Node.js v26.0.0 文档

定时器#

timer 模块公开了一个全局 API，用于调度在未来某个时间点调用的函数。由于定时器函数是全局的，因此无需调用 require('node:timers') 即可使用该 API。

Node.js 中的定时器函数实现了与 Web 浏览器提供的定时器 API 类似的 API，但使用了围绕 Node.js 事件循环 (Event Loop) 构建的不同内部实现。

类：Immediate#

此对象在内部创建，并由 setImmediate() 返回。它可以传递给 clearImmediate() 以取消已调度的操作。

默认情况下，当调度一个 immediate 时，只要该 immediate 处于活动状态，Node.js 事件循环就会继续运行。由 setImmediate() 返回的 Immediate 对象导出了 immediate.ref() 和 immediate.unref() 函数，可用于控制此默认行为。

immediate.hasRef()#

• 返回：<boolean>

如果为 true，则 Immediate 对象将使 Node.js 事件循环保持活动状态。

immediate.ref()#

• 返回：<Immediate> immediate 的引用

调用时，请求只要 Immediate 处于活动状态，Node.js 事件循环就不退出。多次调用 immediate.ref() 不会产生任何效果。

默认情况下，所有的 Immediate 对象都是“被引用”（ref'ed）的，因此除非之前调用过 immediate.unref()，否则通常不需要调用 immediate.ref()。

immediate.unref()#

• 返回：<Immediate> immediate 的引用

调用时，活动的 Immediate 对象将不需要 Node.js 事件循环保持活动状态。如果没有其他活动使事件循环保持运行，则进程可能在 Immediate 对象的回调被调用之前退出。多次调用 immediate.unref() 不会产生任何效果。

immediate[Symbol.dispose]()#

取消此 immediate。这类似于调用 clearImmediate()。

类：Timeout#

此对象在内部创建，并由 setTimeout() 和 setInterval() 返回。它可以传递给 clearTimeout() 或 clearInterval() 以取消已调度的操作。

默认情况下，当使用 setTimeout() 或 setInterval() 调度定时器时，只要定时器处于活动状态，Node.js 事件循环就会继续运行。这些函数返回的每个 Timeout 对象都导出了 timeout.ref() 和 timeout.unref() 函数，可用于控制此默认行为。

timeout.close()#

• 返回：<Timeout> timeout 的引用

取消此超时定时器。

timeout.hasRef()#

• 返回：<boolean>

如果为 true，则 Timeout 对象将使 Node.js 事件循环保持活动状态。

timeout.ref()#

• 返回：<Timeout> timeout 的引用

调用时，请求只要 Timeout 处于活动状态，Node.js 事件循环就不退出。多次调用 timeout.ref() 不会产生任何效果。

默认情况下，所有的 Timeout 对象都是“被引用”（ref'ed）的，因此除非之前调用过 timeout.unref()，否则通常不需要调用 timeout.ref()。

timeout.refresh()#

• 返回：<Timeout> timeout 的引用

将定时器的开始时间设置为当前时间，并重新调度定时器，使其在之前指定的持续时间后（根据当前时间调整）调用其回调函数。这对于在不分配新的 JavaScript 对象的情况下刷新定时器非常有用。

在已经调用过回调的定时器上使用此方法将重新激活定时器。

timeout.unref()#

• 返回：<Timeout> timeout 的引用

调用时，活动的 Timeout 对象将不需要 Node.js 事件循环保持活动状态。如果没有其他活动使事件循环保持运行，则进程可能在 Timeout 对象的回调被调用之前退出。多次调用 timeout.unref() 不会产生任何效果。

timeout[Symbol.toPrimitive]()#

• 返回：<integer> 一个可用于引用此 timeout 的数字

将 Timeout 强制转换为基本类型。该基本类型可用于清除 Timeout。此基本类型只能在创建超时定时器的同一个线程中使用。因此，要在 worker_threads 中使用它，必须首先将其传递给正确的线程。这允许与浏览器 setTimeout() 和 setInterval() 实现有更好的兼容性。

timeout[Symbol.dispose]()#

取消此超时定时器。

