如何在 Vitest 中正确 Mock 模块内联副作用函数

维特（vitest）无法直接 mock 同一模块内的内部函数调用（如 `parent` 调用同模块的 `child`），因其导入绑定在模块初始化时已固化；解决方案是将被测副作用函数拆分到独立模块，再通过 `vi.mock()` 替换其导出。

在单元测试中，Mock 一个“副作用函数”（即具有日志、网络请求、状态变更等外部影响的函数）是常见需求。但许多开发者会遇到这样一个陷阱：试图用 vi.spyOn() 或 vi.mock() 去 Mock 当前模块内部定义并直接调用的函数，结果发现原始实现仍被执行——正如问题中 parent() 内部调用同模块的 child() 时，Spy 完全失效。

根本原因在于：Vitest（以及底层 ESM 模块机制）的 Mock 行为作用于模块导入关系，而非运行时函数引用。当 child() 在 dummy.ts 中被 parent() 直接调用时，它本质上是闭包内对本地变量的引用，不经过任何导入导出链，因此 vi.spyOn(dummy, 'child') 实际上是在 spy 一个已被静态解析并绑定的导出对象属性，而该属性在 parent() 执行路径中并未被访问（parent 直接调用的是词法作用域内的 child 函数，非 dummy.child）。

✅ 正确做法是解耦依赖：将 child() 提取至独立模块（如 dummy-child.ts），让 parent() 通过 import 显式依赖它。这样，Vitest 才能通过模块级 Mock 精准拦截调用：

// dummy-child.ts
export function child(): string {
  console.log('calling actual child');
  return 'bar';
}

// dummy-parent.ts
import { child } from './dummy-child';

export function parent(): string {
  return `foo${child()}`;
}

// dummy-parent.test.ts
import { parent } from './dummy-parent';

vi.mock('./dummy-child', () => ({
  child: () => 'baz',
}));

describe('parent', () => {
  it('should return foobaz when child is mocked', () => {
    expect(parent()).toBe('foobaz'); // ✅ Passes
  });
});

⚠️ 注意事项：

• vi.mock() 必须在 import 语句之后、测试用例之前调用（推荐置于文件顶部，紧随 imports 下方）；
• 使用 vi.mock() 的工厂函数形式（返回 mock 对象）比 vi.spyOn() 更可靠，因为它在模块加载前介入，确保所有导入都命中 Mock 版本；
• 若需多次不同返回值或校验调用，可在工厂函数中返回带 mockImplementation 的 jest.fn()：

  vi.mock('./dummy-child', () => {
    const mockChild = vi.fn().mockReturnValue('baz');
    return { child: mockChild };
  });
  // 后续可使用 expect(mockChild).toHaveBeenCalledTimes(1)

• 切勿在 vi.mock() 工厂中执行实际业务逻辑或依赖未 Mock 的模块，否则可能引发循环依赖或意外副作用。

总结：Vitest 的 Mock 本质是“模块替换”，不是“函数劫持”。要 Mock 一个函数，它必须是被导入的依赖项。将副作用函数提取为独立模块，既是测试友好的设计，也符合单一职责与依赖倒置原则——这不仅是 Vitest 的 workar

ound，更是健壮前端架构的实践基石。