Node.js v21.7.2 文档

worker.getEnvironmentData(key)#

• key <any> 任何可克隆的任意 JavaScript 值，可作为 <Map> 的键。
• 返回值：<any>

在工作线程中，worker.getEnvironmentData() 返回传递给生成线程的 worker.setEnvironmentData() 的数据的克隆。每个新的 Worker 会自动收到环境数据的副本。

const {
  Worker,
  isMainThread,
  setEnvironmentData,
  getEnvironmentData,
} = require('node:worker_threads');

if (isMainThread) {
  setEnvironmentData('Hello', 'World!');
  const worker = new Worker(__filename);
} else {
  console.log(getEnvironmentData('Hello'));  // Prints 'World!'.
} copy

worker.isMainThread#

• <boolean>

如果此代码未在 Worker 线程中运行，则为 true。

const { Worker, isMainThread } = require('node:worker_threads');

if (isMainThread) {
  // This re-loads the current file inside a Worker instance.
  new Worker(__filename);
} else {
  console.log('Inside Worker!');
  console.log(isMainThread);  // Prints 'false'.
} copy

worker.markAsUntransferable(object)#

• object <any> 任何任意 JavaScript 值。

将对象标记为不可传输。如果 object 出现在 port.postMessage() 调用的传输列表中，则会抛出错误。如果 object 是一个原始值，则此操作为无操作。

特别是，这对于可以克隆而不是传输的对象很有意义，这些对象在发送方由其他对象使用。例如，Node.js 使用此方法标记其 Buffer 池 中使用的 ArrayBuffer。

此操作无法撤消。

const { MessageChannel, markAsUntransferable } = require('node:worker_threads');

const pooledBuffer = new ArrayBuffer(8);
const typedArray1 = new Uint8Array(pooledBuffer);
const typedArray2 = new Float64Array(pooledBuffer);

markAsUntransferable(pooledBuffer);

const { port1 } = new MessageChannel();
try {
  // This will throw an error, because pooledBuffer is not transferable.
  port1.postMessage(typedArray1, [ typedArray1.buffer ]);
} catch (error) {
  // error.name === 'DataCloneError'
}

// The following line prints the contents of typedArray1 -- it still owns
// its memory and has not been transferred. Without
// `markAsUntransferable()`, this would print an empty Uint8Array and the
// postMessage call would have succeeded.
// typedArray2 is intact as well.
console.log(typedArray1);
console.log(typedArray2); copy

浏览器中没有此 API 的等效项。

worker.isMarkedAsUntransferable(object)#

• object <any> 任何 JavaScript 值。
• 返回值：<boolean>

检查对象是否使用 markAsUntransferable() 标记为不可传输。

const { markAsUntransferable, isMarkedAsUntransferable } = require('node:worker_threads');

const pooledBuffer = new ArrayBuffer(8);
markAsUntransferable(pooledBuffer);

isMarkedAsUntransferable(pooledBuffer);  // Returns true. copy

浏览器中没有此 API 的等效项。

worker.moveMessagePortToContext(port, contextifiedSandbox)#

• port <MessagePort> 要传输的消息端口。

• contextifiedSandbox <Object> 由 vm.createContext() 方法返回的 上下文化 对象。

• 返回值: <MessagePort>

将 MessagePort 传输到不同的 vm 上下文。原始的 port 对象将变得不可用，返回的 MessagePort 实例将取代它。

返回的 MessagePort 是目标上下文中的一个对象，并继承自其全局 Object 类。传递给 port.onmessage() 监听器的对象也在目标上下文中创建，并继承自其全局 Object 类。

但是，创建的 MessagePort 不再继承自 EventTarget，并且只能使用 port.onmessage() 来接收使用它的事件。

worker.parentPort#

• <null> | <MessagePort>

如果此线程是 Worker，则这是一个 MessagePort，允许与父线程通信。使用 parentPort.postMessage() 发送的消息可以使用 worker.on('message') 在父线程中获得，而从父线程使用 worker.postMessage() 发送的消息可以使用 parentPort.on('message') 在此线程中获得。

const { Worker, isMainThread, parentPort } = require('node:worker_threads');

if (isMainThread) {
  const worker = new Worker(__filename);
  worker.once('message', (message) => {
    console.log(message);  // Prints 'Hello, world!'.
  });
  worker.postMessage('Hello, world!');
} else {
  // When a message from the parent thread is received, send it back:
  parentPort.once('message', (message) => {
    parentPort.postMessage(message);
  });
} copy

