Mock.js 拦截失效或数据格式错误的常见原因及排查

在前端单页面应用及前后端分离项目的开发过程中，Mock.js 常用于在后端接口就绪前生成模拟数据。然而，开发者常会遇到两类典型故障：一是“拦截失效”，请求绕过 Mock.js 直接发送至真实网络环境，触发 404 或跨域错误；二是“数据格式错误”，接口虽被拦截，但返回的数据结构与预期严重偏离，如字段缺失、数组被解析为对象、数值被解析为重复字符串等。排查此类问题应遵循“从网络传输链路到数据模板解析”的层次，先确定请求底层是否命中拦截条件，再深入核对数据模板定义规则。

一、Mock.js 拦截请求的底层机制与失效临界点

要排查拦截失效，首先必须理解 Mock.js 捕获网络请求的具体方式。Mock.js 并不是在浏览器网络底层或操作系统驱动层进行流量代理，而是纯粹运行在浏览器 JavaScript 运行时的客户端库。

当执行 Mock.mock(...) 时，Mock.js 会重写宿主全局对象上的 window.XMLHttpRequest 原型。在后续代码执行中，凡是通过标准 XMLHttpRequest 发起的异步通信，实际上实例化的都是 Mock.js 派生的自定义代理对象 MockXMLHttpRequest。该对象在调用 open() 和 send() 时，会核对目标请求的 URL 和 HTTP Method 是否存在于内部规则注册表中：若匹配成功，则立即阻断真实的 HTTP 物理握手，在浏览器本地通过定时器模拟网络延迟并触发 onload 或 onreadystatechange 返回假数据；若未命中，则回退调用原生 XHR 发起真实请求。

1. 原生 Fetch 导致的拦截完全失效

这是现代前端项目中最普遍的拦截失效原因。很多初学者存在一种常见认知：“只要在前端工程中引入了 Mock.js，项目里所有的网络请求都会被自动拦截”。这种说法在以往基于 jQuery $.ajax 或纯粹依赖 XMLHttpRequest 的旧版 Axios 时代看似成立，但放在现代前端生态中并不正确。

ES6 规范引入的原生 window.fetch 是一套独立于 XMLHttpRequest 的全新网络请求 API。浏览器内核在执行 fetch() 时，直接穿透到底层网络管道，完全不调用 window.XMLHttpRequest。因为 Mock.js 官方核心源码仅覆写了 XHR 原型，没有重写 window.fetch，所以当业务代码或第三方库（如 umi-request、开启了 Fetch 适配器的 Axios 等）使用 fetch 发出请求时，Mock.js 根本无法察觉，请求会原原本本地打往真实服务器，引发接口 404、500 或 CORS 跨域报错。

二、拦截失效的常见原因与系统化排查步骤

除了网络库底层不兼容外，在基于标准 XHR 的项目中，拦截失效通常集中在脚本加载时序、URL 匹配模式、请求动词与工程构建分支这四个关键点上。

1. 引入时机滞后与异步加载竞态

Mock.js 对 window.XMLHttpRequest 的重写必须发生在任何业务请求发起之前。常见错误包括：

• 在入口文件中将 Mock 放在异步操作中引入：例如使用了 import('./mock').then(...) 动态导入，而组件的生命周期钩子（如 Vue 的 created、React 的 useEffect）中已经并发触发了数据拉取。此时 XHR 原型尚未被重写，首屏并发请求直接穿透。
• 环境变量分支未执行：在代码中编写了 if (process.env.NODE_ENV === 'development') { import('./mock'); }，但由于打包配置（如 .env.local）中环境标识写错或判断条件不成立，Mock 入口实际上从未被打包或执行。

验证方法：在浏览器控制台输入 window.XMLHttpRequest.toString()。如果输出为原生系统函数 function XMLHttpRequest() { [native code] }，则说明 Mock.js 根本没有执行挂载；若已被 Mock 替换，则会显示 Mock 自定义构造函数源码。

2. URL 精确字符串匹配受 Query 查询参数破坏

