Vue3 项目中怎么集成 Mock.js 模拟后端接口

一、核心运行机制与关键前置认知

理解 Mock.js 的底层工作机制，是排查后续集成问题的关键。Mock.js 并不是一个独立运行的 Node.js 代理服务器，而是一个纯前端的 JavaScript 运行时库。当你在代码中引入 Mock.js 并执行 Mock.mock() 时，它做的事情是重写浏览器全局的 window.XMLHttpRequest 对象。

这意味着，只要前端发起的网络请求底层依赖的是 XMLHttpRequest（例如业界普遍使用的 axios），该请求在尚未脱离浏览器发出前，就会被 Mock.js 的代理钩子截获。Mock.js 会拿请求的 URL 和 HTTP Method 与已注册的规则做正则匹配，若匹配成功，则执行预设的数据模板生成器并构造一个符合规范的 Fake 响应体，阻止浏览器发起真正的 TCP 握手。

图 1：Mock.js 原生客户端拦截与真实网络链路对比

二、Vue3 集成 Mock.js 完整四步流程

下面以当前主流的 Vue3 + TypeScript + Vite 工程结构为例，进行标准的模块化集成。整体流程清晰分为依赖引入、规则编写、条件注册与组件调用四个阶段。

图 2：Vue3 集成 Mock.js 标准四步工程化配置步骤拆解

步骤一：安装 Mock.js 与 TypeScript 类型定义

在终端项目根目录下，执行如下命令安装 mockjs 运行时依赖。由于 Vue3 普遍采用 TypeScript，还需要在开发依赖（devDependencies）中补充 @types/mockjs：

# 安装运行时依赖
npm install mockjs

# 安装开发环境 TypeScript 类型补充声明
npm install -D @types/mockjs

安装确认：安装完成后，检查 package.json 的 dependencies 中是否包含 "mockjs"，在 devDependencies 中是否包含 "@types/mockjs"。

步骤二：创建 Mock 模块化目录与规则文件

为避免所有模拟接口堆砌在单一文件中，推荐在 src/mock 目录下按功能拆分。例如我们创建用户模块规则 user.ts，并在 index.ts 中做统一聚合：

src/
└── mock/
    ├── index.ts        # Mock 统一入口与基础配置
    └── modules/
        └── user.ts     # 用户业务域相关接口拦截规则

先编写业务规则文件 src/mock/modules/user.ts，演示支持分页与模拟用户列表的接口：

import Mock from 'mockjs'

// 注册接口拦截：使用正则表达式匹配带 query 参数的请求
Mock.mock(/\/api\/users/, 'get', (options: { url: string; type: string; body: string }) => {
  // 模拟从 URL 解析参数（简单演示）
  return Mock.mock({
    code: 200,
    message: 'success',
    data: {
      'total|20-100': 100,
      'list|10': [
        {
          'id|+1': 1,
          name: '@cname',
          'age|18-60': 25,
          email: '@email',
          avatar: "@image('100x100', '#B96555', '#FFFFFF', 'Avatar')",
          createTime: '@datetime("yyyy-MM-dd HH:mm:ss")',
          'status|1': [0, 1]
        }
      ]
    }
  })
})

// 模拟新增用户接口 (POST 请求)
Mock.mock('/api/users', 'post', (options: { body: string }) => {
  const reqBody = JSON.parse(options.body || '{}')
  return Mock.mock({
    code: 200,
    message: '用户创建成功',
    data: {
      id: '@guid',
      ...reqBody,
      createdAt: '@datetime'
    }
  })
})

接着在 src/mock/index.ts 中统一引入所有模块，并可配置模拟延迟时间：

import Mock from 'mockjs'
import './modules/user'

// 设置模拟网络请求的延时响应时间（单位毫秒），模拟真实网络抖动
Mock.setup({
  timeout: '200-600'
})

export default Mock

步骤三：在 main.ts 中条件挂载（开发环境隔离）

严禁直接在 main.ts 顶部写死 import './mock'。这样会导致 Mock.js 及其生成逻辑被直接打包到生产环境 bundle 中，不仅增加产物体积，更会导致线上所有同名接口直接失效。