worker.receiveMessageOnPort(port)#

• port <MessagePort> | <BroadcastChannel>

• 返回值: <Object> | <undefined>

从给定的 MessagePort 接收单个消息。如果没有可用消息，则返回 undefined，否则返回一个具有单个 message 属性的对象，该属性包含消息有效负载，对应于 MessagePort 队列中最旧的消息。

const { MessageChannel, receiveMessageOnPort } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();
port1.postMessage({ hello: 'world' });

console.log(receiveMessageOnPort(port2));
// Prints: { message: { hello: 'world' } }
console.log(receiveMessageOnPort(port2));
// Prints: undefined copy

使用此函数时，不会发出 'message' 事件，也不会调用 onmessage 监听器。

worker.resourceLimits#

• <Object>
  • maxYoungGenerationSizeMb <number>
  • maxOldGenerationSizeMb <number>
  • codeRangeSizeMb <number>
  • stackSizeMb <number>

提供此 Worker 线程中 JS 引擎资源约束的集合。如果将 resourceLimits 选项传递给 Worker 构造函数，则此选项与其值匹配。

如果在主线程中使用此选项，则其值为一个空对象。

worker.SHARE_ENV#

• <symbol>

一个特殊值，可以作为 Worker 构造函数的 env 选项传递，以指示当前线程和 Worker 线程应共享对同一组环境变量的读写访问权限。

const { Worker, SHARE_ENV } = require('node:worker_threads');
new Worker('process.env.SET_IN_WORKER = "foo"', { eval: true, env: SHARE_ENV })
  .on('exit', () => {
    console.log(process.env.SET_IN_WORKER);  // Prints 'foo'.
  }); copy

worker.setEnvironmentData(key[, value])#

• key <any> 任何可克隆的任意 JavaScript 值，可作为 <Map> 的键。
• value <any> 任何任意可克隆的 JavaScript 值，它将被克隆并自动传递给所有新的 Worker 实例。如果将 value 作为 undefined 传递，则将删除之前为 key 设置的任何值。

worker.setEnvironmentData() API 设置当前线程和从当前上下文生成的任何新的 Worker 实例中 worker.getEnvironmentData() 的内容。

worker.threadId#

• <integer>

当前线程的整数标识符。在相应的 worker 对象上（如果有），它可用作 worker.threadId。此值对于单个进程中的每个 Worker 实例都是唯一的。

worker.workerData#

一个任意 JavaScript 值，它包含传递给此线程的 Worker 构造函数的数据的克隆。

数据被克隆，就像使用 postMessage() 一样，根据 HTML 结构化克隆算法。

const { Worker, isMainThread, workerData } = require('node:worker_threads');

if (isMainThread) {
  const worker = new Worker(__filename, { workerData: 'Hello, world!' });
} else {
  console.log(workerData);  // Prints 'Hello, world!'.
} copy

类：BroadcastChannel extends EventTarget#

BroadcastChannel 实例允许与绑定到相同通道名称的所有其他 BroadcastChannel 实例进行异步一对多通信。

'use strict';

const {
  isMainThread,
  BroadcastChannel,
  Worker,
} = require('node:worker_threads');

const bc = new BroadcastChannel('hello');

if (isMainThread) {
  let c = 0;
  bc.onmessage = (event) => {
    console.log(event.data);
    if (++c === 10) bc.close();
  };
  for (let n = 0; n < 10; n++)
    new Worker(__filename);
} else {
  bc.postMessage('hello from every worker');
  bc.close();
} copy

new BroadcastChannel(name)#

• name <any> 要连接的通道名称。允许任何可以使用 `${name}` 转换为字符串的 JavaScript 值。

broadcastChannel.close()#

关闭 BroadcastChannel 连接。

broadcastChannel.onmessage#

• 类型：<Function> 当收到消息时，使用单个 MessageEvent 参数调用。

broadcastChannel.onmessageerror#

• 类型：<Function> 当接收到的消息无法反序列化时调用。

broadcastChannel.postMessage(message)#

• message <any> 任何可克隆的 JavaScript 值。

broadcastChannel.ref()#

与 unref() 相反。在先前 unref() 的 BroadcastChannel 上调用 ref() 不会 允许程序在它是唯一剩余的活动句柄时退出（默认行为）。如果端口被 ref()，再次调用 ref() 不会有任何影响。