调度定时器#

Node.js 中的定时器是一种内部结构，它在特定时间段后调用给定的函数。定时器的函数何时被调用，取决于使用哪种方法创建定时器，以及 Node.js 事件循环正在执行的其他工作。

setImmediate(callback[, ...args])#

• callback <Function> 在本轮 Node.js 事件循环 结束时调用的函数。
• ...args <any> 调用 callback 时要传递的可选参数。
• 返回：<Immediate> 用于 clearImmediate()

在 I/O 事件的回调之后，调度“立即”执行 callback。

当多次调用 setImmediate() 时，callback 函数会按照它们被创建的顺序排队等待执行。每一轮事件循环迭代都会处理整个回调队列。如果在一个正在执行的回调函数中将 immediate 定时器加入队列，该定时器直到下一轮事件循环迭代才会触发。

如果 callback 不是一个函数，将抛出 TypeError。

此方法有一个适用于 Promise 的自定义变体，可以通过 timersPromises.setImmediate() 使用。

setInterval(callback[, delay[, ...args]])#

• callback <Function> 当定时器时间到时要调用的函数。
• delay <number> 调用 callback 前等待的毫秒数。默认值： 1。
• ...args <any> 调用 callback 时要传递的可选参数。
• 返回：<Timeout> 用于 clearInterval()

每隔 delay 毫秒调度一次 callback 的重复执行。

当 delay 大于 2147483647 或小于 1 或为 NaN 时，delay 将被设置为 1。非整数的延迟将被截断为整数。

如果 callback 不是一个函数，将抛出 TypeError。

此方法有一个适用于 Promise 的自定义变体，可以通过 timersPromises.setInterval() 使用。

setTimeout(callback[, delay[, ...args]])#

• callback <Function> 当定时器时间到时要调用的函数。
• delay <number> 调用 callback 前等待的毫秒数。默认值： 1。
• ...args <any> 调用 callback 时要传递的可选参数。
• 返回：<Timeout> 用于 clearTimeout()

在 delay 毫秒后调度执行一次性的 callback。

callback 很可能不会在恰好 delay 毫秒时被调用。Node.js 不保证回调触发的确切时间，也不保证它们的顺序。回调将在尽可能接近指定时间时被调用。

当 delay 大于 2147483647 或小于 1 或为 NaN 时，delay 将被设置为 1。非整数的延迟将被截断为整数。

如果 callback 不是一个函数，将抛出 TypeError。

此方法有一个适用于 Promise 的自定义变体，可以通过 timersPromises.setTimeout() 使用。

取消定时器#

setImmediate()、setInterval() 和 setTimeout() 方法都会返回代表已调度定时器的对象。这些对象可用于取消定时器并防止其触发。

对于 setImmediate() 和 setTimeout() 的 Promise 化变体，可以使用 AbortController 来取消定时器。取消后，返回的 Promise 将会被以 'AbortError' 为原因拒绝。

对于 setImmediate()

import { setImmediate as setImmediatePromise } from 'node:timers/promises';

const ac = new AbortController();
const signal = ac.signal;

