1. 项目概述为什么我们需要在Vite项目中优雅地Mock数据在Vite构建的Vue3项目中前端开发与后端API开发往往是并行的。如果前端开发必须等待后端接口完全就绪才能进行那项目进度就会像堵车一样停滞不前。这时候Mock数据就成了我们前端开发者的“救命稻草”。它允许我们在本地模拟出后端接口的请求与响应让前端逻辑开发、组件测试和界面联调可以独立进行极大地提升了开发效率。然而Mock数据的引入方式五花八门。最原始的是在代码里写死一个对象但这无法模拟网络请求的异步过程进阶一点的是拦截axios或fetch的请求在浏览器层面做手脚而更现代、更贴近工程化实践的方式则是利用构建工具在开发服务器层面进行拦截。vite-plugin-mock插件正是为Vite量身定制的后者。它通过在本地启动一个Mock服务器无缝拦截并处理特定的HTTP请求返回我们预设的模拟数据。这种方式的好处是它模拟了真实的网络请求环境包括请求方法、路径、参数和延迟使得我们的开发体验更接近真实联调。但正如任何工具都有其复杂性vite-plugin-mock在带来便利的同时也伴随着一些配置上的“坑”。这些坑可能源于对Vite插件机制的不熟悉、对ES模块与CommonJS模块差异的忽视或是插件版本与项目环境的不兼容。接下来我将结合一个具体的Vue3 Vite项目从头到尾拆解如何使用vite-plugin-mock并重点分享我踩过的那些坑以及如何优雅地填平它们。2. 环境准备与项目初始化2.1 创建Vue3 Vite项目首先我们使用官方推荐的方式创建一个新的Vite项目。打开终端执行以下命令npm create vitelatest my-vue-mock-app -- --template vue这条命令会使用最新的Vite脚手架创建一个名为my-vue-mock-app的项目并选择Vue作为模板。创建完成后进入项目目录并安装基础依赖cd my-vue-mock-app npm install此时一个最基础的Vue3 Vite项目就准备好了。你可以运行npm run dev来启动开发服务器验证项目是否正常运行。2.2 安装核心依赖vite-plugin-mock接下来安装我们本次的核心插件vite-plugin-mock及其运行时依赖mockjs。mockjs是一个功能强大的数据模拟库可以生成各种随机数据并定义数据模板。npm install vite-plugin-mock mockjs -D这里使用-D即--save-dev将其安装为开发依赖因为Mock数据通常只在开发环境下使用。生产环境构建时这些代码不应该被打包进去。第一个坑版本兼容性问题。vite-plugin-mock的不同大版本对Vite和Node.js的版本有不同要求。例如vite-plugin-mock3.x 版本需要 Vite 4.x 及以上。在安装时如果不指定版本npm会安装最新版。如果遇到启动报错可以尝试指定一个稳定的版本。例如在撰写本文时一个广泛使用的稳定版本是2.9.6。npm install vite-plugin-mock2.9.6 mockjs -D安装完成后建议检查package.json中vite和vite-plugin-mock的版本确保它们兼容。你可以在插件的GitHub仓库或npm页面查看其版本要求。3. 基础配置与Mock文件编写3.1 配置Vite插件安装好插件后我们需要在Vite的配置文件vite.config.js或vite.config.ts中引入并配置它。打开vite.config.js进行如下配置import { defineConfig } from vite import vue from vitejs/plugin-vue import { viteMockServe } from vite-plugin-mock // 引入插件 // https://vitejs.dev/config/ export default defineConfig({ plugins: [ vue(), // 配置vite-plugin-mock viteMockServe({ supportTs: false, // 如果使用TS编写Mock文件设为true logger: false, // 是否在控制台显示请求日志 mockPath: ./src/mock, // Mock文件存放的目录 localEnabled: true, // 开发环境是否开启Mock prodEnabled: false, // 生产环境是否开启绝对不要设为true injectCode: import { setupProdMockServer } from ../src/mock; setupProdMockServer(); , // 如果需要在生产环境也开启仅用于演示切勿用于真实生产环境需要注入这段代码。通常我们保持 prodEnabled: false。 }) ] })关键配置项解析mockPath: 指定你的Mock数据文件存放的根目录。插件会读取这个目录下的所有.js或.ts文件作为Mock配置。localEnabled: 控制开发服务器是否启用Mock功能。一般设为true。prodEnabled:这是个大坑务必设为false。Mock数据绝对不应该出现在生产环境的代码包中否则会暴露模拟接口甚至可能引发安全问题。生产环境必须使用真实的后端API。supportTs: 如果你的Mock文件是用TypeScript编写的例如user.ts需要将此选项设为true插件会使用esbuild进行实时编译。injectCode: 一段会在生产环境构建时被注入的代码。仅当prodEnabled: true时才有用。强烈不建议在生产环境开启Mock所以这个配置通常可以忽略或留空。3.2 编写第一个Mock接口根据上面的配置我们在项目根目录下创建src/mock文件夹并在其中创建第一个Mock文件例如user.js。// src/mock/user.js import Mock from mockjs // 模拟用户登录接口 export default [ { url: /api/login, // 匹配的请求路径 method: post, // 请求方法 timeout: 500, // 模拟网络延迟单位毫秒 response: ({ body }) { // body是请求体 const { username, password } body // 简单的模拟验证 if (username admin password 123456) { return { code: 200, message: 登录成功, data: { token: Mock.Random.guid(), // 使用mockjs生成一个随机token userInfo: { id: Mock.Random.id(), name: username, avatar: Mock.Random.image(100x100) } } } } else { return { code: 401, message: 用户名或密码错误, data: null } } } }, { url: /api/user/info, method: get, response: () { return { code: 200, message: success, data: { userId: Mock.Random.id(), userName: Mock.Random.cname(), email: Mock.Random.email(), roles: [admin] } } } } ]第二个坑路径匹配规则。注意url字段是/api/login。在Vite开发服务器中默认所有请求都会代理到该服务器。如果你的真实后端接口也有/api前缀那么Mock和真实接口的路径就冲突了。常见的做法是在Vite配置中为真实API配置一个代理而Mock接口使用另一个前缀或者直接让Mock接口覆盖开发服务器的特定路径。vite-plugin-mock默认会拦截并优先处理匹配到的请求。如果请求的路径在Mock配置中被找到就会被拦截并返回模拟数据如果没找到请求会继续向下转发例如转发到你配置的proxy代理的后端服务器。3.3 在组件中调用Mock接口现在我们可以在Vue组件中发起请求来测试Mock接口了。首先安装一个HTTP客户端库例如axios。npm install axios然后在一个Vue组件例如src/components/HelloWorld.vue中编写如下代码template div button clickhandleLogin测试登录Mock接口/button button clickgetUserInfo获取用户信息/button div v-ifresult{{ result }}/div /div /template script setup import { ref } from vue import axios from axios const result ref() const handleLogin async () { try { const res await axios.post(/api/login, { username: admin, password: 123456 }) result.value 登录成功: ${JSON.stringify(res.data)} // 假设token存储在本地 localStorage.setItem(token, res.data.data.token) } catch (error) { result.value 登录失败: ${error.message} } } const getUserInfo async () { try { // 假设接口需要token认证从localStorage读取 const token localStorage.getItem(token) const res await axios.get(/api/user/info, { headers: { Authorization: Bearer ${token} } }) result.value 用户信息: ${JSON.stringify(res.data)} } catch (error) { result.value 获取信息失败: ${error.message} } } /script启动开发服务器(npm run dev)点击按钮你应该能看到来自Mock接口的返回数据并且在浏览器开发者工具的Network标签页中能看到对这些/api/xxx路径的请求。4. 高级用法与工程化实践4.1 模块化组织Mock文件当项目变大接口数量增多时把所有接口写在一个文件里是难以维护的。我们可以将Mock文件按业务模块拆分。src/mock/ ├── index.js // 入口文件汇总所有模块 ├── user.js // 用户相关接口 ├── product.js // 商品相关接口 └── order.js // 订单相关接口在src/mock/index.js中我们汇总所有模块// src/mock/index.js import user from ./user import product from ./product import order from ./order // 使用数组的concat方法或者扩展运算符合并所有接口配置 const mocks [...user, ...product, ...order] export default mocks然后需要修改vite.config.js中的配置让插件知道入口文件在哪里。vite-plugin-mock的mockPath配置指向的是目录它会自动读取目录下的所有文件。如果我们有了一个统一的index.js也可以保持原配置不变因为插件会递归读取目录。但为了更清晰的控制我们可以使用ignore选项来排除不需要的文件。更优雅的方式是使用插件的mockPath直接指向一个文件实际上vite-plugin-mock的mockPath设计是用来指向一个目录的。它内部会使用glob来匹配该目录下的文件。所以模块化拆分后保持mockPath: ./src/mock即可它会自动加载user.jsproduct.js等。4.2 使用TypeScript编写Mock文件如果你使用TypeScript可以获得更好的类型提示。首先确保vite.config.ts中supportTs: true。然后将user.js重命名为user.ts// src/mock/user.ts import Mock from mockjs import { MockMethod } from vite-plugin-mock // 导入类型定义 interface LoginBody { username: string password: string } interface UserInfo { id: string name: string avatar: string } const userMocks: MockMethod[] [ { url: /api/login, method: post, timeout: 500, response: ({ body }: { body: LoginBody }) { const { username, password } body if (username admin password 123456) { return { code: 200, message: 登录成功, data: { token: Mock.Random.guid(), userInfo: { id: Mock.Random.id(), name: username, avatar: Mock.Random.image(100x100) } as UserInfo } } } else { return { code: 401, message: 用户名或密码错误, data: null } } } } // ... 其他接口 ] export default userMocks第三个坑TypeScript类型声明。你可能会遇到Cannot find module vite-plugin-mock or its corresponding type declarations的错误。这是因为vite-plugin-mock包内可能没有自带TypeScript类型定义文件.d.ts。解决方案是在项目根目录创建一个类型声明文件例如types/vite-plugin-mock.d.ts。手动声明模块// types/vite-plugin-mock.d.ts declare module vite-plugin-mock { export interface MockMethod { url: string method?: get | post | put | delete | patch timeout?: number statusCode?: number response: (opt: { [key: string]: any; body: Recordstring,any; query: Recordstring,any; headers: Recordstring,any }) any } }然后在tsconfig.json的include字段中包含这个types目录。4.3 模拟更复杂的场景动态参数、文件上传Mock不仅可以返回静态数据还可以根据请求参数动态响应。动态路由参数假设有一个获取特定用户详情的接口路径为/api/user/:id。// 在 user.js 中增加 { url: /api/user/:id, // 使用 :id 捕获动态参数 method: get, response: ({ query }) { // 注意动态参数在 query 对象中 这里有个坑 // 实际上对于 /api/user/123 这样的路径参数 123 在插件的上下文中可能位于 params 或 query。 // vite-plugin-mock 的早期版本可能处理方式不同。更可靠的方式是使用函数参数解构。 // 查看插件文档或源码或者通过 console.log 打印整个参数对象来确定。 console.log(query) // 打印看看 // 假设我们通过打印发现 id 在 params 里 return { code: 200, data: { id: query.id, // 或者 params.id name: Mock.Random.cname() } } } }第四个坑请求参数的获取位置。对于RESTful风格的动态路径参数如/api/user/123vite-plugin-mock是如何解析的根据其实现这类参数通常会被解析到传入response函数的对象的query属性中吗不一定。有些插件或服务器框架会将其放在params里。最稳妥的方法是在response函数里先打印整个传入的参数对象确认数据结构。response: (req) { console.log(完整的请求对象:, req) // req 可能包含: url, method, body, query, headers // 动态路径参数如 :id 可能在 req.query 中也可能被解析到 req.params // 需要根据打印结果调整 const userId req.query.id || req.params.id return { ... } }模拟文件上传接口模拟文件上传的响应虽然不能真的处理文件流但可以模拟成功或失败的响应。{ url: /api/upload, method: post, timeout: 1000, // 模拟上传耗时 response: () { // 模拟一个成功的上传响应 return { code: 200, message: 上传成功, data: { url: Mock.Random.image(800x600), fileName: uploaded_image.png } } } }在组件中你可以使用FormData来模拟上传请求即使后端是Mock的也能测试前端的上传逻辑。5. 深度踩坑与疑难排查5.1 热更新HMR失效问题当你修改了src/mock目录下的.js或.ts文件后期望Vite的热更新能生效即修改Mock接口后无需重启开发服务器。但有时会发现修改并未生效。原因与解决方案检查文件路径和配置确保vite.config.js中的mockPath配置指向了正确的目录并且你的Mock文件确实位于该目录下。检查文件扩展名vite-plugin-mock默认会读取.js.ts.jsx.tsx文件。如果你使用了其他扩展名如.json需要检查插件是否支持或者通过配置include选项来指定。Vite缓存Vite的依赖预构建或缓存有时会导致模块没有被重新加载。尝试以下方法在Vite配置中为viteMockServe添加watchFiles选项显式指定要监听的目录或文件。viteMockServe({ // ... 其他配置 watchFiles: [./src/mock/**/*.js, ./src/mock/**/*.ts] // 明确指定监听的文件模式 })更直接的方法是手动重启开发服务器CtrlC然后npm run dev。插件内部实现某些旧版本插件可能存在HMR支持不完善的问题。升级到最新稳定版通常能解决。5.2 生产环境构建报错即使你在配置中设置了prodEnabled: false在运行npm run build时仍然可能遇到与Mock相关的错误。典型错误[vite]: Rollup failed to resolve import mockjs from src/mock/user.js.原因分析这是因为在构建时ViteRollup会静态分析你的源代码依赖。虽然vite-plugin-mock在生产构建时理论上不会注入Mock服务器代码但如果你在某个非Mock文件例如main.js或某个组件中直接导入了Mock文件或mockjs库Rollup仍然会尝试打包它。但由于mockjs是开发依赖并且生产环境不需要这就会导致构建失败。解决方案隔离Mock代码确保Mock相关的导入语句仅存在于src/mock/目录下的文件中。不要在业务组件、工具函数或Vue入口文件中直接import它们。使用环境变量条件导入不推荐用于Mock虽然可以通过import.meta.env.DEV来判断但动态导入可能会让代码分割和Tree Shaking复杂化对于Mock这种纯开发时工具最好的做法就是物理隔离。检查Vite配置确认vite.config.js中的prodEnabled为false并且没有通过injectCode注入任何生产环境Mock代码。终极方案在构建时排除Mock目录。在vite.config.js中你可以配置build.rollupOptions.external告诉Rollup将Mock相关的模块视为外部依赖不打包。// vite.config.js export default defineConfig(({ command, mode }) { const isBuild command build return { plugins: [ viteMockServe({ localEnabled: !isBuild, // 开发环境开启 prodEnabled: false, // 生产环境绝对关闭 // ... 其他配置 }) ], build: { rollupOptions: { // 在生产构建时排除mock相关模块 external: isBuild ? [/^mockjs/, /^\.\/mock/] : [] } } } })这个配置会在构建时将任何以mockjs开头或路径以./mock开头的导入视为外部模块从而避免打包错误。5.3 与后端API代理Proxy的冲突在实际项目中开发环境通常需要代理部分请求到真正的后端服务器。Vite通过server.proxy配置实现。这就可能和Mock接口产生路径冲突。场景你配置了/api前缀的请求走Mock但同时又将/api代理到了真实的后端地址http://localhost:3000。Vite配置示例// vite.config.js export default defineConfig({ server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, // rewrite: (path) path.replace(/^\/api/, ) // 可选重写路径 } } }, plugins: [ viteMockServe({ mockPath: ./src/mock, localEnabled: true, }) ] })冲突结果一个发往/api/login的请求到底是被Mock拦截了还是被代理到了http://localhost:3000/api/loginvite-plugin-mock的工作机制该插件作为一个Vite插件会注册一个中间件到Vite的开发服务器。这个中间件的优先级通常高于server.proxy配置的代理规则。这意味着如果Mock配置中定义了/api/login请求就会被Mock拦截并返回模拟数据如果Mock中没有定义这个路径请求才会继续向下传递最终可能被server.proxy规则代理到后端服务器。最佳实践路径规划为了避免混淆建议对Mock接口和真实接口进行清晰的路径规划方案A推荐为Mock接口使用一个特定的、不会与真实接口冲突的前缀例如/mock-api。修改所有Mock配置中的url如url: /mock-api/login。这样所有以/mock-api开头的请求走Mock而以/api开头的请求走代理到真实后端。方案B保持Mock接口路径与真实接口路径一致如都是/api但利用Mock的优先级只在需要Mock的接口上配置Mock规则其他接口自然会被代理到后端。这要求你清晰地知道哪些接口已Mock哪些未Mock。我个人更倾向于方案A因为它职责清晰在代码中一眼就能看出哪些请求是访问Mock数据便于后期联调时批量替换为真实接口地址。5.4 模拟网络错误和超时真实的网络环境并不总是成功的。我们需要测试前端代码对网络异常的处理能力。模拟请求超时在Mock配置中timeout字段可以模拟网络延迟。如果你想模拟一个超时错误可以将timeout设为一个大于浏览器或axios超时时间的值。{ url: /api/slow, method: get, timeout: 10000, // 10秒假设axios配置的超时时间是5秒 response: () { return { message: 本应超时你不会看到这条消息 } } }这样前端请求会在5秒后因超时而失败触发catch逻辑。模拟HTTP错误状态码vite-plugin-mock允许你直接返回状态码和状态文本。{ url: /api/error/500, method: get, statusCode: 500, // 直接设置HTTP状态码 response: () { return { code: 50000, message: 服务器内部错误模拟 } } } { url: /api/error/404, method: get, statusCode: 404, response: () { return { code: 40400, message: 资源不存在模拟 } } }在axios中默认情况下HTTP状态码不在2xx范围内会触发catch。你可以利用这一点来测试你的错误处理UI。6. 性能优化与最佳实践总结6.1 按需启用Mock在大型项目中Mock文件可能很多。全部加载可能会轻微影响开发服务器的启动速度。我们可以通过环境变量或Vite的模式mode来控制哪些Mock模块被启用。一种简单的实现方式是在src/mock/index.js中动态导入// src/mock/index.js const modules import.meta.glob(./modules/*.js, { eager: true }) // 使用Vite的glob导入 let allMocks [] // 假设我们通过环境变量 VITE_MOCK_MODULES 来控制例如 VITE_MOCK_MODULESuser,product const enabledModules import.meta.env.VITE_MOCK_MODULES ? import.meta.env.VITE_MOCK_MODULES.split(,) : [] Object.keys(modules).forEach(key { const moduleName key.replace(./modules/, ).replace(.js, ) if (enabledModules.length 0 || enabledModules.includes(moduleName)) { allMocks allMocks.concat(modules[key].default || modules[key]) } }) export default allMocks然后在项目根目录创建.env.development文件VITE_MOCK_MODULESuser,order这样只有user和order模块的Mock会被加载。你可以通过修改这个变量来快速切换Mock场景。6.2 保持Mock数据的真实性Mock数据不应过于随意。尽量让生成的数据符合业务逻辑和字段类型这有助于提前发现前后端数据格式约定不一致的问题。使用mockjs的随机数据生成功能如Mock.Random.cname()中文名、Mock.Random.float()浮点数。对于枚举值从真实的枚举列表中随机选取。对于关联数据如订单包含商品列表保持ID的对应关系。6.3 制定团队Mock规范在团队协作中建议制定统一的Mock规范文件命名按业务模块命名如user.mock.js或user.js放在mock/modules目录下。接口格式统一响应体格式例如{ code: number, message: string, data: any }。路径规范统一使用前缀如/mock-api/v1/。文档化可以考虑使用类似swagger或apidoc的格式注释Mock文件甚至可以通过脚本自动生成简单的接口文档。6.4 平滑切换到真实接口当后端接口开发完成后我们需要从Mock平滑地切换到真实接口。如果之前采用了方案A使用独立Mock前缀那么切换工作就非常简单修改全局的请求基地址例如在axios的实例配置中从/mock-api改为后端的真实地址如http://api.yourdomain.com。或者修改Vite的server.proxy配置将/mock-api代理到真实后端而不再使用本地Mock。如果采用了方案B路径一致则需要逐个检查Mock配置并确保在构建生产包时所有Mock代码已被完全排除且前端请求的基地址已正确指向生产环境API。最后也是最重要的提醒在运行npm run build构建生产包之前务必再三确认你的代码中没有残留任何对Mock文件的直接引用并且vite-plugin-mock的prodEnabled选项为false。最好的实践是在CI/CD流水线中构建生产环境镜像时确保环境变量NODE_ENVproduction并且构建命令不会包含任何Mock相关的步骤。Mock是强大的开发辅助工具但让它出现在线上环境则可能是一个严重的错误。 Vite项目中优雅Mock数据：vite-plugin-mock插件实战与避坑指南
1. 项目概述为什么我们需要在Vite项目中优雅地Mock数据在Vite构建的Vue3项目中前端开发与后端API开发往往是并行的。如果前端开发必须等待后端接口完全就绪才能进行那项目进度就会像堵车一样停滞不前。这时候Mock数据就成了我们前端开发者的“救命稻草”。它允许我们在本地模拟出后端接口的请求与响应让前端逻辑开发、组件测试和界面联调可以独立进行极大地提升了开发效率。然而Mock数据的引入方式五花八门。最原始的是在代码里写死一个对象但这无法模拟网络请求的异步过程进阶一点的是拦截axios或fetch的请求在浏览器层面做手脚而更现代、更贴近工程化实践的方式则是利用构建工具在开发服务器层面进行拦截。vite-plugin-mock插件正是为Vite量身定制的后者。它通过在本地启动一个Mock服务器无缝拦截并处理特定的HTTP请求返回我们预设的模拟数据。这种方式的好处是它模拟了真实的网络请求环境包括请求方法、路径、参数和延迟使得我们的开发体验更接近真实联调。但正如任何工具都有其复杂性vite-plugin-mock在带来便利的同时也伴随着一些配置上的“坑”。这些坑可能源于对Vite插件机制的不熟悉、对ES模块与CommonJS模块差异的忽视或是插件版本与项目环境的不兼容。接下来我将结合一个具体的Vue3 Vite项目从头到尾拆解如何使用vite-plugin-mock并重点分享我踩过的那些坑以及如何优雅地填平它们。2. 环境准备与项目初始化2.1 创建Vue3 Vite项目首先我们使用官方推荐的方式创建一个新的Vite项目。打开终端执行以下命令npm create vitelatest my-vue-mock-app -- --template vue这条命令会使用最新的Vite脚手架创建一个名为my-vue-mock-app的项目并选择Vue作为模板。创建完成后进入项目目录并安装基础依赖cd my-vue-mock-app npm install此时一个最基础的Vue3 Vite项目就准备好了。你可以运行npm run dev来启动开发服务器验证项目是否正常运行。2.2 安装核心依赖vite-plugin-mock接下来安装我们本次的核心插件vite-plugin-mock及其运行时依赖mockjs。mockjs是一个功能强大的数据模拟库可以生成各种随机数据并定义数据模板。npm install vite-plugin-mock mockjs -D这里使用-D即--save-dev将其安装为开发依赖因为Mock数据通常只在开发环境下使用。生产环境构建时这些代码不应该被打包进去。第一个坑版本兼容性问题。vite-plugin-mock的不同大版本对Vite和Node.js的版本有不同要求。例如vite-plugin-mock3.x 版本需要 Vite 4.x 及以上。在安装时如果不指定版本npm会安装最新版。如果遇到启动报错可以尝试指定一个稳定的版本。例如在撰写本文时一个广泛使用的稳定版本是2.9.6。npm install vite-plugin-mock2.9.6 mockjs -D安装完成后建议检查package.json中vite和vite-plugin-mock的版本确保它们兼容。你可以在插件的GitHub仓库或npm页面查看其版本要求。3. 基础配置与Mock文件编写3.1 配置Vite插件安装好插件后我们需要在Vite的配置文件vite.config.js或vite.config.ts中引入并配置它。打开vite.config.js进行如下配置import { defineConfig } from vite import vue from vitejs/plugin-vue import { viteMockServe } from vite-plugin-mock // 引入插件 // https://vitejs.dev/config/ export default defineConfig({ plugins: [ vue(), // 配置vite-plugin-mock viteMockServe({ supportTs: false, // 如果使用TS编写Mock文件设为true logger: false, // 是否在控制台显示请求日志 mockPath: ./src/mock, // Mock文件存放的目录 localEnabled: true, // 开发环境是否开启Mock prodEnabled: false, // 生产环境是否开启绝对不要设为true injectCode: import { setupProdMockServer } from ../src/mock; setupProdMockServer(); , // 如果需要在生产环境也开启仅用于演示切勿用于真实生产环境需要注入这段代码。通常我们保持 prodEnabled: false。 }) ] })关键配置项解析mockPath: 指定你的Mock数据文件存放的根目录。插件会读取这个目录下的所有.js或.ts文件作为Mock配置。localEnabled: 控制开发服务器是否启用Mock功能。一般设为true。prodEnabled:这是个大坑务必设为false。Mock数据绝对不应该出现在生产环境的代码包中否则会暴露模拟接口甚至可能引发安全问题。生产环境必须使用真实的后端API。supportTs: 如果你的Mock文件是用TypeScript编写的例如user.ts需要将此选项设为true插件会使用esbuild进行实时编译。injectCode: 一段会在生产环境构建时被注入的代码。仅当prodEnabled: true时才有用。强烈不建议在生产环境开启Mock所以这个配置通常可以忽略或留空。3.2 编写第一个Mock接口根据上面的配置我们在项目根目录下创建src/mock文件夹并在其中创建第一个Mock文件例如user.js。// src/mock/user.js import Mock from mockjs // 模拟用户登录接口 export default [ { url: /api/login, // 匹配的请求路径 method: post, // 请求方法 timeout: 500, // 模拟网络延迟单位毫秒 response: ({ body }) { // body是请求体 const { username, password } body // 简单的模拟验证 if (username admin password 123456) { return { code: 200, message: 登录成功, data: { token: Mock.Random.guid(), // 使用mockjs生成一个随机token userInfo: { id: Mock.Random.id(), name: username, avatar: Mock.Random.image(100x100) } } } } else { return { code: 401, message: 用户名或密码错误, data: null } } } }, { url: /api/user/info, method: get, response: () { return { code: 200, message: success, data: { userId: Mock.Random.id(), userName: Mock.Random.cname(), email: Mock.Random.email(), roles: [admin] } } } } ]第二个坑路径匹配规则。注意url字段是/api/login。在Vite开发服务器中默认所有请求都会代理到该服务器。如果你的真实后端接口也有/api前缀那么Mock和真实接口的路径就冲突了。常见的做法是在Vite配置中为真实API配置一个代理而Mock接口使用另一个前缀或者直接让Mock接口覆盖开发服务器的特定路径。vite-plugin-mock默认会拦截并优先处理匹配到的请求。如果请求的路径在Mock配置中被找到就会被拦截并返回模拟数据如果没找到请求会继续向下转发例如转发到你配置的proxy代理的后端服务器。3.3 在组件中调用Mock接口现在我们可以在Vue组件中发起请求来测试Mock接口了。首先安装一个HTTP客户端库例如axios。npm install axios然后在一个Vue组件例如src/components/HelloWorld.vue中编写如下代码template div button clickhandleLogin测试登录Mock接口/button button clickgetUserInfo获取用户信息/button div v-ifresult{{ result }}/div /div /template script setup import { ref } from vue import axios from axios const result ref() const handleLogin async () { try { const res await axios.post(/api/login, { username: admin, password: 123456 }) result.value 登录成功: ${JSON.stringify(res.data)} // 假设token存储在本地 localStorage.setItem(token, res.data.data.token) } catch (error) { result.value 登录失败: ${error.message} } } const getUserInfo async () { try { // 假设接口需要token认证从localStorage读取 const token localStorage.getItem(token) const res await axios.get(/api/user/info, { headers: { Authorization: Bearer ${token} } }) result.value 用户信息: ${JSON.stringify(res.data)} } catch (error) { result.value 获取信息失败: ${error.message} } } /script启动开发服务器(npm run dev)点击按钮你应该能看到来自Mock接口的返回数据并且在浏览器开发者工具的Network标签页中能看到对这些/api/xxx路径的请求。4. 高级用法与工程化实践4.1 模块化组织Mock文件当项目变大接口数量增多时把所有接口写在一个文件里是难以维护的。我们可以将Mock文件按业务模块拆分。src/mock/ ├── index.js // 入口文件汇总所有模块 ├── user.js // 用户相关接口 ├── product.js // 商品相关接口 └── order.js // 订单相关接口在src/mock/index.js中我们汇总所有模块// src/mock/index.js import user from ./user import product from ./product import order from ./order // 使用数组的concat方法或者扩展运算符合并所有接口配置 const mocks [...user, ...product, ...order] export default mocks然后需要修改vite.config.js中的配置让插件知道入口文件在哪里。vite-plugin-mock的mockPath配置指向的是目录它会自动读取目录下的所有文件。如果我们有了一个统一的index.js也可以保持原配置不变因为插件会递归读取目录。但为了更清晰的控制我们可以使用ignore选项来排除不需要的文件。更优雅的方式是使用插件的mockPath直接指向一个文件实际上vite-plugin-mock的mockPath设计是用来指向一个目录的。它内部会使用glob来匹配该目录下的文件。所以模块化拆分后保持mockPath: ./src/mock即可它会自动加载user.jsproduct.js等。4.2 使用TypeScript编写Mock文件如果你使用TypeScript可以获得更好的类型提示。首先确保vite.config.ts中supportTs: true。然后将user.js重命名为user.ts// src/mock/user.ts import Mock from mockjs import { MockMethod } from vite-plugin-mock // 导入类型定义 interface LoginBody { username: string password: string } interface UserInfo { id: string name: string avatar: string } const userMocks: MockMethod[] [ { url: /api/login, method: post, timeout: 500, response: ({ body }: { body: LoginBody }) { const { username, password } body if (username admin password 123456) { return { code: 200, message: 登录成功, data: { token: Mock.Random.guid(), userInfo: { id: Mock.Random.id(), name: username, avatar: Mock.Random.image(100x100) } as UserInfo } } } else { return { code: 401, message: 用户名或密码错误, data: null } } } } // ... 其他接口 ] export default userMocks第三个坑TypeScript类型声明。你可能会遇到Cannot find module vite-plugin-mock or its corresponding type declarations的错误。这是因为vite-plugin-mock包内可能没有自带TypeScript类型定义文件.d.ts。解决方案是在项目根目录创建一个类型声明文件例如types/vite-plugin-mock.d.ts。手动声明模块// types/vite-plugin-mock.d.ts declare module vite-plugin-mock { export interface MockMethod { url: string method?: get | post | put | delete | patch timeout?: number statusCode?: number response: (opt: { [key: string]: any; body: Recordstring,any; query: Recordstring,any; headers: Recordstring,any }) any } }然后在tsconfig.json的include字段中包含这个types目录。4.3 模拟更复杂的场景动态参数、文件上传Mock不仅可以返回静态数据还可以根据请求参数动态响应。动态路由参数假设有一个获取特定用户详情的接口路径为/api/user/:id。// 在 user.js 中增加 { url: /api/user/:id, // 使用 :id 捕获动态参数 method: get, response: ({ query }) { // 注意动态参数在 query 对象中 这里有个坑 // 实际上对于 /api/user/123 这样的路径参数 123 在插件的上下文中可能位于 params 或 query。 // vite-plugin-mock 的早期版本可能处理方式不同。更可靠的方式是使用函数参数解构。 // 查看插件文档或源码或者通过 console.log 打印整个参数对象来确定。 console.log(query) // 打印看看 // 假设我们通过打印发现 id 在 params 里 return { code: 200, data: { id: query.id, // 或者 params.id name: Mock.Random.cname() } } } }第四个坑请求参数的获取位置。对于RESTful风格的动态路径参数如/api/user/123vite-plugin-mock是如何解析的根据其实现这类参数通常会被解析到传入response函数的对象的query属性中吗不一定。有些插件或服务器框架会将其放在params里。最稳妥的方法是在response函数里先打印整个传入的参数对象确认数据结构。response: (req) { console.log(完整的请求对象:, req) // req 可能包含: url, method, body, query, headers // 动态路径参数如 :id 可能在 req.query 中也可能被解析到 req.params // 需要根据打印结果调整 const userId req.query.id || req.params.id return { ... } }模拟文件上传接口模拟文件上传的响应虽然不能真的处理文件流但可以模拟成功或失败的响应。{ url: /api/upload, method: post, timeout: 1000, // 模拟上传耗时 response: () { // 模拟一个成功的上传响应 return { code: 200, message: 上传成功, data: { url: Mock.Random.image(800x600), fileName: uploaded_image.png } } } }在组件中你可以使用FormData来模拟上传请求即使后端是Mock的也能测试前端的上传逻辑。5. 深度踩坑与疑难排查5.1 热更新HMR失效问题当你修改了src/mock目录下的.js或.ts文件后期望Vite的热更新能生效即修改Mock接口后无需重启开发服务器。但有时会发现修改并未生效。原因与解决方案检查文件路径和配置确保vite.config.js中的mockPath配置指向了正确的目录并且你的Mock文件确实位于该目录下。检查文件扩展名vite-plugin-mock默认会读取.js.ts.jsx.tsx文件。如果你使用了其他扩展名如.json需要检查插件是否支持或者通过配置include选项来指定。Vite缓存Vite的依赖预构建或缓存有时会导致模块没有被重新加载。尝试以下方法在Vite配置中为viteMockServe添加watchFiles选项显式指定要监听的目录或文件。viteMockServe({ // ... 其他配置 watchFiles: [./src/mock/**/*.js, ./src/mock/**/*.ts] // 明确指定监听的文件模式 })更直接的方法是手动重启开发服务器CtrlC然后npm run dev。插件内部实现某些旧版本插件可能存在HMR支持不完善的问题。升级到最新稳定版通常能解决。5.2 生产环境构建报错即使你在配置中设置了prodEnabled: false在运行npm run build时仍然可能遇到与Mock相关的错误。典型错误[vite]: Rollup failed to resolve import mockjs from src/mock/user.js.原因分析这是因为在构建时ViteRollup会静态分析你的源代码依赖。虽然vite-plugin-mock在生产构建时理论上不会注入Mock服务器代码但如果你在某个非Mock文件例如main.js或某个组件中直接导入了Mock文件或mockjs库Rollup仍然会尝试打包它。但由于mockjs是开发依赖并且生产环境不需要这就会导致构建失败。解决方案隔离Mock代码确保Mock相关的导入语句仅存在于src/mock/目录下的文件中。不要在业务组件、工具函数或Vue入口文件中直接import它们。使用环境变量条件导入不推荐用于Mock虽然可以通过import.meta.env.DEV来判断但动态导入可能会让代码分割和Tree Shaking复杂化对于Mock这种纯开发时工具最好的做法就是物理隔离。检查Vite配置确认vite.config.js中的prodEnabled为false并且没有通过injectCode注入任何生产环境Mock代码。终极方案在构建时排除Mock目录。在vite.config.js中你可以配置build.rollupOptions.external告诉Rollup将Mock相关的模块视为外部依赖不打包。// vite.config.js export default defineConfig(({ command, mode }) { const isBuild command build return { plugins: [ viteMockServe({ localEnabled: !isBuild, // 开发环境开启 prodEnabled: false, // 生产环境绝对关闭 // ... 其他配置 }) ], build: { rollupOptions: { // 在生产构建时排除mock相关模块 external: isBuild ? [/^mockjs/, /^\.\/mock/] : [] } } } })这个配置会在构建时将任何以mockjs开头或路径以./mock开头的导入视为外部模块从而避免打包错误。5.3 与后端API代理Proxy的冲突在实际项目中开发环境通常需要代理部分请求到真正的后端服务器。Vite通过server.proxy配置实现。这就可能和Mock接口产生路径冲突。场景你配置了/api前缀的请求走Mock但同时又将/api代理到了真实的后端地址http://localhost:3000。Vite配置示例// vite.config.js export default defineConfig({ server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, // rewrite: (path) path.replace(/^\/api/, ) // 可选重写路径 } } }, plugins: [ viteMockServe({ mockPath: ./src/mock, localEnabled: true, }) ] })冲突结果一个发往/api/login的请求到底是被Mock拦截了还是被代理到了http://localhost:3000/api/loginvite-plugin-mock的工作机制该插件作为一个Vite插件会注册一个中间件到Vite的开发服务器。这个中间件的优先级通常高于server.proxy配置的代理规则。这意味着如果Mock配置中定义了/api/login请求就会被Mock拦截并返回模拟数据如果Mock中没有定义这个路径请求才会继续向下传递最终可能被server.proxy规则代理到后端服务器。最佳实践路径规划为了避免混淆建议对Mock接口和真实接口进行清晰的路径规划方案A推荐为Mock接口使用一个特定的、不会与真实接口冲突的前缀例如/mock-api。修改所有Mock配置中的url如url: /mock-api/login。这样所有以/mock-api开头的请求走Mock而以/api开头的请求走代理到真实后端。方案B保持Mock接口路径与真实接口路径一致如都是/api但利用Mock的优先级只在需要Mock的接口上配置Mock规则其他接口自然会被代理到后端。这要求你清晰地知道哪些接口已Mock哪些未Mock。我个人更倾向于方案A因为它职责清晰在代码中一眼就能看出哪些请求是访问Mock数据便于后期联调时批量替换为真实接口地址。5.4 模拟网络错误和超时真实的网络环境并不总是成功的。我们需要测试前端代码对网络异常的处理能力。模拟请求超时在Mock配置中timeout字段可以模拟网络延迟。如果你想模拟一个超时错误可以将timeout设为一个大于浏览器或axios超时时间的值。{ url: /api/slow, method: get, timeout: 10000, // 10秒假设axios配置的超时时间是5秒 response: () { return { message: 本应超时你不会看到这条消息 } } }这样前端请求会在5秒后因超时而失败触发catch逻辑。模拟HTTP错误状态码vite-plugin-mock允许你直接返回状态码和状态文本。{ url: /api/error/500, method: get, statusCode: 500, // 直接设置HTTP状态码 response: () { return { code: 50000, message: 服务器内部错误模拟 } } } { url: /api/error/404, method: get, statusCode: 404, response: () { return { code: 40400, message: 资源不存在模拟 } } }在axios中默认情况下HTTP状态码不在2xx范围内会触发catch。你可以利用这一点来测试你的错误处理UI。6. 性能优化与最佳实践总结6.1 按需启用Mock在大型项目中Mock文件可能很多。全部加载可能会轻微影响开发服务器的启动速度。我们可以通过环境变量或Vite的模式mode来控制哪些Mock模块被启用。一种简单的实现方式是在src/mock/index.js中动态导入// src/mock/index.js const modules import.meta.glob(./modules/*.js, { eager: true }) // 使用Vite的glob导入 let allMocks [] // 假设我们通过环境变量 VITE_MOCK_MODULES 来控制例如 VITE_MOCK_MODULESuser,product const enabledModules import.meta.env.VITE_MOCK_MODULES ? import.meta.env.VITE_MOCK_MODULES.split(,) : [] Object.keys(modules).forEach(key { const moduleName key.replace(./modules/, ).replace(.js, ) if (enabledModules.length 0 || enabledModules.includes(moduleName)) { allMocks allMocks.concat(modules[key].default || modules[key]) } }) export default allMocks然后在项目根目录创建.env.development文件VITE_MOCK_MODULESuser,order这样只有user和order模块的Mock会被加载。你可以通过修改这个变量来快速切换Mock场景。6.2 保持Mock数据的真实性Mock数据不应过于随意。尽量让生成的数据符合业务逻辑和字段类型这有助于提前发现前后端数据格式约定不一致的问题。使用mockjs的随机数据生成功能如Mock.Random.cname()中文名、Mock.Random.float()浮点数。对于枚举值从真实的枚举列表中随机选取。对于关联数据如订单包含商品列表保持ID的对应关系。6.3 制定团队Mock规范在团队协作中建议制定统一的Mock规范文件命名按业务模块命名如user.mock.js或user.js放在mock/modules目录下。接口格式统一响应体格式例如{ code: number, message: string, data: any }。路径规范统一使用前缀如/mock-api/v1/。文档化可以考虑使用类似swagger或apidoc的格式注释Mock文件甚至可以通过脚本自动生成简单的接口文档。6.4 平滑切换到真实接口当后端接口开发完成后我们需要从Mock平滑地切换到真实接口。如果之前采用了方案A使用独立Mock前缀那么切换工作就非常简单修改全局的请求基地址例如在axios的实例配置中从/mock-api改为后端的真实地址如http://api.yourdomain.com。或者修改Vite的server.proxy配置将/mock-api代理到真实后端而不再使用本地Mock。如果采用了方案B路径一致则需要逐个检查Mock配置并确保在构建生产包时所有Mock代码已被完全排除且前端请求的基地址已正确指向生产环境API。最后也是最重要的提醒在运行npm run build构建生产包之前务必再三确认你的代码中没有残留任何对Mock文件的直接引用并且vite-plugin-mock的prodEnabled选项为false。最好的实践是在CI/CD流水线中构建生产环境镜像时确保环境变量NODE_ENVproduction并且构建命令不会包含任何Mock相关的步骤。Mock是强大的开发辅助工具但让它出现在线上环境则可能是一个严重的错误。