broadcastChannel.unref()#

在 BroadcastChannel 上调用 unref() 允许线程在这是事件系统中唯一剩余的活动句柄时退出。如果 BroadcastChannel 已经被 unref()，再次调用 unref() 不会有任何影响。

类：MessageChannel#

worker.MessageChannel 类的实例表示一个异步的双向通信通道。MessageChannel 本身没有方法。new MessageChannel() 会生成一个包含 port1 和 port2 属性的对象，它们分别引用链接的 MessagePort 实例。

const { MessageChannel } = require('node:worker_threads');

const { port1, port2 } = new MessageChannel();
port1.on('message', (message) => console.log('received', message));
port2.postMessage({ foo: 'bar' });
// Prints: received { foo: 'bar' } from the `port1.on('message')` listener copy

类: MessagePort#

• 扩展: <EventTarget>

worker.MessagePort 类的实例表示一个异步的双向通信通道的一端。它可以用于在不同的 Worker 之间传输结构化数据、内存区域和其他 MessagePort。

此实现与 浏览器 MessagePort 相匹配。

事件: 'close'#

当通道的任一端断开连接时，都会触发 'close' 事件。

const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();

// Prints:
//   foobar
//   closed!
port2.on('message', (message) => console.log(message));
port2.on('close', () => console.log('closed!'));

port1.postMessage('foobar');
port1.close(); copy

事件: 'message'#

• value <any> 传输的值

对于任何传入的消息，都会触发 'message' 事件，其中包含 port.postMessage() 的克隆输入。

此事件的监听器会收到传递给 postMessage() 的 value 参数的克隆，并且不会接收其他参数。

事件: 'messageerror'#

• error <Error> 错误对象

当反序列化消息失败时，会触发 'messageerror' 事件。

目前，当在接收端实例化已发布的 JS 对象时出现错误时，会触发此事件。这种情况很少见，但可能会发生，例如，当在 vm.Context 中接收某些 Node.js API 对象时（在 vm.Context 中，Node.js API 目前不可用）。

port.close()#

禁用连接双方进一步发送消息。当不再通过此MessagePort进行通信时，可以调用此方法。

频道中包含的两个MessagePort实例都会发出'close'事件。

port.postMessage(value[, transferList])#

• value <any>
• transferList <Object[]>

将 JavaScript 值发送到此通道的接收方。value 以与HTML 结构化克隆算法兼容的方式进行传输。

特别是，与JSON的显著区别在于

• value 可能包含循环引用。
• value 可能包含内置 JS 类型的实例，例如RegExp、BigInt、Map、Set等。
• value 可能包含类型化数组，包括使用ArrayBuffer和SharedArrayBuffer的数组。
• value 可能包含WebAssembly.Module实例。
• value 可能不包含本机（C++ 支持）对象，除了
  • <CryptoKey>s,
  • <FileHandle>s,
  • <Histogram>s,
  • <KeyObject>s,
  • <MessagePort>s,
  • <net.BlockList>s,
  • <net.SocketAddress>es,
  • <X509Certificate>s。

const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();

port1.on('message', (message) => console.log(message));

const circularData = {};
circularData.foo = circularData;
// Prints: { foo: [Circular] }
port2.postMessage(circularData); copy

transferList 可以是ArrayBuffer、MessagePort和FileHandle对象的列表。传输后，它们在通道的发送方不再可用（即使它们不包含在value中）。与子进程不同，目前不支持传输网络套接字等句柄。

如果value包含SharedArrayBuffer实例，则这些实例可从任一线程访问。它们不能列在transferList中。

value 可能仍然包含不在 transferList 中的 ArrayBuffer 实例；在这种情况下，底层内存将被复制而不是移动。

const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();

port1.on('message', (message) => console.log(message));

const uint8Array = new Uint8Array([ 1, 2, 3, 4 ]);
// This posts a copy of `uint8Array`:
port2.postMessage(uint8Array);
// This does not copy data, but renders `uint8Array` unusable:
port2.postMessage(uint8Array, [ uint8Array.buffer ]);

// The memory for the `sharedUint8Array` is accessible from both the
// original and the copy received by `.on('message')`:
const sharedUint8Array = new Uint8Array(new SharedArrayBuffer(4));
port2.postMessage(sharedUint8Array);

