vitest 的 `vi.spyon()` 无法在 `describe` 外部（如模块顶层）正常工作，主因是 `mockreset`、`restoremocks`、`clearmocks` 和 `threads: false` 等配置会干扰 spy 的生命周期管理，导致其在测试执行前被意外重置或失效。
在 Jest 中，jest.spyOn() 允许在测试文件顶层声明 spy，因为 Jest 默认对 mock/spy 实施“自动清理 + 作用域隔离”策略，且其 mock 系统与测试生命周期深度耦合。但 Vitest 的行为更严格——所有 spies 和 mocks 应被视为测试状态的一部分，必须在 it 或 beforeEach 等测试生命周期钩子中创建，否则极易受全局 mock 重置机制影响。
你遇到的问题本质是配置与 spy 使用方式的冲突：
- mockReset: true：在每个测试前调用 vi.resetModules() 并重置所有 mock/spy 状态；
- restoreMocks: true：恢复所有被 vi.mock() 替换的模块为原始实现（影响 spyOn 所依赖的原始对象引用）；
- clearMocks: true：清空所有 mock/spy 的调用记录（包括未被 vi.restoreAllMocks() 显式恢复的 spy）；
- threads: false：虽不直接导致失败，但在单线程模式下，模块缓存和 mock 状态共享更敏感，加剧了跨测试污染风险。
当 notificationSpy = vi.spyOn(...) 在 describe 外定义时，它在文件加载阶段即被创建；而 mockReset/clearMocks 会在每个 it 开始前触发，无差别清除该 spy 的调用历史甚至破坏其代理关系，最终导致 expect(notificationSpy).toHaveBeenCalledOnce(...) 断言失败（spy 调用计数为 0）。
✅ 正确做法（推荐）：
describe('PostboxList', () => {
it('the notification is visible when fetching status is HasError', async () => {
// ✅ 在测试内部创建 spy → 确保其生命周期与当前测试完全绑定
const notificationSpy = vi.spyOn(NotificationActions, 'addNotification');
const store = mockStore({
postbox: {
documents: { data: [], fetchingStatus: DataFetchingStatus.HasError },
messages: { data: [], fetchingStatus: DataFetchingStatus.HasError },
},
});
render(<PostboxList />, { store });
expect(notificationSpy).toHaveBeenCalledOnce({
title: 'POSTBOX.ERROR.TITLE',
text: 'POSTBOX.ERROR.TEXT',
});
});
});⚠️ 若需复用 spy（如多个测试共用），请使用 beforeEach + afterEach 显式管理：
describe('PostboxList', () => {
let notificationSpy: SpyInstance;
beforeEach(() => {
notificationSpy = vi.spyOn(NotificationActions, 'addNotification');
});
afterEach(() => {
vi.restoreAllMocks(); // 显式恢复，避免泄漏
});
it('...', () => {
// 使用 notificationSpy
});
it('...', () => {
// 使用 notificationSpy
});
});? 配置优化建议（在 vite.config.ts 中）：
test: {
// ...其他配置保持不变
mockReset: false, // ❌ 移除：避免自动重置顶层 spy
restoreMocks: false, // ❌ 移除：由 beforeEach/afterEach 显式控制
clearMocks: false, // ❌ 移除：同上，避免误清调用记录
threads: true, // ✅ 恢复默认（推荐），提升隔离性
}? 总结：Vitest 的设计哲学是“mock/spy 即测试局部状态”。将 vi.spyOn() 移至 it 或 beforeEach 内部，配合关闭激进的自动重置配置，即可彻底解决该问题。这不仅修复当前 bug，也使测试更健壮、可预测，并符合 Vitest 最佳实践。
