Node.js v25.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 通道將關閉，使其能夠優雅地退出。

上述內容*僅*適用於伺服器連線，客戶端連線不會被工作程序自動關閉，並且 disconnect 不會等待它們關閉後再退出。

在工作程序中，存在 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#

• 型別: <integer>

每個新的工作程序都會被賦予一個唯一的 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> 傳送給工作程序的 kill 訊號的名稱。預設值： '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