// This transfers a freshly created message port to the receiver.
// This can be used, for example, to create communication channels between
// multiple `Worker` threads that are children of the same parent thread.
const otherChannel = new MessageChannel();
port2.postMessage({ port: otherChannel.port1 }, [ otherChannel.port1 ]); copy

消息对象会立即被克隆，并且可以在发布后进行修改，而不会产生副作用。

有关此 API 背后的序列化和反序列化机制的更多信息，请参阅 node:v8 模块的序列化 API。

传输 TypedArray 和 Buffer 时的注意事项#

所有 TypedArray 和 Buffer 实例都是对底层 ArrayBuffer 的视图。也就是说，ArrayBuffer 实际上存储了原始数据，而 TypedArray 和 Buffer 对象提供了一种查看和操作数据的方法。可以并且通常会对同一个 ArrayBuffer 实例创建多个视图。使用传输列表传输 ArrayBuffer 时必须格外小心，因为这样做会导致所有共享该 ArrayBuffer 的 TypedArray 和 Buffer 实例变得不可用。

const ab = new ArrayBuffer(10);

const u1 = new Uint8Array(ab);
const u2 = new Uint16Array(ab);

console.log(u2.length);  // prints 5

port.postMessage(u1, [u1.buffer]);

console.log(u2.length);  // prints 0 copy

具体来说，对于 Buffer 实例，底层 ArrayBuffer 是否可以传输或克隆完全取决于实例的创建方式，而这通常无法可靠地确定。

可以使用 markAsUntransferable() 标记 ArrayBuffer，以指示它应该始终被克隆，而永远不会被传输。

根据 Buffer 实例的创建方式，它可能拥有也可能不拥有其底层 ArrayBuffer。除非确定 Buffer 实例拥有 ArrayBuffer，否则不得传输 ArrayBuffer。特别是，对于从内部 Buffer 池创建的 Buffer（例如使用 Buffer.from() 或 Buffer.allocUnsafe()），无法传输它们，并且它们始终被克隆，这会发送整个 Buffer 池的副本。这种行为可能会带来意外的更高内存使用量和潜在的安全问题。

有关 Buffer 池的更多详细信息，请参阅 Buffer.allocUnsafe()。

使用 Buffer.alloc() 或 Buffer.allocUnsafeSlow() 创建的 Buffer 实例的 ArrayBuffer 始终可以被传输，但这样做会使所有其他现有这些 ArrayBuffer 的视图变得不可用。

克隆具有原型、类和访问器的对象时的注意事项#

由于对象克隆使用 HTML 结构化克隆算法，因此不会保留不可枚举属性、属性访问器和对象原型。特别是，Buffer 对象将在接收方被读取为普通的 Uint8Array，JavaScript 类的实例将被克隆为普通的 JavaScript 对象。

const b = Symbol('b');

class Foo {
  #a = 1;
  constructor() {
    this[b] = 2;
    this.c = 3;
  }

  get d() { return 4; }
}

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => console.log(data);

port2.postMessage(new Foo());

// Prints: { c: 3 } copy

此限制扩展到许多内置对象，例如全局 URL 对象

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => console.log(data);

port2.postMessage(new URL('https://example.org'));

// Prints: { } copy

port.hasRef()#

• 返回值：<boolean>

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

port.ref()#

与 unref() 相反。如果之前对端口调用过 unref()，则再次调用 ref() 不会让程序在它是唯一剩余的活动句柄时退出（默认行为）。如果端口已 ref()，则再次调用 ref() 不会有任何效果。

如果使用 .on('message') 附加或删除监听器，则端口会根据事件监听器是否存在自动 ref() 和 unref()。

port.start()#

开始接收此 MessagePort 上的消息。当使用此端口作为事件发射器时，一旦附加了 'message' 监听器，就会自动调用此方法。

此方法存在是为了与 Web MessagePort API 保持一致。在 Node.js 中，它仅用于在没有事件监听器存在时忽略消息。Node.js 在处理 .onmessage 方面也有所不同。设置它会自动调用 .start()，但取消设置它会让消息排队，直到设置新的处理程序或丢弃端口。

port.unref()#

对端口调用 unref() 允许线程在它是事件系统中唯一剩余的活动句柄时退出。如果端口已经 unref()，则再次调用 unref() 不会有任何效果。

如果使用 .on('message') 附加或删除监听器，则端口会根据事件监听器是否存在自动 ref() 和 unref()。

类：Worker#

• 扩展：<EventEmitter>

Worker 类代表一个独立的 JavaScript 执行线程。大多数 Node.js API 都可以在其中使用。