另一个高频失效点在于 URL 的声明方式。在定义拦截规则时，Mock.js 允许传入字符串或正则表达式。许多开发者习惯直接传入全等字符串：

// 隐患写法：使用固定全等字符串匹配
Mock.mock('/api/user/info', 'get', { code: 200, data: { name: '张三' } });

如果前端发起的 GET 请求带有动态查询参数（例如分页、时间戳或用户 ID）：axios.get('/api/user/info?id=1001&t=1698000000')，Mock.js 内部在做字符串对比时，会执行 options.url === rurl。因为 '/api/user/info?id=1001&t=1698000000' !== '/api/user/info'，等值比对失败，Mock.js 便判定未命中，直接将请求透传至外部网络。

规范修正：涉及带参数的 GET 请求或带有动态路径的 RESTful 接口，必须使用正则表达式进行路径定义：

// 规范写法：使用正则表达式支持 query 参数或动态路径
Mock.mock(new RegExp('^/api/user/info(\\?.*)?$'), 'get', (options) => {
  // options.url 中包含完整请求路径与参数，可手动解析
  return {
    code: 200,
    data: { id: 1001, name: '张三' }
  };
});

3. 请求方法（Method）大小写与类型不匹配

Mock.js 在比对请求方法时，通常会转换为小写比对，但如果业务代码使用的是 POST，而拦截规则配置成了 'get'，或者规则中省略了请求方式导致默认匹配与自定义方法冲突，也会导致匹配静默失败。此外，Axios 中如果配置了全局 baseURL（例如 baseURL: '/api'），业务调用的 axios.get('/user') 实际生成的请求 URL 是 /api/user，若 Mock 规则中只注册了 /user，两者也会因前缀缺失而无法命中。

三、数据格式错误与模板解析异常的根源分析

当接口能够成功拦截、控制台未报 404，但页面组件渲染崩溃或出现 undefined 时，问题通常源于数据模板定义（Data Template Definition, DTD）语法错误。Mock.js 的数据模板语法采用 'name|rule': value 格式，其核心行为严重依赖 value 的 JavaScript 原始类型与 rule 的运算符组合。

1. 数组长度规则与单项抽取混淆

这是导致返回数据“类型直接改变”的最常见错误。开发者通常希望返回一个包含指定条数对象的数组：

// 典型错误：误以为 'list|1' 代表包含 1 个元素的数组
Mock.mock('/api/list', {
  'list|1': [{ 'id|+1': 1, 'name': '@cname' }]
});

在 Mock.js 语法中：

• 当 value 为数组且 rule 为 1 时（即 'name|1': array），Mock.js 的含义是“从数组中随机挑选 1 个元素作为最终属性值”。其输出结果不是 [{ id: 1, name: '...' }]，而是单个对象 { id: 1, name: '...' }！
• 前端组件执行 res.data.list.map(...) 或 v-for="item in list" 时，由于对象不具备迭代器方法，控制台会抛出致命异常 TypeError: res.data.list.map is not a function。
• 若需要生成包含 1 个元素的数组，规则必须写作 'list|1-1': [...]；若需生成固定 N 条记录，应显式写作 'list|10': [...]；若需生成范围数量，应写作 'list|5-15': [...]。

2. 初始值类型误判导致数值与字符串生成颠倒

Mock.js 根据冒号右侧 value 的类型来赋予规则符号不同的物理语义。以 'property|1-100' 为例：

// 错误写法：初始值给成了字符串
'age|1-100': '18' 
// 输出结果并不是 1 到 100 的随机数，而是将字符串 '18' 重复 1 到 100 次，产生形如 '1818181818...' 的超长字符串！

// 规范写法：初始值必须是 Number 类型
'age|1-100': 18 
// 输出结果为 1 到 100 之间的随机整数

类似地，布尔类型属性若写作 'isActive|1': true，代表以 50% 概率生成 true/false；若右侧写成字符串 'isActive|1': 'true'，则退化为字符串重复。

