Vite项目Mock数据配置：区分开发与生产环境的完整指南

1. 项目概述：为什么我们需要在Vite项目中配置Mock

如果你正在用Vite开发Vue项目，尤其是在前后端分离的架构下，前端开发进度和后端接口交付进度不一致是常态。这时候，Mock数据就成了前端开发的“生命线”。它能让你在不依赖真实后端接口的情况下，独立开发、调试和测试前端功能，极大地提升了开发效率和体验。

vite-plugin-mock 是目前Vite生态中非常流行的一个Mock插件，它基于 mockjs ，可以让你在本地开发时轻松拦截API请求并返回模拟数据。但很多开发者，包括我自己在项目初期，都踩过一个坑： 如何优雅地区分开发环境和生产环境，确保Mock数据只在本地生效，而不会被打包上线或影响线上逻辑？

这看似简单，实则涉及到Vite插件配置、环境变量判断、构建优化等多个环节。配置不当，轻则导致线上请求被意外拦截，出现诡异的数据；重则可能将Mock服务暴露到生产环境，引发安全风险。今天，我就结合自己多个Vue3 + Vite项目的实战经验，从头到尾拆解 vite-plugin-mock 在开发与生产环境下的完整配置方案，分享那些官方文档里没写的细节和避坑指南。

2. 核心思路与方案选型：不止于开箱即用

vite-plugin-mock 插件本身提供了开箱即用的能力，你只需要安装、配置，它就能在开发服务器（dev server）运行时拦截请求。但生产环境的构建（build）过程是静态的，我们绝对不希望任何Mock逻辑被打包进去。因此，我们的核心思路是： 利用Vite的环境变量，对插件进行条件式启用和配置。

2.1 环境变量：配置的基石

Vite使用 import.meta.env 来暴露环境变量。默认情况下，它提供了几个模式（mode）：

• development : 用于 vite serve （开发服务器）。
• production : 用于 vite build （生产构建）。

我们可以在 vite.config.js/ts 中通过 process.env.NODE_ENV 或 import.meta.env.MODE 来获取当前模式。这是实现环境区分的基础。

2.2 方案对比：启用 vs 深度集成

根据项目复杂度和团队规范，通常有两种配置思路：

1. 简单启用方案 ：在 vite.config.ts 中，根据当前环境变量，决定是否引入并配置 vite-plugin-mock 插件。这是最直接、最常用的方法。
2. 深度集成方案 ：除了条件启用插件，还将Mock数据的定义与业务代码进行一定程度的解耦。例如，将Mock API的路径规则集中管理，或者将Mock响应数据与TypeScript类型定义结合，以获得更好的类型提示和代码维护性。

对于大多数项目，方案一已经完全够用。方案二更适合大型、长期维护、对前端数据模型有严格定义的项目。本文将重点讲解方案一，并在高级技巧部分提及方案二的思路。

2.3 工具选型：为什么是 vite-plugin-mock ？

市面上Mock方案很多，比如直接使用 mockjs 在代码中拦截，或者使用 axios-mock-adapter 。选择 vite-plugin-mock 主要基于以下几点：

• 与Vite深度集成 ：作为Vite插件，它直接工作在Vite开发服务器层面，拦截请求的时机更早，对业务代码无侵入。
• 开发体验好 ：支持热更新（HMR），修改Mock文件后，无需重启开发服务器。
• 配置灵活 ：支持ES模块和CommonJS，可以方便地组织大量的Mock文件。
• 社区活跃 ：作为Vite官方生态的推荐插件之一，更新和维护有保障。

3. 详细配置步骤与实操要点

接下来，我们一步步实现一个健壮的、区分环境的Mock配置。假设我们有一个标准的Vue3 + TypeScript + Vite项目。

3.1 第一步：安装依赖

首先，安装核心依赖。

npm install mockjs vite-plugin-mock -D
# 或
yarn add mockjs vite-plugin-mock -D
# 或
pnpm add mockjs vite-plugin-mock -D

这里 -D 表示作为开发依赖安装，这很重要，因为它确保了 mockjs 和 vite-plugin-mock 不会被打包到最终的生产环境代码中。

