🎭 Mocker 模块模拟
@vitest/mocker — 通过 Vite 插件体系实现编译时 + 运行时的双阶段模块模拟。
1. 模块定位
Mocker 是 Vitest 中技术含量最高的模块之一。它需要在不修改用户代码的前提下,在模块加载阶段"拦截"并替换导入。不同于 Jest 的 jest-runtime 全量接管,Vitest 选择了更轻量的策略:作为 Vite 插件插入模块转换管道。
graph TB
subgraph "编译阶段 (Vite Plugin)"
HP[hoistMocksPlugin] --> |AST 改写| CODE["注入 __vite_ssr_import__"]
IP[interceptorPlugin] --> |模块重定向| RESOLVE["解析到 mock 文件"]
AP[automockPlugin] --> |自动生成| AUTO["创建空模块骨架"]
end
subgraph "运行阶段"
VI[vi.mock / vi.spyOn] --> |运行时注册| REG[MockerRegistry]
REG --> |查找 mock 实现| LOAD["加载 mock 模块"]
end
subgraph "浏览器端"
MSW[MSW Interceptor] --> FETCH["拦截 fetch"]
NATIVE[Native Interceptor] --> IMPORT["拦截 import()"]
end
CODE --> LOAD
RESOLVE --> LOAD
style HP fill:#7c3aed,color:#fff
style IP fill:#2563eb,color:#fff
style VI fill:#059669,color:#fff
图:Mocker 编译时 + 运行时双阶段架构
2. Hoist Mock 机制
这是 Mocker 中最精巧的设计。JavaScript 的 import 语句必须放在模块顶层,且在用户代码执行前就已经解析完毕。这意味着:如果用户在 vi.mock() 之后才 import 目标模块,mock 不会生效。
Vitest 的解决方案是 AST 级代码改写:在 Vite 转换阶段,扫描所有 vi.mock() 调用,将它们提升(hoist)到文件顶部,并转换为特殊的 __vite_ssr_import__ 调用。
// ★ Hoist 配置——控制哪些调用需要提升
interface HoistMocksOptions {
hoistedModule?: string // 默认 'vitest'
utilsObjectNames?: string[] // 默认 ["vi", "vitest"]
hoistableMockMethodNames?: string[] // 默认 ["mock", "unmock"]
dynamicImportMockMethodNames?: string[] // 默认 ["mock","unmock","doMock","doUnmock"]
hoistedMethodNames?: string[] // 默认 ["hoisted"]
}🔍 Hoist 改写示例
原始代码:import { fn } from './mod'; vi.mock('./mod');
改写后:vi.mock('./mod'); const { fn } = await __vite_ssr_import__('./mod');
将 import 声明转换为动态 __vite_ssr_import__,确保 mock 注册在导入之前完成。使用 acorn-walk + MagicString 进行精确的 AST 节点替换。
3. Mock 路径解析
当 vi.mock('./foo') 被调用时,Mocker 需要找到对应的 mock 实现文件。规则与 Jest 兼容:
- 同级目录:
./foo→./__mocks__/foo.ts - node_modules:
lodash→__mocks__/lodash.ts(项目根目录) - Node 内置模块:
fs→__mocks__/fs.ts
// ★ findMockRedirect: 标准 __mocks__ 目录查找
export function findMockRedirect(root, mockPath, external) {
const path = external || mockPath
if (external || isNodeBuiltin(mockPath) || !existsSync(mockPath)) {
const mockFolder = join(root, '__mocks__', dirname(path))
if (!existsSync(mockFolder)) return null
// ★ 支持嵌套包: @scope/pkg → __mocks__/@scope/pkg.ts
return findFile(mockFolder, basename(path))
}
// 同级目录: ./foo → ./__mocks__/foo.ts
const fullPath = resolve(dirname(path), '__mocks__', basename(path))
return existsSync(fullPath) ? fullPath : null
}4. Vite 拦截插件
Mocker 通过 6 个 Vite 插件实现模块拦截:
| 插件 | 职责 |
|---|---|
hoistMocksPlugin | AST 改写:将 vi.mock 提升到文件顶部 |
interceptorPlugin | 模块加载时拦截:检查注册表中是否有 mock 实现 |
mockerPlugin | 主插件:协调所有子插件,管理 mock 注册表 |
automockPlugin | 自动生成空 mock 模块(所有导出替换为 vi.fn()) |
dynamicImportPlugin | 处理动态 import() 的拦截 |
ServerMockResolver | 服务端 mock 路径解析器 |
5. 浏览器端实现
在浏览器环境中,无法使用 Vite 插件拦截模块加载。Mocker 提供两种替代方案:
- MSW (Mock Service Worker):通过 Service Worker 拦截
fetch请求,将模块请求重定向到 mock 实现 - Native Interceptor:利用
import()的动态特性,在运行时替换模块引用
// ★ 浏览器端导出——与 Node 端 API 一致
export { ModuleMockerMSWInterceptor } from './interceptor-msw'
export { ModuleMockerServerInterceptor } from './interceptor-native'
export { ModuleMocker } from './mocker'6. 自动 Mock
vi.mock('./mod') 不提供实现时,Vitest 会自动创建一个 mock 模块:所有导出函数被替换为 vi.fn(),对象/类被递归替换。
// ★ automockModule: 遍历模块导出,递归创建 mock
export async function automockModule(mod) {
for (const key of Object.keys(mod)) {
const val = mod[key]
if (typeof val === 'function') mod[key] = vi.fn(val)
else if (typeof val === 'object' && val !== null) automockModule(val)
}
}7. "如果我来写" 对比思考
直觉方案:像 Jest 一样自己实现一个 require 运行时,完全接管模块加载流程。
Vitest 的做法:hoistMocksPlugin 在 Vite 转换阶段进行 AST 改写——将 vi.mock() 提升到文件顶部,将 import 转换为 __vite_ssr_import__。
差异分析:Jest 的 jest-runtime 是一套完整的模块系统——它在 V8 虚拟机中手动实现 require,这很强大但也导致了很多兼容性问题(ESM、top-level await)。Vitest 的 AST 改写方案更轻量——它不改变模块系统的语义,只是重排了执行顺序。这得益于 Vite 对 SSR 模块图的原生支持。
直觉方案:全局限流表(global Map)。
Vitest 的做法:MockerRegistry(registry.ts)——一个按文件路径隔离的注册表。每个测试文件有自己的 mock 注册表,vi.mock() 只在当前文件生效。
差异分析:全局注册表会导致测试之间的 mock 污染——文件 A 的 mock 意外影响文件 B。按文件隔离确保 mock 的作用域与测试文件绑定,这是保证测试隔离性的关键设计。
8. 学习要点
| 🏗️ 学习主题 | 关键收获 |
|---|---|
| Hoist 机制 | AST 改写实现代码提升——不改变语义,只重排顺序 |
| Vite 插件拦截 | 利用 Vite 的 resolveId/load 钩子实现模块重定向 |
| 双端实现 | Node 用 Vite 插件,Browser 用 Service Worker——API 保持统一 |
| Mock 注册表 | 按文件隔离的注册表——防止跨文件 mock 污染 |
| 自动 Mock | 递归替换导出为 vi.fn()——零配置 mock 支持 |