在 Worker 环境中，一些显著的差异包括：

• process.stdin、process.stdout 和 process.stderr 流可能被父线程重定向。
• require('node:worker_threads').isMainThread 属性被设置为 false。
• require('node:worker_threads').parentPort 消息端口可用。
• process.exit() 不会停止整个程序，只会停止单个线程，而 process.abort() 则不可用。
• process.chdir() 和设置组或用户 ID 的 process 方法不可用。
• process.env 是父线程环境变量的副本，除非另有说明。对其中一个副本的更改不会在其他线程中可见，也不会对原生插件可见（除非将 worker.SHARE_ENV 作为 env 选项传递给 Worker 构造函数）。在 Windows 上，与主线程不同，环境变量的副本以区分大小写的方式运行。
• process.title 无法修改。
• 信号不会通过 process.on('...') 传递。
• 执行可能在任何时候停止，因为调用了 worker.terminate()。
• 来自父进程的 IPC 通道不可访问。
• 不支持 trace_events 模块。
• 只有满足 特定条件 的原生插件才能从多个线程加载。

可以在其他 Worker 中创建 Worker 实例。

类似于 Web Workers 和 node:cluster 模块，双向通信可以通过线程间消息传递实现。在内部，Worker 拥有一个内置的 MessagePort 对，它们在创建 Worker 时就已经相互关联。虽然父端上的 MessagePort 对象没有直接暴露，但其功能通过 worker.postMessage() 和父线程上 Worker 对象的 worker.on('message') 事件暴露出来。

为了创建自定义消息通道（建议使用自定义通道而不是默认的全局通道，因为它有利于分离关注点），用户可以在任一线程上创建 MessageChannel 对象，并通过预先存在的通道（例如全局通道）将该 MessageChannel 上的其中一个 MessagePort 传递给另一个线程。

有关消息传递方式以及哪些 JavaScript 值可以成功地跨线程传输的更多信息，请参阅 port.postMessage()。

const assert = require('node:assert');
const {
  Worker, MessageChannel, MessagePort, isMainThread, parentPort,
} = require('node:worker_threads');
if (isMainThread) {
  const worker = new Worker(__filename);
  const subChannel = new MessageChannel();
  worker.postMessage({ hereIsYourPort: subChannel.port1 }, [subChannel.port1]);
  subChannel.port2.on('message', (value) => {
    console.log('received:', value);
  });
} else {
  parentPort.once('message', (value) => {
    assert(value.hereIsYourPort instanceof MessagePort);
    value.hereIsYourPort.postMessage('the worker is sending this');
    value.hereIsYourPort.close();
  });
} copy

new Worker(filename[, options])#