3.2 第二步：创建Mock数据文件

在项目根目录下创建一个 mock 文件夹，用于存放所有Mock数据文件。这样的结构清晰，便于管理。

your-vite-project/
├── src/
├── mock/                 # Mock数据目录
│   ├── index.ts          # Mock入口文件，集中导出所有接口
│   ├── user.ts           # 用户相关接口Mock
│   └── product.ts        # 产品相关接口Mock
├── vite.config.ts
└── package.json

mock/user.ts 示例：

// 引入mockjs，用于生成随机数据
import { MockMethod } from 'vite-plugin-mock';
import { Random } from 'mockjs';

// 定义用户相关的Mock接口
export default [
  {
    // 请求URL
    url: '/api/user/login',
    // 请求方法
    method: 'post',
    // 响应函数，返回模拟数据
    response: () => {
      return {
        code: 200,
        message: 'success',
        data: {
          token: Random.string(32), // 生成32位随机字符串作为token
          userId: Random.id(),
          userName: Random.cname(), // 随机中文名
        },
      };
    },
  },
  {
    url: '/api/user/info',
    method: 'get',
    // 响应函数可以接收请求参数
    response: (req) => {
      const { userId } = req.query;
      return {
        code: 200,
        message: 'success',
        data: {
          userId,
          userName: Random.cname(),
          avatar: Random.image('100x100', '#4A7BF7', '#FFF', 'Avatar'),
          email: Random.email(),
        },
      };
    },
  },
] as MockMethod[];

mock/index.ts 示例：

// 集中导入并导出所有Mock模块
import userMock from './user';
import productMock from './product';

// 使用展开运算符合并所有Mock配置数组
const mockArray = [...userMock, ...productMock];

export default mockArray;

注意 ： vite-plugin-mock 的 MockMethod 类型定义提供了良好的TypeScript支持。确保每个Mock对象都符合这个类型，可以获得更好的代码提示。

3.3 第三步：配置 vite.config.ts （核心）

这是最关键的一步，我们需要根据环境变量来条件化地配置插件。

vite.config.ts 配置示例：

