本文介绍如何在 TypeScript 项目中不牺牲类型安全的前提下，正确替代 setTimeout 等全局定时器方法，推荐使用 Jest/Vitest 内置的 fake timers 机制，避免手动重写引发的类型错误与维护风险。
本文介绍如何在 typescript 项目中不牺牲类型安全的前提下，正确替代 `settimeout` 等全局定时器方法，推荐使用 jest/vitest 内置的 fake timers 机制，避免手动重写引发的类型错误与维护风险。
在单元测试中，直接重写 globalThis.setTimeout 表面看似简单，实则极易引发类型系统报错（如 TS2741：缺失 promisify 属性）和运行时行为不一致问题。这是因为 typeof setTimeout 并非一个简单函数签名——Node.js 的 timers.d.ts 中将其定义为带有静态方法（如 promisify）的复杂对象，而手动赋值的箭头函数无法满足该完整接口。
✅ 推荐方案：使用测试框架原生 Timer Mocks
Jest 和 Vitest 均提供了成熟、类型安全且语义清晰的 fake timers API，无需任何类型断言或 any：
// Jest 示例（Vitest 语法几乎完全一致）
describe('Timer-dependent logic', () => {
beforeEach(() => {
jest.useFakeTimers(); // 启用虚拟计时器
});
afterEach(() => {
jest.useRealTimers(); // 恢复真实计时器，确保测试隔离
});
test('should execute callback after delay', () => {
const callback = jest.fn();
setTimeout(callback, 3000);
expect(callback).not.toHaveBeenCalled();
jest.advanceTimersByTime(3000); // 快进 3 秒（精确控制）
// 或使用 jest.runAllTimers(); // 立即执行所有待处理定时器
expect(callback).toHaveBeenCalledTimes(1);
});
});? 关键优势：
- ✅ 零类型污染：不修改全局对象，完全绕过
typeof setTimeout类型校验； - ✅ 行为精准：支持
advanceTimersByTime()、runAllTimers()、runOnlyPendingTimers()等细粒度控制； - ✅ 自动清理友好：配合
beforeEach/afterEach可确保每个测试环境纯净； - ✅ 跨平台兼容：Jest（Node.js）与 Vitest（Node.js + 浏览器环境）均原生支持。
⚠️ 注意事项：
- 避免在生产代码中 monkey-patch
globalThis.setTimeout—— 这违反封装原则，易导致不可预测副作用； - 若使用 Vitest，请启用
fakeTimers: { enable: true }配置或调用vi.useFakeTimers()； - 对于依赖
Promise+setTimeout的异步逻辑（如delay()工具函数），建议配合await vi.runAllTimersAsync()确保 Promise 链完成。
总结：类型安全 ≠ 手动重写全局函数。拥抱测试框架提供的抽象层，才是可维护、可扩展、真正 type-safe 的工程实践。