• filename <string> | <URL> Worker 主脚本或模块的路径。必须是绝对路径或相对路径（即相对于当前工作目录），以 ./ 或 ../ 开头，或者使用 file: 或 data: 协议的 WHATWG URL 对象。当使用 data: URL 时，数据将根据 MIME 类型使用 ECMAScript 模块加载器 进行解释。如果 options.eval 为 true，则这是一个包含 JavaScript 代码的字符串，而不是路径。
• options <Object>
  • argv <any[]> 将被字符串化并附加到 worker 中 process.argv 的参数列表。这与 workerData 非常相似，但这些值在全局 process.argv 上可用，就像它们作为 CLI 选项传递给脚本一样。
  • env <Object> 如果设置，则指定 Worker 线程中 process.env 的初始值。作为特殊值，worker.SHARE_ENV 可用于指定父线程和子线程应共享其环境变量；在这种情况下，对一个线程的 process.env 对象的更改也会影响另一个线程。默认值： process.env。
  • eval <boolean> 如果为 true 并且第一个参数是 string，则将构造函数的第一个参数解释为在 worker 在线后执行的脚本。
  • execArgv <string[]> 传递给 worker 的 node CLI 选项列表。不支持 V8 选项（如 --max-old-space-size）和影响进程的选项（如 --title）。如果设置，则在 worker 内部提供为 process.execArgv。默认情况下，选项从父线程继承。
  • stdin <boolean> 如果设置为 true，则 worker.stdin 提供一个可写流，其内容显示为 Worker 中的 process.stdin。默认情况下，不提供任何数据。
  • stdout <boolean> 如果设置为 true，则 worker.stdout 不会自动通过管道传输到父级中的 process.stdout。
  • stderr <boolean> 如果设置为 true，则 worker.stderr 不会自动通过管道传输到父进程的 process.stderr。
  • workerData <any> 任何被克隆并作为 require('node:worker_threads').workerData 可用的 JavaScript 值。克隆过程如 HTML 结构化克隆算法 中所述，如果对象无法克隆（例如，因为它包含 function），则会抛出错误。
  • trackUnmanagedFds <boolean> 如果设置为 true，则 Worker 会跟踪通过 fs.open() 和 fs.close() 管理的原始文件描述符，并在 Worker 退出时关闭它们，类似于其他资源，例如通过 FileHandle API 管理的网络套接字或文件描述符。此选项会自动被所有嵌套的 Worker 继承。默认值： true。
  • transferList <Object[]> 如果在 workerData 中传递了一个或多个 MessagePort 类对象，则需要为这些项提供 transferList，否则会抛出 ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST 错误。有关更多信息，请参阅 port.postMessage()。
  • resourceLimits <Object> 新 JS 引擎实例的可选资源限制集。达到这些限制会导致 Worker 实例终止。这些限制仅影响 JS 引擎，不影响外部数据，包括任何 ArrayBuffer。即使设置了这些限制，如果进程遇到全局内存不足情况，它仍然可能中止。
    • maxOldGenerationSizeMb <number> 主堆的最大大小（以 MB 为单位）。如果设置了命令行参数 --max-old-space-size，它会覆盖此设置。
    • maxYoungGenerationSizeMb <number> 最近创建的对象的堆空间的最大大小。如果设置了命令行参数 --max-semi-space-size，它会覆盖此设置。
    • codeRangeSizeMb <number> 用于生成代码的预分配内存范围的大小。
    • stackSizeMb <number> 线程的默认最大堆栈大小。较小的值可能会导致 Worker 实例无法使用。默认值： 4。
  • name <string> 可选的 name，用于附加到工作线程标题，以便于调试/识别，最终标题为 [worker ${id}] ${name}。**默认值：** ''。

事件：'error'#

• err <Error>

如果工作线程抛出未捕获的异常，则会发出 'error' 事件。在这种情况下，工作线程将被终止。

事件：'exit'#

• exitCode <integer>

工作线程停止后会发出 'exit' 事件。如果工作线程通过调用 process.exit() 退出，则 exitCode 参数为传递的退出代码。如果工作线程被终止，则 exitCode 参数为 1。

这是任何 Worker 实例发出的最后一个事件。

事件：'message'#

• value <any> 传输的值

当工作线程调用 require('node:worker_threads').parentPort.postMessage() 时，会发出 'message' 事件。有关详细信息，请参阅 port.on('message') 事件。

从工作线程发送的所有消息都会在 Worker 对象上发出 'exit' 事件 之前发出。

事件：'messageerror'#

• error <Error> 错误对象

当反序列化消息失败时，会触发 'messageerror' 事件。

事件：'online'#

当工作线程开始执行 JavaScript 代码时，会发出 'online' 事件。

worker.getHeapSnapshot([options])#

• options <Object>
  • exposeInternals <boolean> 如果为 true，则在堆快照中公开内部信息。**默认值：** false。
  • exposeNumericValues <boolean> 如果为 true，则在人工字段中公开数值。**默认值：** false。
• 返回值：<Promise> 包含 V8 堆快照的可读流的 Promise

返回当前 Worker 状态的 V8 快照的可读流。有关更多详细信息，请参阅 v8.getHeapSnapshot()。

如果 Worker 线程不再运行（这可能发生在 'exit' 事件 触发之前），则返回的 Promise 会立即被拒绝，并出现 ERR_WORKER_NOT_RUNNING 错误。

worker.performance#

一个对象，可用于查询 Worker 实例的性能信息。类似于 perf_hooks.performance。

performance.eventLoopUtilization([utilization1[, utilization2]])#

• utilization1 <Object> eventLoopUtilization() 的先前调用的结果。
• utilization2 <Object> utilization1 之前 eventLoopUtilization() 的先前调用的结果。
• 返回值：<Object>
  • idle <number>
  • active <number>
  • utilization <number>

与 perf_hooks eventLoopUtilization() 相同的调用，只是返回了 Worker 实例的值。

不同之处在于，与主线程不同，Worker 中的引导是在事件循环中完成的。因此，一旦 Worker 的脚本开始执行，事件循环利用率就会立即可用。