// We do not `await` the promise so `ac.abort()` is called concurrently.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort();
const { setImmediate: setImmediatePromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort();
copy

对于 setTimeout()

import { setTimeout as setTimeoutPromise } from 'node:timers/promises';

const ac = new AbortController();
const signal = ac.signal;

// We do not `await` the promise so `ac.abort()` is called concurrently.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort();
const { setTimeout: setTimeoutPromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort();
copy

clearImmediate(immediate)#

• immediate <Immediate> 由 setImmediate() 返回的 Immediate 对象。

取消由 setImmediate() 创建的 Immediate 对象。

clearInterval(timeout)#

• timeout <Timeout> | <string> | <number> 由 setInterval() 返回的 Timeout 对象，或者 Timeout 对象的基本类型（字符串或数字）。

取消由 setInterval() 创建的 Timeout 对象。

clearTimeout(timeout)#

• timeout <Timeout> | <string> | <number> 由 setTimeout() 返回的 Timeout 对象，或者 Timeout 对象的基本类型（字符串或数字）。

取消由 setTimeout() 创建的 Timeout 对象。

定时器 Promise API#

timers/promises API 提供了一套返回 Promise 对象的替代定时器函数。可以通过 require('node:timers/promises') 访问此 API。

import {
  setTimeout,
  setImmediate,
  setInterval,
} from 'node:timers/promises';
const {
  setTimeout,
  setImmediate,
  setInterval,
} = require('node:timers/promises');
copy

timersPromises.setTimeout([delay[, value[, options]]])#

• delay <number> 在履行 promise 前等待的毫秒数。默认值： 1。
• value <any> promise 履行时携带的值。
• options <Object>
• ref <boolean> 设置为 false 以表示所调度的 Timeout 不需要使 Node.js 事件循环保持活动状态。默认值： true。
• signal <AbortSignal> 可选的 AbortSignal，用于取消已调度的 Timeout。

import {
  setTimeout,
} from 'node:timers/promises';

const res = await setTimeout(100, 'result');

console.log(res);  // Prints 'result'
const {
  setTimeout,
} = require('node:timers/promises');

setTimeout(100, 'result').then((res) => {
  console.log(res);  // Prints 'result'
});
copy

timersPromises.setImmediate([value[, options]])#

• value <any> promise 履行时携带的值。
• options <Object>
• ref <boolean> 设置为 false 以表示所调度的 Immediate 不需要使 Node.js 事件循环保持活动状态。默认值： true。
• signal <AbortSignal> 可选的 AbortSignal，用于取消已调度的 Immediate。

import {
  setImmediate,
} from 'node:timers/promises';

const res = await setImmediate('result');

console.log(res);  // Prints 'result'
const {
  setImmediate,
} = require('node:timers/promises');

setImmediate('result').then((res) => {
  console.log(res);  // Prints 'result'
});
copy

timersPromises.setInterval([delay[, value[, options]]])#

返回一个异步迭代器，它以 delay 毫秒的间隔生成值。如果 ref 为 true，则需要显式或隐式调用异步迭代器的 next() 方法以保持事件循环处于活动状态。

• delay <number> 迭代之间等待的毫秒数。默认值： 1。
• value <any> 迭代器返回的值。
• options <Object>
• ref <boolean> 设置为 false 以表示迭代之间调度的 Timeout 不需要使 Node.js 事件循环保持活动状态。默认值： true。
• signal <AbortSignal> 可选的 AbortSignal，用于取消操作之间调度的 Timeout。

import {
  setInterval,
} from 'node:timers/promises';

const interval = 100;
for await (const startTime of setInterval(interval, Date.now())) {
  const now = Date.now();
  console.log(now);
  if ((now - startTime) > 1000)
    break;
}
console.log(Date.now());
const {
  setInterval,
} = require('node:timers/promises');
const interval = 100;

(async function() {
  for await (const startTime of setInterval(interval, Date.now())) {
    const now = Date.now();
    console.log(now);
    if ((now - startTime) > 1000)
      break;
  }
  console.log(Date.now());
})();
copy

timersPromises.scheduler.wait(delay[, options])#

• delay <number> 解析 promise 前等待的毫秒数。
• options <Object>
• ref <boolean> 设置为 false 以表示所调度的 Timeout 不需要使 Node.js 事件循环保持活动状态。默认值： true。
• signal <AbortSignal> 可选的 AbortSignal，用于取消等待。

这是一个实验性 API，由作为 Web 平台标准 API 开发的调度 API (Scheduling APIs) 草案规范定义。

调用 timersPromises.scheduler.wait(delay, options) 等同于调用 timersPromises.setTimeout(delay, undefined, options)。

import { scheduler } from 'node:timers/promises';

await scheduler.wait(1000); // Wait one second before continuing
copy

timersPromises.scheduler.yield()#

• 返回：<Promise>

这是一个实验性 API，由作为 Web 平台标准 API 开发的调度 API (Scheduling APIs) 草案规范定义。

调用 timersPromises.scheduler.yield() 等同于调用不带任何参数的 timersPromises.setImmediate()。