Vitest 中无法直接在 __mocks__/ 文件内调用 vi.importActual()，但可通过在 __mocks__ 里嵌套 vi.mock() 并传入 importOriginal 回调，实现“自动导入真实模块 + 覆盖指定导出”的优雅打桩模式。
vitest 中无法直接在 `__mocks__/` 文件内调用 `vi.importactual()`，但可通过在 `__mocks__` 里嵌套 `vi.mock()` 并传入 `importoriginal` 回调，实现“自动导入真实模块 + 覆盖指定导出”的优雅打桩模式。
在大型 Vitest 项目中，频繁重复编写类似以下代码会显著降低可维护性：
vi.mock('react-router-dom', async () => {
const actual = await vi.importActual('react-router-dom')
return { ...actual, useNavigate: vi.fn() }
})
虽然你已将逻辑抽离至 __mocks__/react-router-dom.ts，但该文件默认是静态导出，不支持动态加载原始模块——这是 Vitest 当前的设计限制（GitHub #5482 明确标记为待支持特性）。
✅ 正确解法：在 __mocks__/ 中使用 vi.mock() 配合 importOriginal 回调
创建 __mocks__/react-router-dom.ts（注意：必须为 .ts 或 .js，且需确保类型兼容）：
// __mocks__/react-router-dom.ts
import { vi } from 'vitest'
// 注意：此处 vi.mock 是在 mock 文件内调用，Vitest 会识别为“自动 mock 注册”
vi.mock('react-router-dom', async (importOriginal) => {
const actual = await importOriginal()
return {
...actual,
useNavigate: vi.fn(),
// ✅ 可按需覆盖任意导出，其余全部透传
// useParams: vi.fn().mockReturnValue({ id: '123' }),
}
})
⚠️ 关键前提：在测试入口或 test-setup.ts 中显式启用该 mock
// test-setup.ts
import { vi } from 'vitest'
// 必须调用，否则 __mocks__/react-router-dom.ts 不会被激活
vi.mock('react-router-dom')
或在具体测试文件顶部声明：
// example.test.ts
import { vi } from 'vitest'
vi.mock('react-router-dom') // 启用 __mocks__/ 版本
describe('MyComponent', () => {
it('triggers navigation on submit', () => {
render(<mycomponent></mycomponent>)
fireEvent.click(screen.getByText('Submit'))
expect(useNavigate()).toHaveBeenCalled() // ✅ 使用的是 mock 实现
})
})
? 原理说明：
-
vi.mock('react-router-dom')在测试环境启动时触发 Vitest 的 mock 解析机制； - Vitest 检测到
__mocks__/react-router-dom.ts存在，并执行其中的vi.mock(...)调用； -
importOriginal()回调等效于vi.importActual()，但仅在此上下文中可用，确保原始模块被正确加载； - 所有未覆盖的导出（如
Link,Outlet,useParams等）均来自真实react-router-dom，行为完全一致。
? 最佳实践建议：
- 将
vi.mock('xxx')统一放在test-setup.ts中，避免每个测试文件重复声明； - 若需差异化 mock（如不同测试需不同
useNavigate行为），可在测试内 再次调用vi.mock()覆盖（Vitest 支持 mock 重定义）； - 为避免类型丢失，在
__mocks__/react-router-dom.ts顶部添加类型断言或declare module（见下方示例）：
// __mocks__/react-router-dom.ts
import type * as Router from 'react-router-dom'
import { vi } from 'vitest'
vi.mock('react-router-dom', async (importOriginal) => {
const actual = await importOriginal() as typeof Router
return {
...actual,
useNavigate: vi.fn(),
}
})
此方案已在 Vitest v1.3+ 稳定运行，是当前最简洁、可复用、语义清晰的局部打桩模式。未来若 Vitest 原生支持 importActual in __mocks__，迁移成本极低——只需替换 importOriginal() 调用即可。