import { defineConfig, loadEnv } from 'vite';
import vue from '@vitejs/plugin-vue';
import { viteMockServe } from 'vite-plugin-mock';
import type { ConfigEnv, UserConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig(({ command, mode }: ConfigEnv): UserConfig => {
  // 加载环境变量。process.cwd()是项目根目录。
  // 第三个参数''表示加载所有以`VITE_`开头的环境变量，以及`.env`文件中的变量。
  const env = loadEnv(mode, process.cwd(), '');

  return {
    plugins: [
      vue(),
      // 配置 vite-plugin-mock
      viteMockServe({
        // 默认启用Mock。这里通过环境变量进行精细控制。
        enable: command === 'serve' || env.VITE_USE_MOCK === 'true',
        
        // 指定Mock文件入口。相对于项目根目录。
        mockPath: 'mock',
        
        // 是否监视mockPath文件夹下文件的更改，以支持热更新。
        watchFiles: true,
        
        // 生产环境是否启用Mock（极度不推荐！这里仅为演示条件判断）。
        // 通常我们会确保在生产构建时 enable 为 false。
        // prodEnable: env.VITE_USE_MOCK_IN_PROD === 'true', // 危险！请谨慎使用。

        // 是否将请求日志打印到控制台，开发环境调试用。
        logger: true,

        // 如果你的接口有统一的前缀（如`/api`），可以在这里配置，插件会自动处理。
        // 但更推荐在Mock文件的url中直接写完整路径，更清晰。
        // prefix: '/api',
      }),
    ],
    // 配置开发服务器代理，解决跨域问题（可选，但常见）
    server: {
      proxy: {
        // 当请求路径以 `/api` 开头时，转发到真实的后端服务器
        '/api': {
          target: 'http://your-real-backend.com',
          changeOrigin: true,
          // 如果你配置了viteMockServe的prefix，这里可能需要重写路径
          // rewrite: (path) => path.replace(/^\/api/, '')
        },
      },
    },
  };
});

配置解析与要点：

1. enable 参数是核心 ：

   • command === 'serve' ：当运行 vite serve （即开发服务器）时，此条件为 true 。这是最安全的判断，确保Mock只在本地开发时启用。
   • env.VITE_USE_MOCK === 'true' ：我们通过一个自定义环境变量 VITE_USE_MOCK 来做额外控制。例如，你可以在 .env.development 文件中设置 VITE_USE_MOCK=true ，在 .env.production 中设置为 false 或不设置。这提供了灵活性，比如在某些特定构建预览（如 staging 环境）时也可能需要Mock。

2. mockPath ：指向我们创建的 mock 目录。插件会读取该目录下的文件。

3. watchFiles: true ：强烈建议开启。这样当你修改 mock/user.ts 等文件时，Mock规则会热更新，无需手动重启开发服务器。

4. 关于 prodEnable ： 生产环境启用Mock是极其危险的行为 ，除非你有非常特殊的、受控的演示或测试需求。通常你应该忽略这个选项，或者通过严格的环境变量（如 VITE_USE_MOCK_IN_PROD ）来控制，并且确保该变量在生产环境的CI/CD流程中 永远不会 被设置为 true 。

5. 与 server.proxy 的协作 ：注意看 server.proxy 配置。我们配置了 /api 代理到真实后端。 vite-plugin-mock 的优先级高于 proxy 。这意味着：

   • 当一个请求（如 /api/user/login ）发出时，会先在Mock规则中查找匹配项。
   • 如果 mock/user.ts 中定义了该URL的Mock，则请求被拦截并返回模拟数据， 不会 走到代理。
   • 如果Mock中没有定义，请求才会被代理到 http://your-real-backend.com/api/user/login 。
   • 这种机制非常完美：开发早期，所有接口走Mock；后端接口逐步完成后，你可以逐个删除Mock规则，请求就会自动流向真实后端，实现无缝切换。

3.4 第四步：配置环境变量文件

为了更清晰地管理环境配置，我们使用 .env 文件。

• .env.development (本地开发环境)

  # 开发环境启用Mock
  VITE_USE_MOCK=true
  # 其他开发环境变量...
  VITE_API_BASE_URL=/api
  

• .env.production (生产构建环境)

  # 生产环境强制禁用Mock！这是安全红线。
  # VITE_USE_MOCK=false
  # 生产环境API地址
  VITE_API_BASE_URL=https://api.your-product.com
  # 注意：即使不设置VITE_USE_MOCK，vite.config.ts中的 command === 'serve' 判断也能确保生产构建时不启用Mock。
  

• .env.staging (预发布/测试环境) - 可选

  #  staging环境通常连接测试后端，一般也不需要Mock
  # VITE_USE_MOCK=false
  VITE_API_BASE_URL=https://staging-api.your-product.com
  

在 vite.config.ts 中，我们通过 loadEnv(mode, process.cwd(), '') 加载对应模式下的环境变量。运行 vite serve 时，默认 mode 是 development ，会加载 .env.development ；运行 vite build 时，默认 mode 是 production ，会加载 .env.production 。你也可以通过 --mode 参数指定模式，例如 vite build --mode staging 。

4. 高级技巧与最佳实践

基础的配置已经能覆盖90%的场景。但在实际大型项目中，我们还可以做得更好。

4.1 类型安全与Mock数据

在TypeScript项目中，我们希望Mock返回的数据结构和前端定义的接口类型一致。可以创建一个共享的类型定义文件。

src/types/api.ts ：

// 定义后端接口返回的数据类型
export interface UserInfo {
  userId: string;
  userName: string;
  avatar: string;
  email: string;
}

export interface ApiResponse<T = any> {
  code: number;
  message: string;
  data: T;
}

在Mock文件中使用类型：

// mock/user.ts
import { MockMethod } from 'vite-plugin-mock';
import { Random } from 'mockjs';
import type { ApiResponse, UserInfo } from '../src/types/api'; // 注意路径

export default [
  {
    url: '/api/user/info',
    method: 'get',
    response: (): ApiResponse<UserInfo> => { // 指定返回类型
      return {
        code: 200,
        message: 'success',
        data: {
          userId: Random.id(),
          userName: Random.cname(),
          avatar: Random.image('100x100'),
          email: Random.email(),
        },
      };
    },
  },
] as MockMethod[];

这样做的好处是，如果后端接口类型 UserInfo 发生了变更，TypeScript编译器会在Mock文件中报错，提醒你同步更新Mock数据，保证前后端契约的一致性。

4.2 模拟网络延迟与异常状态

真实的网络请求有延迟，也可能失败。Mock可以模拟这些场景，让前端开发更贴近真实。

// mock/user.ts
export default [
  {
    url: '/api/user/login',
    method: 'post',
    // 模拟1秒延迟
    timeout: 1000,
    response: (req) => {
      const { username, password } = req.body;
      // 模拟登录失败
      if (username !== 'admin' || password !== '123456') {
        return {
          code: 401,
          message: '用户名或密码错误',
          data: null,
        };
      }
      // 模拟成功
      return {
        code: 200,
        message: 'success',
        data: { token: 'mock_token_here' },
      };
    },
  },
  {
    url: '/api/some/slow-api',
    method: 'get',
    // 模拟随机延迟，更真实
    timeout: () => Random.integer(500, 3000),
    response: () => ({ /* ... */ }),
  },
  {
    url: '/api/some/error-api',
    method: 'get',
    // 模拟HTTP状态码，如500错误
    statusCode: 500,
    response: () => ({
      code: 500,
      message: 'Internal Server Error',
      data: null,
    }),
  },
] as MockMethod[];

4.3 使用 mockjs 的语法生成更丰富的随机数据

mockjs 提供了强大的数据生成语法，可以生成非常逼真的模拟数据。

import { MockMethod } from 'vite-plugin-mock';
import { Random, mock } from 'mockjs';

export default [
  {
    url: '/api/products',
    method: 'get',
    response: () => {
      // 使用mockjs模板语法生成列表数据
      const data = mock({
        'list|10-20': [ // 生成10到20条产品数据
          {
            'id|+1': 1, // id从1开始自增
            'name': '@ctitle(5, 10)', // 随机中文标题，5-10个字
            'price|100-9999.2': 1, // 价格：100到9999，保留两位小数
            'status|1': ['on_sale', 'sold_out', 'draft'], // 状态三选一
            'cover': Random.image('200x200', Random.color(), '#FFF', 'Product'),
            'createdAt': '@datetime', // 随机日期时间
          },
        ],
        total: 35, // 假设总共有35条
        page: 1,
        pageSize: 20,
      });
      return {
        code: 200,
        message: 'success',
        data,
      };
    },
  },
] as MockMethod[];

5. 常见问题排查与实战心得

即使配置正确，在实际开发中也可能遇到一些“坑”。下面是我总结的几个典型问题及解决方案。

5.1 Mock接口不生效，请求走到了代理或真实后端

可能原因及排查步骤：

1. 检查插件是否启用 ：在终端运行 vite 命令时，控制台应该会打印出 vite-plugin-mock 相关的日志，例如 [vite-plugin-mock] Mock Server start success! 。如果没有，说明插件未启用。检查 vite.config.ts 中 enable 参数的逻辑，确保在开发模式下为 true 。
2. 检查Mock文件路径和导出 ：确认 mockPath 配置的路径正确，并且 mock/index.ts （或你指定的入口文件）正确导出了一个符合 MockMethod[] 类型的数组。
3. 检查URL和方法是否完全匹配 ：Mock配置中的 url 和 method 必须与前端代码中发起的请求 完全一致 ，包括大小写、查询参数（ ? 后面的部分不会被匹配，需在 response 函数中通过 req.query 处理）、路径参数等。建议使用完整的绝对路径（如 /api/user/login ）。
4. 检查请求拦截顺序 ：记住，Mock插件的优先级高于 server.proxy 。如果同时匹配了Mock和代理，会走Mock。你可以暂时注释掉 server.proxy 配置，看Mock是否生效，以排除代理干扰。

5.2 修改Mock文件后，热更新不生效

可能原因：

1. watchFiles 未设置为 true ：这是最常见的原因。确保配置中 watchFiles: true 。
2. 文件监视限制 ：在某些操作系统或IDE（如VSCode）中，如果同时打开的文件过多，可能会达到系统文件监视器的上限。可以尝试增加Vite的监视限制，在 vite.config.ts 的 server 配置中添加：

   export default defineConfig({
     server: {
       watch: {
         // 增加系统文件监视限制
         // 在Linux/macOS上可能需要调整
         // ignored: ['!**/mock/**'], // 明确不忽略mock文件夹
       },
     },
   });
   

3. 缓存问题 ：尝试重启Vite开发服务器。

5.3 生产构建后，包里是否还有Mock代码？

这是最重要的安全检查点。

由于我们将 mockjs 和 vite-plugin-mock 安装在 devDependencies 中，并且通过 enable: command === 'serve' 确保了在生产构建时插件逻辑不被执行，因此 正常情况下，生产环境的构建产物中不应该包含任何Mock相关的代码 。

验证方法：

1. 运行 npm run build （生产构建）。
2. 使用代码搜索工具（如 grep 或编辑器全局搜索）在生成的 dist 目录中搜索 mockjs 、 vite-plugin-mock 或你定义的Mock接口路径等关键字。 应该搜不到任何结果 。
3. 更彻底的方法是分析构建产物。可以使用 rollup-plugin-visualizer 或 webpack-bundle-analyzer （Vite也支持）生成依赖分析图，确认没有开发依赖被打包进来。

核心安全原则 ：永远不要依赖“应该没有”的假设。必须通过构建后的检查来确认。一个简单的自动化检查可以放在CI/CD流水线中，例如构建后运行一个脚本，检查 dist 目录中是否包含 mock 字符串，如果包含则构建失败。

5.4 如何处理需要登录态的接口Mock？

对于需要携带Token的接口，Mock函数可以通过请求头来获取并模拟验证逻辑。

// mock/user.ts
export default [
  {
    url: '/api/user/profile',
    method: 'get',
    response: (req) => {
      const token = req.headers?.authorization?.replace('Bearer ', '');
      // 模拟Token验证
      if (!token || token !== 'valid_mock_token') {
        return {
          code: 401,
          message: 'Unauthorized',
          data: null,
        };
      }
      return {
        code: 200,
        message: 'success',
        data: { /* 用户资料 */ },
      };
    },
  },
] as MockMethod[];

在前端代码中，你需要像调用真实接口一样，在请求拦截器中设置Token。这样，整个数据流的模拟就非常完整了。

5.5 与后端接口联调时的平滑切换

当后端接口开发完成，你需要从Mock切换到真实接口。推荐的做法是：

1. 逐个接口切换 ：不要一次性删除所有Mock。在 mock 目录中，将已完成的接口对应的Mock配置注释掉或删除。这样，该接口的请求就会因为不匹配Mock规则，而自动 fallback 到 server.proxy 配置，转发到真实后端。
2. 使用环境变量控制Mock开关 ：如前所述，利用 VITE_USE_MOCK 环境变量。在需要全量对接后端时，可以在 .env.development.local （此文件优先级高，且通常不被提交到git）中设置 VITE_USE_MOCK=false ，然后重启开发服务器，即可完全禁用所有Mock，所有请求都走代理。
3. 保持Mock文件作为文档和备用 ：即使接口对接完成，也建议保留Mock文件（可以移到另一个目录或注释起来）。它们可以作为前端期望的接口响应格式的“文档”，在未来后端重构或新成员加入时非常有参考价值。

配置 vite-plugin-mock 区分环境，核心在于理解Vite的运行机制和环境变量，并坚守“Mock不上线”的安全底线。通过条件式启用插件、合理组织Mock文件、并结合TypeScript和 mockjs 的高级特性，你可以搭建一个既高效又安全的本地开发环境。这套配置方案在我经历的几个中大型Vue3项目中都得到了验证，稳定且易于维护。最关键的是，每次构建上线前，养成检查构建产物的习惯，确保万无一失。