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__ 调用。

packages/mocker/src/node/hoistMocks.ts:1-45IDE 打开
// ★ 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
packages/mocker/src/node/redirect.ts:7-55IDE 打开
// ★ 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 插件实现模块拦截:

插件职责
hoistMocksPluginAST 改写:将 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() 的动态特性,在运行时替换模块引用
packages/mocker/src/browser/index.ts
// ★ 浏览器端导出——与 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(),对象/类被递归替换。

packages/mocker/src/node/automock.ts
// ★ 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. "如果我来写" 对比思考

🧠 问题:如何让 vi.mock 在 import 之前生效?

直觉方案:像 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 模块图的原生支持。

🧠 问题:如何跟踪哪些模块被 mock 了?

直觉方案:全局限流表(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 支持