---
url: /config/faketimers.md
---

# fakeTimers

* **类型：** `FakeTimerConfig`

当使用 [`vi.useFakeTimers()`](/api/vi#vi-usefaketimers) 时，Vitest 将传递给 [`@sinon/fake-timers`](https://npmx.dev/package/@sinonjs/fake-timers) 的选项。

## fakeTimers.now

* **类型：** `number | Date`
* **默认值：** `Date.now()`

使用指定的 Unix 纪元时间安装假计时器。

## fakeTimers.toFake

* **类型：** `('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask' | 'Intl' | 'Temporal')[]`
* **默认值：** 全局可用的所有内容，`nextTick` 和 `queueMicrotask` 除外

一个包含要模拟的全局方法和 API 名称的数组。例如，如果只想模拟 `setTimeout()` 和 `nextTick()`，请将此属性指定为 `['setTimeout', 'nextTick']`。

仅当 `Temporal` 在全局对象上可用时才会被模拟：原生支持（Node.js >= 26 默认支持，旧版本需在 `--harmony-temporal` 后使用，并且受支持的浏览器也支持），或通过全局安装的 polyfill（例如 `import 'temporal-polyfill/global'`）支持。

在使用 `--pool=forks` 通过 `node:child_process` 在 Vitest 内部运行时，不支持模拟 `nextTick`。NodeJS 在 `node:child_process` 内部使用 `process.nextTick`，而在模拟它时会卡住。在使用 `--pool=threads` 运行 Vitest 时支持模拟 `nextTick`。

## fakeTimers.toNotFake

* **类型：** `('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask' | 'Intl' | 'Temporal')[]`
* **默认值：** `[]`

要从假计时器中排除的全局方法和 API 名称数组。使用此选项时，Vitest 始终会排除 `nextTick` 和 `queueMicrotask`。如需模拟其中任一 API，请改用 `toFake`。

::: warning
同时使用 `toFake` 和 `toNotFake` 不受支持。
:::

## fakeTimers.loopLimit

* **类型：** `number`
* **默认值：** `10_000`

调用 [`vi.runAllTimers()`](/api/vi#vi-runalltimers) 时将运行的计时器最大数量。

## fakeTimers.shouldAdvanceTime

* **类型：** `boolean`
* **默认值：** `false`

告诉 @sinonjs/fake-timers 根据真实系统时间的变化自动增加模拟时间（例如，真实系统时间每变化 20ms，模拟时间将增加 20ms）。

## fakeTimers.advanceTimeDelta

* **类型：** `number`
* **默认值：** `20`

仅在与 `shouldAdvanceTime: true` 一起使用时相关。真实系统时间每变化 advanceTimeDelta 毫秒，模拟时间就增加 advanceTimeDelta 毫秒。

## fakeTimers.shouldClearNativeTimers

* **类型：** `boolean`
* **默认值：** `true`

告诉假计时器通过委托给各自的处理程序来清除“原生”（即非假）计时器。如果禁用，且在启动假计时器会话之前存在计时器，则可能导致潜在的意外行为。