在 Vite 项目中，推荐借助 import.meta.env.DEV 或自定义环境变量，使用动态 import() 实现按需加载：

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'

// 仅在本地开发环境中挂载 Mock
if (import.meta.env.DEV) {
  import('./mock')
}

const app = createApp(App)
app.mount('#app')

当执行 npm run dev 时，import.meta.env.DEV 值为 true，Vite 会加载 src/mock/index.ts，拦截器生效；而在执行 npm run build 时，Vite 的静态分析会自动排除该代码分支（Tree-shaking），避免污染生产构建。

步骤四：在 Vue3 视图中发起请求与验证

在 Vue3 组件中，使用标准 Axios 方式调用接口。业务代码无需做任何针对 Mock 的特殊标记：

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import axios from 'axios'

interface UserItem {
  id: number
  name: string
  age: number
  email: string
  avatar: string
  createTime: string
  status: number
}

const userList = ref<UserItem[]>([])
const loading = ref(false)

const fetchUsers = async () => {
  loading.value = true
  try {
    const res = await axios.get('/api/users', {
      params: { page: 1, pageSize: 10 }
    })
    if (res.data.code === 200) {
      userList.value = res.data.data.list
    }
  } catch (error) {
    console.error('获取用户列表失败', error)
  } finally {
    loading.value = false
  }
}

onMounted(() => {
  fetchUsers()
})
</script>

三、Mock 数据模板语法与动态路由参数匹配

Mock.js 的核心价值之一在于其内置丰富的数据占位符与生成规则。很多初学者在集成时容易在两处卡壳：一是动态参数路径无法被拦截，二是不知道如何生成逼真的中文业务数据。

图 3：Mock 数据模板语法与动态接口匹配模型

当接口带有 Query 参数（例如 /api/users?page=1&pageSize=10）或者 RESTful 风格的路径参数（例如 /api/users/1024）时，如果注册规则传入的是纯字符串 '/api/users'，Mock.js 将无法命中匹配，导致直接返回 404 或穿透到后端。必须统一使用 正则表达式 作为 Mock.mock() 的首个入参。

四、常见避坑指南与生产环境安全隔离

许多开发者在初次引入 Mock.js 后常会产生“为什么控制台没有报错，但 Network 里一片空白”的疑问。以下梳理四个最常见的现象排查与解决思路：

• 现象一：Chrome DevTools Network 面板看不到请求
  原因：这是 Mock.js 的预期行为。因为 Mock.js 直接覆写了浏览器的 window.XMLHttpRequest 并在内存中通过回调触发 onreadystatechange 和 onload，底层网络进程根本没有创建物理 socket 链接。如果需要查看数据交互，建议直接在 Axios 拦截器中通过 console.log 输出响应体。
• 现象二：请求报 404 或直接发送到了真实地址
  原因：检查两个地方。一是注册 URL 时是否为纯字符串且请求实际带有 Query 参数；二是检查 HTTP Method 大小写（Mock.js 内部推荐使用小写 'get'、'post' 或 'put'）。
• 现象三：上传文件或 FormData 报错
  原因：Mock.js 模拟的 XMLHttpRequest 并未完全对齐 W3C 最新标准，在处理二进制 Blob、ArrayBuffer 或复杂 FormData 上传时可能会抛出内部异常。如需模拟大文件上传，建议使用专门的开发代理或自定义中间件。
• 现象四：打包后线上出现模拟数据或包体积增大
  原因：未做好构建隔离。严格通过条件动态导入引入，并在打包后使用 rollup-plugin-visualizer 检查生产包，确认 mockjs 没有任何 chunk 存在于 dist/ 产物中。

图 4：避坑排查决策与生产发布安全检查清单

总结

在 Vue3 项目中集成 Mock.js，能够在后端接口尚未就绪时，为前端开发提供极其逼真的数据交互体验。通过在客户端借助 XMLHttpRequest 代理，可以大幅降低联调前的沟通阻塞。在实际工程落地时，务必牢记：请求层选用 Axios 确保拦截生效、规则定义使用正则表达式兼容动态参数、并在 main.ts 中通过环境分支彻底隔离生产构建，即可兼顾敏捷的开发效率与健壮的线上安全。