idle 时间没有增加并不意味着 Worker 卡在引导阶段。以下示例显示了 Worker 的整个生命周期从未累积任何 idle 时间，但仍然能够处理消息。

const { Worker, isMainThread, parentPort } = require('node:worker_threads');

if (isMainThread) {
  const worker = new Worker(__filename);
  setInterval(() => {
    worker.postMessage('hi');
    console.log(worker.performance.eventLoopUtilization());
  }, 100).unref();
  return;
}

parentPort.on('message', () => console.log('msg')).unref();
(function r(n) {
  if (--n < 0) return;
  const t = Date.now();
  while (Date.now() - t < 300);
  setImmediate(r, n);
})(10); copy

只有在 'online' 事件 触发后，才能使用 Worker 的事件循环利用率。如果在此之前或 'exit' 事件 之后调用，则所有属性的值均为 0。

worker.postMessage(value[, transferList])#

• value <any>
• transferList <Object[]>

向 Worker 发送一条消息，该消息将通过 require('node:worker_threads').parentPort.on('message') 接收。有关更多详细信息，请参阅 port.postMessage()。

worker.ref()#

与 unref() 相反，对先前 unref() 的 worker 调用 ref() 不会 允许程序在它是唯一剩余的活动句柄时退出（默认行为）。如果 worker 被 ref()，再次调用 ref() 不会有任何效果。

worker.resourceLimits#

• <Object>
  • maxYoungGenerationSizeMb <number>
  • maxOldGenerationSizeMb <number>
  • codeRangeSizeMb <number>
  • stackSizeMb <number>

提供此 Worker 线程的 JS 引擎资源约束集。如果 resourceLimits 选项传递给 Worker 构造函数，则它与它的值匹配。

如果 worker 已停止，则返回值为空对象。

worker.stderr#

• <stream.Readable>

这是一个可读流，其中包含写入 worker 线程内部的 process.stderr 的数据。如果 stderr: true 未传递给 Worker 构造函数，则数据将被管道传输到父线程的 process.stderr 流。

worker.stdin#

• <null> | <stream.Writable>

如果 stdin: true 传递给 Worker 构造函数，则这是一个可写流。写入此流的数据将在 worker 线程中作为 process.stdin 提供。

worker.stdout#

• <stream.Readable>

这是一个可读流，其中包含写入 worker 线程内部的 process.stdout 的数据。如果 stdout: true 未传递给 Worker 构造函数，则数据将被管道传输到父线程的 process.stdout 流。

worker.terminate()#

• 返回值: <Promise>

尽快停止工作线程中的所有 JavaScript 执行。返回一个 Promise，用于在 'exit' 事件 发出时完成的退出代码。

worker.threadId#

• <integer>

引用线程的整数标识符。在工作线程内部，它可用作 require('node:worker_threads').threadId。此值对于单个进程中的每个 Worker 实例都是唯一的。

worker.unref()#

在工作线程上调用 unref() 允许线程在这是事件系统中唯一活动的句柄时退出。如果工作线程已经 unref()ed，再次调用 unref() 不会有任何影响。

注意#

stdio 的同步阻塞#

Worker 使用通过 <MessagePort> 的消息传递来实现与 stdio 的交互。这意味着来自 Worker 的 stdio 输出可能会被接收端上的同步代码阻塞，该代码阻塞了 Node.js 事件循环。

import {
  Worker,
  isMainThread,
} from 'worker_threads';

if (isMainThread) {
  new Worker(new URL(import.meta.url));
  for (let n = 0; n < 1e10; n++) {
    // Looping to simulate work.
  }
} else {
  // This output will be blocked by the for loop in the main thread.
  console.log('foo');
}'use strict';

const {
  Worker,
  isMainThread,
} = require('node:worker_threads');

if (isMainThread) {
  new Worker(__filename);
  for (let n = 0; n < 1e10; n++) {
    // Looping to simulate work.
  }
} else {
  // This output will be blocked by the for loop in the main thread.
  console.log('foo');
}copy

从预加载脚本启动工作线程#

从预加载脚本（使用 -r 命令行标志加载和运行的脚本）启动工作线程时要小心。除非显式设置 execArgv 选项，否则新的工作线程会自动继承运行进程的命令行标志，并将预加载与主线程相同的预加载脚本。如果预加载脚本无条件地启动工作线程，则每个生成的线程都会生成另一个线程，直到应用程序崩溃。