Node.js v24.0.0 文档

事件: 'disconnect'#

类似于 cluster.on('disconnect') 事件，但特定于此工作进程。

cluster.fork().on('disconnect', () => {
  // Worker has disconnected
}); copy

事件: 'error'#

此事件与 child_process.fork() 提供的事件相同。

在工作进程中，也可以使用 process.on('error')。

事件: 'exit'#

• code <number> 退出代码，如果它正常退出。
• signal <string> 导致进程被终止的信号名称（例如 'SIGHUP'）。

类似于 cluster.on('exit') 事件，但特定于此工作进程。

import cluster from 'node:cluster';

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('exit', (code, signal) => {
    if (signal) {
      console.log(`worker was killed by signal: ${signal}`);
    } else if (code !== 0) {
      console.log(`worker exited with error code: ${code}`);
    } else {
      console.log('worker success!');
    }
  });
}const cluster = require('node:cluster');

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('exit', (code, signal) => {
    if (signal) {
      console.log(`worker was killed by signal: ${signal}`);
    } else if (code !== 0) {
      console.log(`worker exited with error code: ${code}`);
    } else {
      console.log('worker success!');
    }
  });
}copy

事件: 'listening'#

• address <Object>

类似于 cluster.on('listening') 事件，但特定于此工作进程。

cluster.fork().on('listening', (address) => {
  // Worker is listening
});cluster.fork().on('listening', (address) => {
  // Worker is listening
});copy

它不会在工作进程中发出。

事件: 'message'#

• message <Object>
• handle <undefined> | <Object>

类似于 cluster 的 'message' 事件，但特定于此工作进程。

在工作进程中，也可以使用 process.on('message')。

请参阅 process 事件：'message'。

这是一个使用消息系统的示例。 它在主进程中保留工作进程收到的 HTTP 请求数的计数

import cluster from 'node:cluster';
import http from 'node:http';
import { availableParallelism } from 'node:os';
import process from 'node:process';

if (cluster.isPrimary) {

  // Keep track of http requests
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // Count requests
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // Start workers and listen for messages containing notifyRequest
  const numCPUs = availableParallelism();
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  for (const id in cluster.workers) {
    cluster.workers[id].on('message', messageHandler);
  }

} else {

  // Worker processes have a http server.
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // Notify primary about the request
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();
const process = require('node:process');

if (cluster.isPrimary) {

  // Keep track of http requests
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // Count requests
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // Start workers and listen for messages containing notifyRequest
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  for (const id in cluster.workers) {
    cluster.workers[id].on('message', messageHandler);
  }

} else {

  // Worker processes have a http server.
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // Notify primary about the request
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}copy

事件: 'online'#

类似于 cluster.on('online') 事件，但特定于此工作进程。

cluster.fork().on('online', () => {
  // Worker is online
}); copy

它不会在工作进程中发出。

worker.disconnect()#

• 返回: <cluster.Worker> 对 worker 的引用。

在工作进程中，此函数将关闭所有服务器，等待这些服务器上的 'close' 事件，然后断开 IPC 通道。

在主进程中，内部消息被发送到工作进程，导致它在自身上调用 .disconnect()。

导致设置 .exitedAfterDisconnect。

服务器关闭后，它将不再接受新连接，但任何其他侦听工作进程都可以接受连接。 现有连接将像往常一样被允许关闭。 当不再存在连接时，请参阅 server.close()，到工作进程的 IPC 通道将关闭，允许它正常死亡。

以上内容仅适用于服务器连接，客户端连接不会被工作进程自动关闭，并且断开连接不会等待它们关闭后再退出。

在工作进程中，存在 process.disconnect，但它不是此函数；它是 disconnect()。

由于长时间存在的服务器连接可能会阻止工作进程断开连接，因此发送消息可能很有用，这样可以采取特定于应用程序的操作来关闭它们。 实现超时也可能很有用，如果在一段时间后未发出 'disconnect' 事件，则终止工作进程。

if (cluster.isPrimary) {
  const worker = cluster.fork();
  let timeout;

  worker.on('listening', (address) => {
    worker.send('shutdown');
    worker.disconnect();
    timeout = setTimeout(() => {
      worker.kill();
    }, 2000);
  });

  worker.on('disconnect', () => {
    clearTimeout(timeout);
  });

} else if (cluster.isWorker) {
  const net = require('node:net');
  const server = net.createServer((socket) => {
    // Connections never end
  });

  server.listen(8000);

  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      // Initiate graceful close of any connections to server
    }
  });
} copy

