悠悠楠杉
网站页面
解决Vitestvi.mock在CommonJS环境中不生效的问题
12/14
![]()
正文：
在从Jest迁移到Vitest的过程中，许多开发者会遇到一个棘手问题：在CommonJS模块系统中，vi.mock()似乎失去了魔力。当你信心满满地写下模拟逻辑后，测试却依然调用了原始模块的实现。这种失效现象背后，隐藏着ESM与CommonJS模块加载机制的深层差异。
问题根源：模块加载的时间差
Vitest的模块模拟机制高度依赖ESM的静态解析特性。在ESM环境中，vi.mock()会在模块加载前被优先处理，从而实现对目标模块的拦截。但在CommonJS中，模块加载是同步且顺序执行的。当你在测试文件中直接导入被测模块时，实际的模块加载发生在vi.mock()调用之前，导致模拟指令"姗姗来迟"。
典型错误示例：javascript
// 测试文件 test.cjs
const { fetchData } = require('./service');
const vi = require('vitest').vi;
vi.mock('./service', () => ({
fetchData: vi.fn(() => 'mocked data')
}));
// 此时service模块早已加载完毕，mock无效
test('should mock', () => {
expect(fetchData()).toBe('mocked data'); // 失败!
});
解决方案一：动态导入 + 作用域隔离
最可靠的解决思路是将被测模块的加载延迟到mock声明之后。通过动态导入（Dynamic Import）结合作用域隔离，可精确控制加载时序：javascript
const vi = require('vitest').vi;
const { describe, test, expect } = require('vitest');
vi.mock('./service', () => ({
fetchData: vi.fn(() => 'mocked data')
}));
describe('Service测试', () => {
test('动态加载验证', async () => {
// 在mock声明后加载模块
const { fetchData } = await import('./service');
expect(fetchData()).toBe('mocked data'); // 通过!
});
});
解决方案二：vi.doMock 显式声明
Vitest提供了专为CommonJS设计的vi.doMock方法，配合require的运行时解析特性：javascript
const vi = require('vitest').vi;
// 必须在import前声明
vi.doMock('./service', () => ({
fetchData: vi.fn(() => 'mocked data')
}));
// 通过require实时加载
const { fetchData } = require('./service');
test('doMock验证', () => {
expect(fetchData()).toBe('mocked data'); // 通过!
});
环境配置要点
即使代码正确，配置错误仍会导致问题：
1. 确保package.json中不包含"type": "module"字段
2. 测试脚本扩展名使用.cjs显式声明CommonJS格式
3. 在vite.config.js中确认test.globals: true以启用全局API
迁移陷阱：Jest的习惯延续
Jest用户需特别注意两个关键差异：
1. Jest的jest.mock()是运行前预处理，而Vitest的vi.mock依赖模块系统协作
2. CommonJS的缓存机制可能导致多次require返回相同实例，需配合vi.resetModules()清理：
javascript
beforeEach(async () => {
await vi.resetModules(); // 清除模块缓存
});
模块联邦的特殊场景
当使用微前端等模块联邦方案时，可能需要通过自定义解析器突破限制：
javascript
// vite.config.js
export default {
test: {
deps: {
inline: ['@module-federation/shared'] // 强制内联处理
}
}
}
掌握这些核心技巧后，CommonJS环境下的模块模拟将不再是迁移路上的拦路虎。关键在于理解Vitest的运行时介入机制，并主动调整模块加载时序。通过合理的动态导入策略和API组合，即使在复杂的遗留系统中，也能构建可靠的测试隔离环境。
