故障排查

本章节帮助你解决在使用 vite-plugin-mock-dev-server 过程中遇到的常见问题。

快速诊断清单

遇到问题时，请按以下顺序检查：

1. ✅ 插件是否正确安装
2. ✅ vite.config.ts 中是否正确配置
3. ✅ Mock 文件是否在正确的目录
4. ✅ 开发服务器是否已重启
5. ✅ 请求路径是否匹配

常见问题

Mock API 没有响应

症状

请求 Mock API 时返回 404 或没有响应。

可能原因及解决方案

1. 插件未正确加载

检查 vite.config.ts：

import { defineConfig } from 'vite'
import { mockDevServerPlugin } from 'vite-plugin-mock-dev-server'

export default defineConfig({
  plugins: [
    // 确保插件已添加
    mockDevServerPlugin()
  ],
  // 确保代理配置正确
  server: {
    proxy: {
      // 插件读取 proxy 配置，匹配 /api 开头的请求
      '/api': 'http://example.com'
    }
  }
})

2. Mock 文件位置错误

默认情况下，插件会查找 mock 目录下的文件：

project-root/
├── mock/                 # Mock 文件目录
│   ├── api.mock.ts
│   └── users.mock.ts
├── src/
└── vite.config.ts

如果使用了自定义目录：

mockDevServerPlugin({
  dir: 'my-mock-folder' // 确保目录存在
})

3. 文件扩展名不匹配

默认只识别以下扩展名：

• .mock.js
• .mock.ts
• .mock.cjs
• .mock.mjs
• .mock.json
• .mock.json5

4. 开发服务器未重启

修改 vite.config.ts 后需要重启开发服务器。

热更新不生效

症状

修改 Mock 文件后，数据没有更新。

解决方案

1. 检查文件是否被监听

开启调试日志查看文件监听状态：

mockDevServerPlugin({
  log: 'debug'
})

2. 检查文件路径

确保修改的文件在配置的 include 范围内：

mockDevServerPlugin({
  include: ['**/*.mock.ts'], // 确保你的文件匹配这个模式
  exclude: ['**/node_modules/**', '**/*.test.mock.ts'] // 确保没有被排除
})

3. 启用页面刷新

热更新仅更新服务端数据，浏览器需要刷新才能看到更新。可以启用热更新时自动刷新浏览器页面：

mockDevServerPlugin({
  reload: true // 修改 Mock 文件后刷新页面
})

路径匹配失败

症状

请求路径与 Mock 配置不匹配。

调试方法

1. 开启调试日志

mockDevServerPlugin({
  log: 'debug'
})

查看控制台输出。

2. 检查路径格式

常见错误：

// ❌ 错误：缺少前导斜杠
export default defineMock({
  url: 'api/users' // 应该是 '/api/users'
})

// ❌ 错误：尾部斜杠不一致
// Mock 配置
url: '/api/users'
// 实际请求
fetch('/api/users/') // 不匹配！

// ✅ 正确
url: '/api/users'
fetch('/api/users') // 匹配

3. 检查前缀配置

如果使用 prefix 配置，确保请求路径以 prefix 开头：

mockDevServerPlugin({
  prefix: ['/api'] // 只拦截 /api 开头的请求
})

// ✅ 会被拦截
fetch('/api/users')

// ❌ 不会被拦截
fetch('/mock/users')

WebSocket 连接失败

症状

WebSocket 连接无法建立或立即断开。

解决方案

1. 检查 WebSocket 前缀配置

mockDevServerPlugin({
  wsPrefix: ['/ws', '/socket.io'] // WebSocket 路径前缀
})

2. 确保没有在 Vite 代理中配置相同路径

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      // ❌ 错误：WebSocket 路径不应该在这里配置
      '/ws': 'http://localhost:8080'
    }
  },
  plugins: [
    mockDevServerPlugin({
      wsPrefix: ['/ws'] // 应该只在这里配置
    })
  ]
})

3. 检查 WebSocket URL 格式