worker.exitedAfterDisconnect#

• <boolean>

如果工作进程因 .disconnect() 而退出，则此属性为 true。如果工作进程以任何其他方式退出，则为 false。如果工作进程尚未退出，则为 undefined。

布尔值 worker.exitedAfterDisconnect 允许区分自愿退出和意外退出，主进程可能会根据此值选择不重新生成工作进程。

cluster.on('exit', (worker, code, signal) => {
  if (worker.exitedAfterDisconnect === true) {
    console.log('Oh, it was just voluntary – no need to worry');
  }
});

// kill worker
worker.kill(); copy

worker.id#

• <整数>

每个新的工作进程都会被赋予一个唯一的 ID，此 ID 存储在 id 中。

当工作进程处于活动状态时，它就是 cluster.workers 中索引它的键。

worker.isConnected()#

如果工作进程通过其 IPC 通道连接到主进程，则此函数返回 true，否则返回 false。 工作进程在创建后连接到其主进程。 在发出 'disconnect' 事件后，它将被断开连接。

worker.isDead()#

如果工作进程已终止（由于退出或被发出信号），则此函数返回 true。 否则，它返回 false。

import cluster from 'node:cluster';
import http from 'node:http';
import { availableParallelism } from 'node:os';
import process from 'node:process';

const numCPUs = availableParallelism();

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('fork', (worker) => {
    console.log('worker is dead:', worker.isDead());
  });

  cluster.on('exit', (worker, code, signal) => {
    console.log('worker is dead:', worker.isDead());
  });
} else {
  // Workers can share any TCP connection. In this case, it is an HTTP server.
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Current process\n ${process.pid}`);
    process.kill(process.pid);
  }).listen(8000);
}const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();
const process = require('node:process');

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('fork', (worker) => {
    console.log('worker is dead:', worker.isDead());
  });

  cluster.on('exit', (worker, code, signal) => {
    console.log('worker is dead:', worker.isDead());
  });
} else {
  // Workers can share any TCP connection. In this case, it is an HTTP server.
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Current process\n ${process.pid}`);
    process.kill(process.pid);
  }).listen(8000);
}copy

worker.kill([signal])#

• signal <string> 要发送到工作进程的终止信号的名称。 默认值: 'SIGTERM'

此函数将终止工作进程。 在主工作进程中，它通过断开 worker.process 的连接来实现这一点，并在断开连接后，使用 signal 终止。 在工作进程中，它通过使用 signal 终止进程来实现这一点。

kill() 函数终止工作进程，而不等待正常断开连接，它的行为与 worker.process.kill() 相同。

为了向后兼容，此方法别名为 worker.destroy()。

在工作进程中，process.kill() 存在，但它不是此函数；它是 kill()。

worker.process#

• <ChildProcess>

所有工作进程都是使用 child_process.fork() 创建的，此函数返回的对象存储为 .process。 在工作进程中，存储的是全局 process。

参见: 子进程模块。

如果 process 上发生 'disconnect' 事件，并且 .exitedAfterDisconnect 不是 true，则工作进程将调用 process.exit(0)。 这样可以防止意外断开连接。

worker.send(message[, sendHandle[, options]][, callback])#

• message <Object>
• sendHandle <Handle>
• options <Object> options 参数（如果存在）是一个对象，用于参数化发送某些类型的句柄。 options 支持以下属性
  • keepOpen <boolean> 可在传递 net.Socket 实例时使用的值。 当 true 时，套接字在发送进程中保持打开状态。 默认值: false。
• callback <Function>
• 返回: <boolean>

向工作进程或主进程发送消息，可以选择带句柄。

在主进程中，这会将消息发送到特定的工作进程。 它与 ChildProcess.send() 相同。

在工作进程中，这会将消息发送到主进程。 它与 process.send() 相同。

此示例将回显来自主进程的所有消息

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.send('hi there');

} else if (cluster.isWorker) {
  process.on('message', (msg) => {
    process.send(msg);
  });
} copy