3. 占位符（Placeholder）大小写与未注册扩展

占位符以 @ 开头，用于直接引用 Mock.Random 提供的数据生成方法（如 @cname, @date, @guid）。常见错误包括：

• 占位符名称大小写错误：Mock.js 内置方法区分大小写。例如写成 @Date 或 @DATETIME，解析器无法找到匹配的内置函数，会直接放弃解析，将原生字符串 "@Date" 原样返回给前端。
• 格式化模板参数语法不符合规范：例如使用 @date('yyyy-MM-dd') 时，格式化占位符支持 yyyy、MM、dd 等，若写错为其它未定义的格式，会导致解析异常。
• 自定义占位符未挂载或挂载滞后：若使用 Mock.Random.extend({ ... }) 注册自定义数据生成函数，该扩展调用必须先于任何使用该占位符的模板代码执行。

4. 动态函数属性中 this 上下文与求值顺序陷阱

Mock.js 支持在模板中将属性值声明为一个 Function，该函数内可以通过 this 访问当前数据对象已生成的其他属性。这里存在两个隐藏陷阱：

• 使用 ES6 箭头函数导致 this 丢失：若写成 fullName: () => this.firstName + this.lastName，箭头函数捕获的是定义时外部闭包的 this（通常是 undefined 或 window），导致计算结果为 "NaN" 或 "undefinedundefined"。必须使用标准函数关键字 function() { ... }。
• 属性解析顺序依赖：Mock.js 按照对象属性在模板中的顺序依次求值。如果属性 A 依赖属性 B 的生成结果，但属性 A 在物理书写顺序上排在属性 B 的前面，此时访问 this.B 必然得到 undefined。

四、Mock.js 工程化防御性配置与调试闭环

为了在团队开发中彻底杜绝拦截失效与格式畸形问题，建议从工程入口组织、规则编写范式、网络模拟与可观测性四个维度建立闭环。

1. 规范的工程入口与环境隔离

在现代脚手架（如 Vite、Vue CLI 或 Create React App）中，建立统一的 src/mock/index.js 管理模块，并在应用入口 src/main.js 最顶部以同步方式载入：

// src/main.js
// 1. 开发环境下最顶层同步引入，确保在任何业务组件加载前重写完成
if (process.env.NODE_ENV === 'development') {
  require('./mock');
}

import Vue from 'vue';
import App from './App.vue';
// ... 业务挂载

2. 统一封装高防御度的 Mock 注册函数

为避免各个模块各自书写字符串导致 Query 参数匹配失效，可封装统一的辅助函数，自动为路径添加正则边界：

// src/mock/utils.js
import Mock from 'mockjs';

// 封装安全的正则匹配注册器
export function mockRoute(urlPattern, method, responseHandler) {
  // 自动将字符串包装为忽略 Query 参数的正则表达式
  const regex = typeof urlPattern === 'string'
    ? new RegExp('^' + urlPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(\\?.*)?$')
    : urlPattern;

  Mock.mock(regex, method.toLowerCase(), (options) => {
    // 注入调试日志：开发环境控制台实时回显拦截信息
    console.groupCollapsed(`%c[Mock Intercepted] %c${method.toUpperCase()} ${options.url}`, 'color:#8A9478;font-weight:bold;', 'color:#464B48;');
    console.log('Query/Body Options:', options);
    const result = typeof responseHandler === 'function' ? responseHandler(options) : Mock.mock(responseHandler);
    console.log('Mock Response:', result);
    console.groupEnd();
    return result;
  });
}

3. 配置网络延迟与自检手段

真实网络环境始终存在往返耗时，如果 Mock 总是毫秒级同步返回，可能会掩盖前端页面中的竞态条件（Race Condition）、重复提交与加载中遮罩（Loading Spinners）失效问题。

通过在 Mock 初始化时配置延时范围，可以有效模拟真实网络抖动：

import Mock from 'mockjs';

// 配置所有被拦截请求的响应时间在 200ms 到 600ms 之间
Mock.setup({
  timeout: '200-600'
});