// ✅ 正确
const socket = new WebSocket('ws://localhost:5173/ws/chat')

// ❌ 错误：使用了 http 协议
const wrongSocket = new WebSocket('http://localhost:5173/ws/chat')

Cookie 设置不生效

症状

设置的 Cookie 在浏览器中看不到。

解决方案

1. 检查 Cookie 配置

export default defineMock({
  url: '/api/login',
  cookies: {
    // ✅ 正确：设置 Cookie
    session: ['abc123', {
      httpOnly: true,
      maxAge: 24 * 60 * 60 * 1000 // 24小时，单位是毫秒
    }]
  }
})

2. 检查浏览器安全限制

• Secure 标志要求 HTTPS
• SameSite=Strict 可能阻止跨站请求
• HttpOnly 的 Cookie 在 JavaScript 中不可见

3. 检查请求是否跨域

如果前端和 Mock 服务跨域，需要配置 CORS：

mockDevServerPlugin({
  cors: true // 或详细配置
})

文件上传失败

症状

上传文件时返回 413 或无法解析文件。

解决方案

1. 配置文件大小限制

mockDevServerPlugin({
  formidableOptions: {
    maxFileSize: 10 * 1024 * 1024, // 10MB，默认 5MB
    maxFieldsSize: 10 * 1024 * 1024
  }
})

2. 检查文件保存路径

import path from 'node:path'

mockDevServerPlugin({
  formidableOptions: {
    uploadDir: path.join(process.cwd(), 'uploads'), // 确保目录存在
    keepExtensions: true // 保留文件扩展名
  }
})

3. 检查请求 Content-Type

确保请求头包含正确的 Content-Type：

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

请求体解析失败

症状

无法获取请求体数据或数据格式错误。

解决方案

1. 检查 Content-Type

// 确保请求发送了正确的 Content-Type
fetch('/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json' // 默认为 json 格式，其他格式需指定
  },
  body: JSON.stringify({ name: 'John' })
})

2. 配置请求体大小限制

mockDevServerPlugin({
  bodyParserOptions: {
    jsonLimit: '10mb', // JSON 请求体大小限制
    formLimit: '10mb', // Form 请求体大小限制
    textLimit: '10mb' // Text 请求体大小限制
  }
})

3. 检查请求体格式

export default defineMock({
  url: '/api/users',
  method: 'POST',
  body: (request) => {
    console.log('Request body:', request.body) // 调试用
    return { received: request.body }
  }
})

与后端 API 冲突

症状

Mock API 和真实后端 API 同时存在时发生冲突。

解决方案

配置 Vite 代理

export default defineConfig({
  plugins: [mockDevServerPlugin({ prefix: ['/api'] })],
  server: {
    proxy: {
      // 未匹配到 Mock 的请求转发到后端
      '^/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  }
})

调试技巧

开启详细日志

mockDevServerPlugin({
  log: 'debug' // 'debug' | 'info' | 'warn' | 'error' | 'silent'
})

检查请求详情

export default defineMock({
  url: '/api/debug',
  body: request => ({
    // 查看完整请求信息
    method: request.method,
    url: request.url,
    query: request.query,
    params: request.params,
    body: request.body,
    headers: request.headers,
    cookies: request.getCookie('session')
  })
})

使用浏览器开发者工具

1. Network 面板: 查看请求和响应详情
2. Console 面板: 查看插件日志输出
3. Application 面板: 查看 Cookies 和 LocalStorage

获取帮助

如果以上方法都无法解决你的问题：

1. 查看文档: 仔细阅读相关功能的使用文档
2. 搜索 Issues: 在 GitHub Issues 中搜索类似问题
3. 提交 Issue: 如果确认是 bug，请提交 Issue 并提供：
   • 插件版本
   • Vite 版本
   • Node.js 版本
   • 最小可复现示例
   • 错误日志

已知限制

1. 某些中间件不兼容: 与某些 Vite 插件可能存在冲突