Node.js v21.7.2 文件

程序事件#

process 物件是 EventEmitter 的一個實體。

事件：'beforeExit'#

當 Node.js 清空事件迴圈且沒有其他工作要排程時，就會發出 'beforeExit' 事件。通常，當沒有排程工作時，Node.js 程序就會結束，但註冊在 'beforeExit' 事件上的監聽器可以進行非同步呼叫，從而導致 Node.js 程序繼續執行。

監聽器 callback 函式會呼叫，並將 process.exitCode 的值作為唯一的引數傳遞。

'beforeExit' 事件不會針對導致明確終止的條件發出，例如呼叫 process.exit() 或未捕捉的例外狀況。

'beforeExit' 不應用作 'exit' 事件的替代方案，除非目的是安排其他工作。

import process from 'node:process';

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0const process = require('node:process');

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0copy

事件：'disconnect'#

如果 Node.js 程序使用 IPC 通道衍生（請參閱 子程序 和 叢集 文件），當 IPC 通道關閉時，將會發出 'disconnect' 事件。

事件：'exit'#

• code <整數>

'exit' 事件會在 Node.js 程序準備退出時發出，原因可能是

• 明確呼叫 process.exit() 方法；
• Node.js 事件迴圈不再有任何其他工作要執行。

此時無法防止事件迴圈退出，且一旦所有 'exit' 監聽器執行完畢，Node.js 程序就會終止。

監聽器回呼函式會呼叫 process.exitCode 屬性或傳遞給 process.exit() 方法的 exitCode 引數所指定的退出碼。

import process from 'node:process';

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});const process = require('node:process');

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});copy

監聽器函式必須只執行同步作業。Node.js 程序會在呼叫 'exit' 事件監聽器後立即退出，導致事件迴圈中排隊的任何其他工作都被放棄。例如，在以下範例中，逾時情況永遠不會發生

import process from 'node:process';

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});const process = require('node:process');

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});copy

事件：'message'#

• message <Object> | <boolean> | <number> | <string> | <null> 已剖析的 JSON 物件或可序列化基本值。
• sendHandle <net.Server> | <net.Socket> net.Server 或 net.Socket 物件，或未定義。

如果 Node.js 程序使用 IPC 通道產生 (請參閱 子程序 和 叢集 文件)，則每當子程序收到父程序使用 childprocess.send() 傳送的訊息時，就會發出 'message' 事件。

訊息會經過序列化和剖析。產生的訊息可能與最初傳送的訊息不同。

如果在產生程序時將 serialization 選項設定為 advanced，則 message 參數可以包含 JSON 無法表示的資料。請參閱 child_process 的進階序列化 以取得更多詳細資料。

事件：'multipleResolves'#

• type <string> 解析類型。'resolve' 或 'reject' 之一。
• promise <Promise> 已解析或拒絕多次的承諾。
• value <any> 承諾在原始解析後已解析或拒絕的值。

每當 Promise 已

• 解析多次。
• 拒絕多次。
• 在解析後拒絕。
• 在拒絕後解析。

就會發出 'multipleResolves' 事件。這有助於追蹤使用 Promise 建構函式時應用程式中的潛在錯誤，因為會在不通知的情況下吞掉多次解析。不過，這個事件的發生並不一定表示有錯誤。例如，Promise.race() 會觸發 'multipleResolves' 事件。

由於在像上述 Promise.race() 範例中的情況中，事件不可靠，因此已將它標示為已不建議使用。

import process from 'node:process';

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason);
  setImmediate(() => process.exit(1));
});

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call');
      resolve('Swallowed resolve');
      reject(new Error('Swallowed reject'));
    });
  } catch {
    throw new Error('Failed');
  }
}

main().then(console.log);
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First callconst process = require('node:process');

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason);
  setImmediate(() => process.exit(1));
});

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call');
      resolve('Swallowed resolve');
      reject(new Error('Swallowed reject'));
    });
  } catch {
    throw new Error('Failed');
  }
}

main().then(console.log);
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First callcopy

事件：'rejectionHandled'#

• promise <Promise> 延遲處理的承諾。

每當 Promise 已拒絕，且在 Node.js 事件迴圈的一輪執行時間之後才附加錯誤處理常式（例如使用 promise.catch()），就會發出 'rejectionHandled' 事件。

Promise 物件之前會在 'unhandledRejection' 事件中發出，但在處理過程中取得拒絕處理常式。

Promise 鏈中沒有頂層的概念，可以永遠處理拒絕。由於本質上是異步的，Promise 拒絕可以在將來的某個時間點處理，可能遠遠晚於發出 'unhandledRejection' 事件的事件迴圈轉動。

另一種說法是，與同步程式碼中不斷增長的未處理例外清單不同，使用 Promises 時可能會有增長和縮小的未處理拒絕清單。

在同步程式碼中，當未處理例外清單增長時，會發出 'uncaughtException' 事件。

在異步程式碼中，當未處理拒絕清單增長時，會發出 'unhandledRejection' 事件，當未處理拒絕清單縮小時，會發出 'rejectionHandled' 事件。

import process from 'node:process';

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});const process = require('node:process');

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});copy

在此範例中，unhandledRejections Map 會隨著時間增長和縮小，反映從未處理開始然後變成已處理的拒絕。可以定期（對於長時間執行的應用程式來說可能是最好的）或在處理程序退出時（對於腳本來說可能是最方便的）將此類錯誤記錄在錯誤記錄中。

事件：'uncaughtException'#

• err <Error> 未捕捉的例外。
• origin <字串> 指出例外是來自未處理的拒絕或同步錯誤。可以是 'uncaughtException' 或 'unhandledRejection'。後者用於在基於 Promise 的非同步內容中發生例外（或 Promise 被拒絕）以及 --unhandled-rejections 標幟設定為 strict 或 throw（這是預設值）且拒絕未被處理，或在命令列進入點的 ES 模組靜態載入階段發生拒絕時。

當未捕捉到的 JavaScript 例外一直冒泡回事件迴圈時，會發出 'uncaughtException' 事件。預設情況下，Node.js 會透過將堆疊追蹤列印到 stderr 並以程式碼 1 退出，覆寫任何先前設定的 process.exitCode 來處理此類例外。新增 'uncaughtException' 事件的處理常式會覆寫此預設行為。或者，在 'uncaughtException' 處理常式中變更 process.exitCode，這將導致處理程序以提供的退出程式碼退出。否則，在有此類處理常式的情況下，處理程序將以 0 退出。

import process from 'node:process';
import fs from 'node:fs';

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}\n`,
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');const process = require('node:process');
const fs = require('node:fs');

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}\n`,
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');copy

透過安裝 'uncaughtExceptionMonitor' 監聽器，可以監控 'uncaughtException' 事件，而不會覆寫退出處理程序的預設行為。

警告：正確使用 'uncaughtException'#

'uncaughtException' 是一種用於例外處理的粗糙機制，僅供最後手段使用。此事件不應用作等同於 On Error Resume Next。未處理的例外本質上表示應用程式處於未定義的狀態。嘗試在未從例外中適當復原的情況下繼續應用程式程式碼，可能會導致其他無法預見且無法預測的問題。

從事件處理常式內引發的例外不會被捕捉。相反地，處理程序將以非零退出程式碼退出，並且堆疊追蹤將被列印。這是為了避免無限遞迴。

在未捕捉到的例外後嘗試正常繼續，可能類似於在升級電腦時拔掉電源線。十次中有九次，什麼事也不會發生。但第十次，系統就會損毀。

正確使用 'uncaughtException' 是在關閉程序前執行已配置資源的同步清理（例如檔案描述符、控制代碼等）。在 'uncaughtException' 之後恢復正常運作並不安全。

若要以更可靠的方式重新啟動已當掉的應用程式，無論是否發出 'uncaughtException'，都應在個別程序中使用外部監視器來偵測應用程式故障，並視需要復原或重新啟動。

事件：'uncaughtExceptionMonitor'#

• err <Error> 未捕捉的例外。
• origin <string> 指出例外狀況是否來自於未處理的拒絕或同步錯誤。可以是 'uncaughtException' 或 'unhandledRejection'。後者用於在基於 Promise 的非同步內容中發生例外狀況（或如果 Promise 被拒絕）以及 --unhandled-rejections 旗標設定為 strict 或 throw（這是預設值）且拒絕未被處理，或在命令列進入點的 ES 模組靜態載入階段發生拒絕時使用。

'uncaughtExceptionMonitor' 事件會在發出 'uncaughtException' 事件或呼叫透過 process.setUncaughtExceptionCaptureCallback() 安裝的掛勾之前發出。

安裝 'uncaughtExceptionMonitor' 監聽器不會在發出 'uncaughtException' 事件後改變行為。如果未安裝 'uncaughtException' 監聽器，程序仍會當掉。

import process from 'node:process';

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.jsconst process = require('node:process');

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.jscopy

事件：'unhandledRejection'#

• reason <Error> | <any> 拒絕承諾的物件（通常是 Error 物件）。
• promise <Promise> 被拒絕的承諾。

每當 Promise 被拒絕，且在事件循環的一輪內沒有錯誤處理常式附加到承諾時，就會發出 'unhandledRejection' 事件。使用承諾進行程式設計時，例外狀況會封裝為「被拒絕的承諾」。拒絕可以使用 promise.catch() 捕捉和處理，並透過 Promise 鏈傳播。'unhandledRejection' 事件對於偵測和追蹤尚未處理其拒絕的被拒絕承諾很有用。

import process from 'node:process';

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`const process = require('node:process');

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`copy

下列情況也會觸發發出 'unhandledRejection' 事件

import process from 'node:process';

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turnconst process = require('node:process');

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turncopy

在此範例案例中，可以將拒絕追蹤為開發人員錯誤，這通常會是其他 'unhandledRejection' 事件的情況。若要解決此類失敗，可以將非運作的 .catch(() => { }) 處理常式附加到 resource.loaded，這會防止發出 'unhandledRejection' 事件。

事件：'warning'#

• warning <Error> 警告的主要屬性為
  • name <string> 警告的名稱。預設：'Warning'。
  • message <字串> 系統提供的警告說明。
  • stack <字串> 發出警告的程式碼位置的堆疊追蹤。

每當 Node.js 發出處理程序警告時，就會發出 'warning' 事件。

處理程序警告類似於錯誤，在於它描述了引起使用者注意的異常狀況。但是，警告不屬於一般的 Node.js 和 JavaScript 錯誤處理流程。每當 Node.js 偵測到可能導致應用程式效能不佳、錯誤或安全漏洞的錯誤編碼實務時，就會發出警告。

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});const process = require('node:process');

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});copy

預設情況下，Node.js 會將處理程序警告列印到 stderr。可以使用 --no-warnings 命令列選項來抑制預設的控制台輸出，但 'warning' 事件仍會由 process 物件發出。目前，無法抑制廢棄警告以外的特定警告類型。若要抑制廢棄警告，請查看 --no-deprecation 旗標。

以下範例說明當有太多監聽器加入事件時，列印到 stderr 的警告

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leak
detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit copy

相反地，以下範例關閉預設警告輸出，並將自訂處理常式加入 'warning' 事件

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Do not do that!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Do not do that! copy

可以使用 --trace-warnings 命令列選項，讓警告的預設控制台輸出包含警告的完整堆疊追蹤。

使用 --throw-deprecation 命令列旗標啟動 Node.js，會導致自訂廢棄警告以例外狀況的形式擲出。

使用 --trace-deprecation 命令列旗標，會導致自訂廢棄警告連同堆疊追蹤一起列印到 stderr。

使用 --no-deprecation 命令列旗標，會抑制所有自訂廢棄警告的報告。

*-deprecation 命令列旗標只會影響使用名稱 'DeprecationWarning' 的警告。

發出自訂警告#

請參閱 process.emitWarning() 方法，以發出自訂或應用程式特定的警告。

Node.js 警告名稱#

Node.js 發出的警告類型（由 name 屬性識別）沒有嚴格的準則。隨時可以新增新的警告類型。最常見的幾種警告類型包括

• 'DeprecationWarning' - 表示使用已棄用的 Node.js API 或功能。此類警告必須包含一個 'code' 屬性，用於識別 棄用代碼。
• 'ExperimentalWarning' - 表示使用實驗性的 Node.js API 或功能。此類功能必須謹慎使用，因為它們可能會隨時變更，且不受與受支援功能相同的嚴格語意版本控制和長期支援政策約束。
• 'MaxListenersExceededWarning' - 表示已在 EventEmitter 或 EventTarget 上註冊了太多特定事件的監聽器。這通常表示有記憶體外洩。
• 'TimeoutOverflowWarning' - 表示已將無法放入 32 位元有號整數的數字值提供給 setTimeout() 或 setInterval() 函式。
• 'UnsupportedWarning' - 表示使用不受支援的選項或功能，這些選項或功能將被忽略，而不是視為錯誤處理。一個範例是在使用 HTTP/2 相容性 API 時使用 HTTP 回應狀態訊息。

事件：'worker'#

• worker <Worker> 已建立的 <Worker>。

在建立新的 <Worker> 執行緒後，會發出 'worker' 事件。

訊號事件#

當 Node.js 程序收到訊號時，將會發出訊號事件。請參閱 signal(7)，以取得標準 POSIX 訊號名稱的清單，例如 'SIGINT'、'SIGHUP' 等。

訊號在 Worker 執行緒中不可用。

訊號處理常式將會收到訊號名稱（'SIGINT'、'SIGTERM' 等）作為第一個參數。

每個事件的名稱將會是訊號的大寫通用名稱（例如 SIGINT 訊號的 'SIGINT'）。

import process from 'node:process';

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);const process = require('node:process');

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);copy

• 'SIGUSR1' 已被 Node.js 保留，用於啟動 偵錯器。可以安裝監聽器，但這樣可能會干擾偵錯器。
• 在非 Windows 平台上，'SIGTERM' 和 'SIGINT' 有預設處理常式，在退出並傳回程式碼 128 + 訊號號碼 之前，會重設終端機模式。如果其中一個訊號已安裝監聽器，其預設行為將會被移除（Node.js 將不再退出）。
• 預設情況下，'SIGPIPE' 會被忽略。可以安裝監聽器。
• 當主控台視窗關閉時，'SIGHUP' 會在 Windows 上產生，而在其他平台上則會在各種類似情況下產生。請參閱 signal(7)。可以安裝監聽器，但是大約 10 秒後，Windows 將無條件終止 Node.js。在非 Windows 平台上，SIGHUP 的預設行為是終止 Node.js，但一旦安裝了監聽器，其預設行為將會被移除。
• 'SIGTERM' 在 Windows 上不受支援，可以監聽。
• 來自終端機的 'SIGINT' 在所有平台上都受支援，通常可以使用 Ctrl+C 產生（儘管這可能是可設定的）。當 終端機原始模式 已啟用且使用 Ctrl+C 時，不會產生。
• 當按下 Ctrl+Break 時，Windows 上會傳送 'SIGBREAK'。在非 Windows 平台上，可以監聽它，但無法傳送或產生它。
• 當主控台已調整大小時，會傳送 'SIGWINCH'。在 Windows 上，這只會在寫入主控台時發生，當游標正在移動時，或當可讀取的 tty 在原始模式下使用時。
• 'SIGKILL' 無法安裝監聽器，它會在所有平台上無條件終止 Node.js。
• 'SIGSTOP' 無法安裝監聽器。
• 當未使用 kill(2) 人為引發時，'SIGBUS'、'SIGFPE'、'SIGSEGV' 和 'SIGILL' 本質上會讓程序處於無法安全呼叫 JS 監聽器的狀態。這樣做可能會導致程序停止回應。
• 可以傳送 0 來測試程序是否存在，如果程序存在，它不會產生任何效果，但如果程序不存在，它會擲出錯誤。

Windows 不支援訊號，因此沒有等效於訊號終止，但 Node.js 提供了一些模擬，包括 process.kill() 和 subprocess.kill()

• 傳送 SIGINT、SIGTERM 和 SIGKILL 會導致目標程序無條件終止，之後，subprocess 會報告該程序已由訊號終止。
• 傳送訊號 0 可用作平台獨立的方式來測試程序是否存在。

process.abort()#

process.abort() 方法會導致 Node.js 程序立即退出並產生核心檔案。

此功能在 Worker 執行緒中不可用。

process.allowedNodeEnvironmentFlags#

• <Set>

process.allowedNodeEnvironmentFlags 屬性是一個特殊的唯讀 Set，允許在 NODE_OPTIONS 環境變數中使用。

process.allowedNodeEnvironmentFlags 擴充了 Set，但覆寫了 Set.prototype.has 以識別數個不同的可能旗標表示法。process.allowedNodeEnvironmentFlags.has() 在下列情況下會傳回 true

• 旗標可以省略開頭的單破折號 (-) 或雙破折號 (--)；例如，--inspect-brk 的 inspect-brk，或 -r 的 r。
• 傳遞到 V8 的旗標（如 --v8-options 中所列）可以將一個或多個非開頭破折號替換為底線，反之亦然；例如，--perf_basic_prof、--perf-basic-prof、--perf_basic-prof 等。
• 旗標可以包含一個或多個等號 (=) 字元；等號之後（包含等號）的所有字元都將被忽略；例如，--stack-trace-limit=100。
• 旗標必須允許在 NODE_OPTIONS 中使用。

在遍歷 process.allowedNodeEnvironmentFlags 時，旗標只會出現一次；每個旗標都會以一個或多個破折號開頭。傳遞到 V8 的旗標會包含底線，而不是非開頭的破折號

import { allowedNodeEnvironmentFlags } from 'node:process';

allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});const { allowedNodeEnvironmentFlags } = require('node:process');

allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});copy

process.allowedNodeEnvironmentFlags 的 add()、clear() 和 delete() 方法不執行任何動作，且會靜默失敗。

如果 Node.js 是不使用 NODE_OPTIONS 支援編譯的（顯示在 process.config 中），process.allowedNodeEnvironmentFlags 將會包含原本允許的內容。

process.arch#

• <字串>

編譯 Node.js 二進位檔所使用的作業系統 CPU 架構。可能的數值為：'arm'、'arm64'、'ia32'、'loong64'、'mips'、'mipsel'、'ppc'、'ppc64'、'riscv64'、's390'、's390x' 和 'x64'。

import { arch } from 'node:process';

console.log(`This processor architecture is ${arch}`);const { arch } = require('node:process');

console.log(`This processor architecture is ${arch}`);copy

process.argv#

• <字串陣列>

process.argv 屬性會傳回一個陣列，其中包含啟動 Node.js 程序時所傳遞的命令列引數。第一個元素會是 process.execPath。如果需要存取 argv[0] 的原始值，請參閱 process.argv0。第二個元素會是正在執行的 JavaScript 檔案路徑。其餘元素會是任何其他命令列引數。

例如，假設 process-args.js 的腳本如下

import { argv } from 'node:process';

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});const { argv } = require('node:process');

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});copy

以下列方式啟動 Node.js 程序

node process-args.js one two=three four copy

會產生下列輸出

0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four copy

process.argv0#

• <字串>

process.argv0 屬性會儲存 Node.js 啟動時傳遞的 argv[0] 原始值的唯讀副本。

$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0' copy

process.channel#

• <物件>

如果 Node.js 程序使用 IPC 通道衍生（請參閱子程序文件），則 process.channel 屬性會參考 IPC 通道。如果沒有 IPC 通道，則此屬性為 undefined。

process.channel.ref()#

如果之前已呼叫 .unref()，則此方法會讓 IPC 通道保持程序的事件迴圈執行。

通常，這會透過 process 物件上的 'disconnect' 和 'message' 監聽器數量來管理。但是，可以使用此方法明確要求特定行為。

process.channel.unref()#

此方法會讓 IPC 通道不保持程序的事件迴圈執行，並讓它在通道開啟時也能完成。

通常，這會透過 process 物件上的 'disconnect' 和 'message' 監聽器數量來管理。但是，可以使用此方法明確要求特定行為。

process.chdir(directory)#

• directory <string>

process.chdir() 方法會變更 Node.js 程序的目前工作目錄，或是在執行失敗時擲回例外（例如，如果指定的 directory 不存在）。

import { chdir, cwd } from 'node:process';

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}const { chdir, cwd } = require('node:process');

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}copy

此功能在 Worker 執行緒中不可用。

process.config#

• <物件>

process.config 屬性會傳回一個凍結的 Object，其中包含用於編譯目前 Node.js 可執行檔的組態選項的 JavaScript 表示形式。這與執行 ./configure 指令碼時產生的 config.gypi 檔案相同。

可能的輸出的範例如下

{
  target_defaults:
   { cflags: [],
     default_configuration: 'Release',
     defines: [],
     include_dirs: [],
     libraries: [] },
  variables:
   {
     host_arch: 'x64',
     napi_build_version: 5,
     node_install_npm: 'true',
     node_prefix: '',
     node_shared_cares: 'false',
     node_shared_http_parser: 'false',
     node_shared_libuv: 'false',
     node_shared_zlib: 'false',
     node_use_openssl: 'true',
     node_shared_openssl: 'false',
     strict_aliasing: 'true',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
} copy

process.connected#

• <boolean>

如果 Node.js 程序是使用 IPC 通道衍生的（請參閱 子程序 和 叢集 文件），只要 IPC 通道已連線，process.connected 屬性就會傳回 true，而呼叫 process.disconnect() 之後，會傳回 false。

一旦 process.connected 為 false，就不可能再使用 process.send() 透過 IPC 通道傳送訊息。

process.constrainedMemory()#

• <number> | <undefined>

取得基於作業系統限制的程序可用記憶體量（以位元組為單位）。如果沒有這樣的限制，或限制未知，則傳回 undefined。

請參閱 uv_get_constrained_memory 以取得更多資訊。

process.cpuUsage([previousValue])#

• previousValue <Object> 呼叫 process.cpuUsage() 的前一個傳回值
• 傳回：<Object>
  • user <整數>
  • system <整數>

process.cpuUsage() 方法會傳回目前程序的使用者和系統 CPU 時間使用量，物件中包含 user 和 system 屬性，其值為微秒值（百萬分之一秒）。這些值分別衡量在使用者和系統程式碼中花費的時間，如果有多個 CPU 核心為此程序執行工作，最終可能會大於實際經過時間。

可以將先前呼叫 process.cpuUsage() 的結果傳遞為函式的引數，以取得差異讀數。

import { cpuUsage } from 'node:process';

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }const { cpuUsage } = require('node:process');

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }copy

process.cwd()#

• 傳回：<字串>

process.cwd() 方法會傳回 Node.js 程序目前的作業目錄。

import { cwd } from 'node:process';

console.log(`Current directory: ${cwd()}`);const { cwd } = require('node:process');

console.log(`Current directory: ${cwd()}`);copy

process.debugPort#

• <數字>

啟用時，Node.js 除錯工具使用的埠。

import process from 'node:process';

process.debugPort = 5858;const process = require('node:process');

process.debugPort = 5858;copy

process.disconnect()#

如果 Node.js 程序使用 IPC 通道產生（請參閱 子程序 和 叢集 文件），process.disconnect() 方法會關閉與父程序的 IPC 通道，讓子程序在沒有其他連線維持其運作後正常結束。

呼叫 process.disconnect() 的效果與從父程序呼叫 ChildProcess.disconnect() 相同。

如果 Node.js 程序未使用 IPC 通道產生，process.disconnect() 會為 undefined。

process.dlopen(module, filename[, flags])#

• module <Object>
• filename <string>
• flags <os.constants.dlopen> 預設值： os.constants.dlopen.RTLD_LAZY

process.dlopen() 方法允許動態載入共用物件。它主要由 require() 用於載入 C++ 外掛程式，且不應直接使用，除非在特殊情況下。換句話說，除非有特定原因，例如自訂 dlopen 旗標或從 ES 模組載入，否則應優先使用 require() 而非 process.dlopen()。

flags 參數是一個整數，允許指定 dlopen 行為。有關詳細資訊，請參閱 os.constants.dlopen 文件。

呼叫 process.dlopen() 時的一個重要需求是必須傳遞 module 執行個體。然後，可透過 module.exports 存取 C++ 外掛程式匯出的函式。

以下範例顯示如何載入名為 local.node 的 C++ 外掛程式，該外掛程式匯出 foo 函式。透過傳遞 RTLD_NOW 常數，在呼叫傳回之前載入所有符號。在此範例中，假設常數可用。

import { dlopen } from 'node:process';
import { constants } from 'node:os';
import { fileURLToPath } from 'node:url';

const module = { exports: {} };
dlopen(module, fileURLToPath(new URL('local.node', import.meta.url)),
       constants.dlopen.RTLD_NOW);
module.exports.foo();const { dlopen } = require('node:process');
const { constants } = require('node:os');
const { join } = require('node:path');

const module = { exports: {} };
dlopen(module, join(__dirname, 'local.node'), constants.dlopen.RTLD_NOW);
module.exports.foo();copy

process.emitWarning(warning[, options])#

• warning <字串> | <錯誤> 要發出的警告。
• options <物件>
  • type <字串> 當 warning 為 字串 時，type 是用於發出警告的 類型 的名稱。預設： 'Warning'。
  • code <字串> 發出警告實例的唯一識別碼。
  • ctor <函式> 當 warning 為 字串 時，ctor 是用於限制產生的堆疊追蹤的選用函式。預設： process.emitWarning。
  • detail <字串> 要包含在錯誤中的其他文字。

process.emitWarning() 方法可用於發出自訂或應用程式特定的處理程序警告。這些警告可透過將處理常式新增到 'warning' 事件來偵聽。

import { emitWarning } from 'node:process';

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional informationconst { emitWarning } = require('node:process');

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional informationcopy

在此範例中，Error 物件是由 process.emitWarning() 內部產生，並傳遞到 'warning' 處理常式。

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});const process = require('node:process');

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});copy

如果 warning 傳遞為 Error 物件，則會略過 options 參數。

process.emitWarning(warning[, type[, code]][, ctor])#

• warning <字串> | <錯誤> 要發出的警告。
• type <字串> 當 warning 為 字串 時，type 是用於發出警告的 類型 的名稱。預設： 'Warning'。
• code <字串> 發出警告實例的唯一識別碼。
• ctor <函式> 當 warning 為 字串 時，ctor 是用於限制產生的堆疊追蹤的選用函式。預設： process.emitWarning。

process.emitWarning() 方法可用於發出自訂或應用程式特定的處理程序警告。這些警告可透過將處理常式新增到 'warning' 事件來偵聽。

import { emitWarning } from 'node:process';

// Emit a warning using a string.
emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!const { emitWarning } = require('node:process');

// Emit a warning using a string.
emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!copy

import { emitWarning } from 'node:process';

// Emit a warning using a string and a type.
emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!const { emitWarning } = require('node:process');

// Emit a warning using a string and a type.
emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!copy

import { emitWarning } from 'node:process';

emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } = require('node:process');

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!copy

在先前每個範例中，Error 物件是由 process.emitWarning() 內部產生，並傳遞到 'warning' 處理常式。

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});const process = require('node:process');

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});copy

如果 warning 傳遞為 Error 物件，則會將其傳遞到 'warning' 事件處理常式，而不會修改（且會略過選用的 type、code 和 ctor 參數）

import { emitWarning } from 'node:process';

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } = require('node:process');

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!copy

如果 warning 不是字串或 Error 物件，將擲出 TypeError。

雖然處理警告使用 Error 物件，但處理警告機制並非取代一般錯誤處理機制。

如果警告 type 為 'DeprecationWarning'，將實作以下額外處理：

• 如果使用 --throw-deprecation 命令列旗標，將以例外狀況擲出不建議使用警告，而不是以事件發出。
• 如果使用 --no-deprecation 命令列旗標，將抑制不建議使用警告。
• 如果使用 --trace-deprecation 命令列旗標，將把不建議使用警告列印到 stderr，以及完整的堆疊追蹤。

避免重複警告#

最佳實務是每個處理程序只發出一次警告。為此，請將 emitWarning() 放在布林值之後。

import { emitWarning } from 'node:process';

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothingconst { emitWarning } = require('node:process');

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothingcopy

process.env#

• <物件>

process.env 屬性傳回包含使用者環境的物件。請參閱 environ(7)。

這個物件的範例如下所示

{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
} copy

可以修改這個物件，但此類修改不會反映在 Node.js 處理程序外部，或（除非明確要求）其他 Worker 執行緒。換句話說，以下範例無法運作

node -e 'process.env.foo = "bar"' && echo $foo copy

而以下範例可以運作

import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);const { env } = require('node:process');

env.foo = 'bar';
console.log(env.foo);copy

在 process.env 上指定屬性會隱式將值轉換為字串。此行為已棄用。未來版本的 Node.js 可能在值不是字串、數字或布林值時擲出錯誤。

import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'const { env } = require('node:process');

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'copy

使用 delete 刪除 process.env 中的屬性。

import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefinedconst { env } = require('node:process');

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefinedcopy

在 Windows 作業系統中，環境變數不區分大小寫。

import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1const { env } = require('node:process');

env.TEST = 1;
console.log(env.test);
// => 1copy

除非在建立 Worker 執行個體時明確指定，每個 Worker 執行緒都有其自己的 process.env 副本，根據其父執行緒的 process.env，或指定為 Worker 建構函式的 env 選項。對 process.env 的變更不會在 Worker 執行緒中可見，而且只有主執行緒可以進行作業系統或原生外掛程式可見的變更。在 Windows 上，Worker 執行個體上的 process.env 副本以與主執行緒不同的區分大小寫方式運作。

process.execArgv#

• <字串陣列>

process.execArgv 屬性傳回在啟動 Node.js 程序時傳遞的 Node.js 特定命令列選項組。這些選項不會出現在 process.argv 屬性傳回的陣列中，也不包含 Node.js 可執行檔、指令碼名稱或指令碼名稱之後的任何選項。這些選項有助於以與父執行緒相同的執行環境產生子程序。

node --harmony script.js --version copy

結果在 process.execArgv

['--harmony'] copy

和 process.argv

['/usr/local/bin/node', 'script.js', '--version'] copy

參閱 Worker 建構函式，以了解此屬性在工作執行緒中的詳細行為。

process.execPath#

• <字串>

process.execPath 屬性傳回啟動 Node.js 程序的可執行檔的絕對路徑名稱。如果有的話，會解析符號連結。

'/usr/local/bin/node' copy

process.exit([code])#

• code <整數> | <字串> | <null> | <undefined> 退出碼。對於字串類型，僅允許整數字串（例如「1」）。預設：0。

process.exit() 方法指示 Node.js 同步終止程序，退出狀態為 code。如果省略 code，則 exit 會使用「成功」碼 0 或 process.exitCode 的值（如果已設定）。在呼叫所有 'exit' 事件監聽器之前，Node.js 都不會終止。

使用「失敗」碼退出

import { exit } from 'node:process';

exit(1);const { exit } = require('node:process');

exit(1);copy

執行 Node.js 的 shell 應將退出碼視為 1。

呼叫 process.exit() 會強制程序儘快退出，即使仍有未完全完成的非同步作業待處理，包括對 process.stdout 和 process.stderr 的 I/O 作業。

在多數情況下，實際上不需要明確呼叫 process.exit()。如果事件迴圈中沒有其他待處理工作，Node.js 程序會自行退出。可以設定 process.exitCode 屬性，以指示程序在正常退出時應使用的退出碼。

例如，以下範例說明 process.exit() 方法的誤用，可能會導致列印到 stdout 的資料被截斷並遺失

import { exit } from 'node:process';

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}const { exit } = require('node:process');

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}copy

之所以會有這個問題，是因為在 Node.js 中寫入 process.stdout 有時是非同步的，而且可能會在 Node.js 事件迴圈的多次滴答中發生。然而，呼叫 process.exit() 會強制程序在對 stdout 執行這些額外寫入之前退出。

不要直接呼叫 process.exit()，程式碼應設定 process.exitCode，並透過避免為事件迴圈排程任何額外工作，讓程序自然退出

import process from 'node:process';

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}const process = require('node:process');

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}copy

如果由於錯誤狀況而需要終止 Node.js 程序，擲出未捕捉的錯誤並允許程序相應地終止，這比呼叫 process.exit() 更安全。

在 Worker 執行緒中，此函式會停止目前的執行緒，而不是目前的程序。

process.exitCode#

• <integer> | <string> | <null> | <undefined> 退出代碼。對於字串類型，僅允許整數字串（例如「1」）。預設值：undefined。

一個數字，當程序正常退出或透過 process.exit() 退出且未指定代碼時，將會是程序退出代碼。

對 process.exit(code) 指定代碼會覆寫 process.exitCode 的任何先前設定。

process.getActiveResourcesInfo()#

• 傳回：<string[]>

process.getActiveResourcesInfo() 方法傳回一個字串陣列，其中包含目前讓事件迴圈保持運作的資源類型。

import { getActiveResourcesInfo } from 'node:process';
import { setTimeout } from 'node:timers';

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]const { getActiveResourcesInfo } = require('node:process');
const { setTimeout } = require('node:timers');

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]copy

process.getegid()#

process.getegid() 方法傳回 Node.js 程序的數值有效群組識別碼。（請參閱 getegid(2)。）

import process from 'node:process';

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}const process = require('node:process');

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}copy

此函式僅在 POSIX 平台上可用（即不是 Windows 或 Android）。

process.geteuid()#

• 傳回：<Object>

process.geteuid() 方法傳回程序的有效使用者身分識別碼。（請參閱 geteuid(2)。）

import process from 'node:process';

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}const process = require('node:process');

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}copy

此函式僅在 POSIX 平台上可用（即不是 Windows 或 Android）。

process.getgid()#

• 傳回：<Object>

process.getgid() 方法傳回程序的群組身分識別碼。（請參閱 getgid(2)。）

import process from 'node:process';

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}const process = require('node:process');

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}copy

此函式僅在 POSIX 平台上可用（即不是 Windows 或 Android）。

process.getgroups()#

• 傳回：<integer[]>

process.getgroups() 方法傳回一個包含補充群組 ID 的陣列。POSIX 未指定是否包含有效群組 ID，但 Node.js 確保始終包含。

import process from 'node:process';

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}const process = require('node:process');

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}copy

此函式僅在 POSIX 平台上可用（即不是 Windows 或 Android）。

process.getuid()#

• 傳回：<integer>

process.getuid() 方法傳回程序的數字使用者身分識別碼。（請參閱 getuid(2)。）

import process from 'node:process';

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}const process = require('node:process');

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}copy

此函式僅在 POSIX 平台上可用（即不是 Windows 或 Android）。

process.hasUncaughtExceptionCaptureCallback()#

• 傳回：<boolean>

指出是否已使用 process.setUncaughtExceptionCaptureCallback() 設定回呼函式。

process.hrtime([time])#

• time <整數陣列> 之前呼叫 process.hrtime() 的結果
• 傳回：<integer[]>

這是 process.hrtime.bigint() 在 JavaScript 中引入 bigint 之前的舊版。

process.hrtime() 方法會傳回目前的高解析度真實時間，以 [秒數、奈秒數] 元組 陣列 表示，其中 奈秒數 是無法以秒為單位表示的真實時間剩餘部分。

time 是選用參數，必須是之前 process.hrtime() 呼叫的結果，才能與目前時間相減。如果傳入的參數不是元組 陣列，會擲回 TypeError。傳入使用者定義的陣列，而不是之前 process.hrtime() 呼叫的結果，會導致未定義的行為。

這些時間相對於過去的任意時間，與一天中的時間無關，因此不受時鐘漂移影響。主要用途是測量區間之間的效能

import { hrtime } from 'node:process';

const NS_PER_SEC = 1e9;
const time = hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);const { hrtime } = require('node:process');

const NS_PER_SEC = 1e9;
const time = hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);copy

process.hrtime.bigint()#

• 傳回：<bigint>

process.hrtime() 方法的 bigint 版本，傳回目前高解析度真實時間，以 bigint 表示，單位為奈秒。

與 process.hrtime() 不同，它不支援額外的 time 參數，因為差異可以直接透過兩個 bigint 的減法計算。

import { hrtime } from 'node:process';

const start = hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);const { hrtime } = require('node:process');

const start = hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);copy

process.initgroups(user, extraGroup)#

• user <字串> | <數字> 使用者名稱或數字識別碼。
• extraGroup <字串> | <數字> 群組名稱或數字識別碼。

process.initgroups() 方法會讀取 /etc/group 檔案，並使用使用者為其成員的所有群組來初始化群組存取清單。這項特權操作需要 Node.js 程序具有 root 存取權或 CAP_SETGID 功能。

放棄特權時請小心

import { getgroups, initgroups, setgid } from 'node:process';

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(getgroups());         // [ 27, 30, 46, 1000 ]const { getgroups, initgroups, setgid } = require('node:process');

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(getgroups());         // [ 27, 30, 46, 1000 ]copy

此函式僅在 POSIX 平台上可用（即非 Windows 或 Android）。此功能在 Worker 執行緒中不可用。

process.kill(pid[, signal])#

• pid <數字> 程序 ID
• signal <字串> | <數字> 要傳送的訊號，可以是字串或數字。預設：'SIGTERM'。

process.kill() 方法會將 signal 傳送給由 pid 識別的程序。

訊號名稱是字串，例如 'SIGINT' 或 'SIGHUP'。請參閱 訊號事件 和 kill(2) 以取得更多資訊。

如果目標 pid 不存在，此方法會擲回錯誤。特殊情況下，可以使用 0 訊號來測試程序是否存在。如果 pid 用於終止程序群組，Windows 平台會擲回錯誤。

儘管此函數的名稱是 process.kill()，但它實際上只是一個訊號傳送器，類似於 kill 系統呼叫。傳送的訊號可能會執行終止目標程序以外的動作。

import process, { kill } from 'node:process';

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

kill(process.pid, 'SIGHUP');const process = require('node:process');

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

process.kill(process.pid, 'SIGHUP');copy

當 Node.js 程序收到 SIGUSR1 時，Node.js 會啟動偵錯器。請參閱 訊號事件。

process.loadEnvFile(path)#

• path <字串> | <URL> | <Buffer> | <未定義>。預設值： './.env'

將 .env 檔案載入 process.env。.env 檔案中的 NODE_OPTIONS 用法不會對 Node.js 產生任何影響。

const { loadEnvFile } = require('node:process');
loadEnvFile();import { loadEnvFile } from 'node:process';
loadEnvFile();copy

process.mainModule#

• <物件>

process.mainModule 屬性提供取得 require.main 的另一種方式。不同之處在於，如果主模組在執行期間變更，require.main 仍可能參考在變更發生前已載入模組中的原始主模組。一般來說，可以安全地假設這兩個參考相同的模組。

與 require.main 相同，如果沒有進入指令碼，process.mainModule 將會是 undefined。

process.memoryUsage()#

• 傳回：<Object>
  • rss <整數>
  • heapTotal <整數>
  • heapUsed <整數>
  • external <整數>
  • arrayBuffers <整數>

傳回一個物件，用於描述以位元組為單位的 Node.js 程序記憶體使用情況。

import { memoryUsage } from 'node:process';

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }const { memoryUsage } = require('node:process');

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }copy

• heapTotal 和 heapUsed 參考 V8 的記憶體使用情況。
• external 參考繫結到由 V8 管理的 JavaScript 物件的 C++ 物件的記憶體使用情況。
• rss，常駐集大小，是程序在主記憶體裝置中佔用的空間量（這是總配置記憶體的子集），包括所有 C++ 和 JavaScript 物件及程式碼。
• arrayBuffers 參考配置給 ArrayBuffer 和 SharedArrayBuffer 的記憶體，包括所有 Node.js Buffer。這也包含在 external 值中。當 Node.js 用作嵌入式函式庫時，此值可能是 0，因為在這種情況下可能不會追蹤 ArrayBuffer 的配置。

使用 Worker 執行緒時，rss 將會是整個程序的有效值，而其他欄位只會參考目前的執行緒。

process.memoryUsage() 方法會遍歷每個頁面以收集有關記憶體使用情況的資訊，這可能會很慢，具體取決於程式記憶體配置。

process.memoryUsage.rss()#

• 傳回：<integer>

process.memoryUsage.rss() 方法傳回一個整數，表示以位元組為單位的常駐集大小 (RSS)。

常駐集大小是程式在主記憶體裝置中所佔用的空間量（這是總配置記憶體的一部分），包括所有 C++ 和 JavaScript 物件和程式碼。

這與 process.memoryUsage() 提供的 rss 屬性相同，但 process.memoryUsage.rss() 較快。

import { memoryUsage } from 'node:process';

console.log(memoryUsage.rss());
// 35655680const { memoryUsage } = require('node:process');

console.log(memoryUsage.rss());
// 35655680copy

process.nextTick(callback[, ...args])#

• callback <Function>
• ...args <any> 呼叫 callback 時要傳遞的其他參數

process.nextTick() 會將 callback 加入「下一個勾選佇列」。在 JavaScript 堆疊上的目前作業執行完畢，且事件迴圈獲准繼續執行之前，此佇列會完全清空。如果遞迴呼叫 process.nextTick()，可能會產生無限迴圈。請參閱 Event Loop 指南以取得更多背景資訊。

import { nextTick } from 'node:process';

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callbackconst { nextTick } = require('node:process');

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callbackcopy

在開發 API 時，這一點很重要，因為它能讓使用者在物件建構之後，但在任何 I/O 發生之前，指派事件處理常式。

import { nextTick } from 'node:process';

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.const { nextTick } = require('node:process');

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.copy

對於 API 而言，保持 100% 同步或 100% 非同步非常重要。請考慮這個範例

// WARNING!  DO NOT USE!  BAD UNSAFE HAZARD!
function maybeSync(arg, cb) {
  if (arg) {
    cb();
    return;
  }

  fs.stat('file', cb);
} copy

這個 API 很危險，因為在下列情況下

const maybeTrue = Math.random() > 0.5;

maybeSync(maybeTrue, () => {
  foo();
});

bar(); copy

無法明確得知 foo() 或 bar() 會先被呼叫。

以下方法較佳

import { nextTick } from 'node:process';

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}const { nextTick } = require('node:process');

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}copy

何時使用 queueMicrotask() 而非 process.nextTick()#

queueMicrotask() API 是 process.nextTick() 的替代方案，它也會使用與執行已解決承諾的 then、catch 和 finally 處理常式相同的微任務佇列來延遲執行函式。在 Node.js 中，每次「下一個勾選佇列」被清空時，微任務佇列會在緊接著清空。

import { nextTick } from 'node:process';

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
nextTick(() => console.log(1));
// Output:
// 1
// 2
// 3const { nextTick } = require('node:process');

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
nextTick(() => console.log(1));
// Output:
// 1
// 2
// 3copy

對於大多數使用者空間使用案例，queueMicrotask() API 提供了一種可攜式且可靠的延遲執行機制，可在多個 JavaScript 平台環境中運作，應優先於 process.nextTick() 使用。在簡單的場景中，queueMicrotask() 可以直接替換 process.nextTick()。

console.log('start');
queueMicrotask(() => {
  console.log('microtask callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// microtask callback copy

這兩個 API 之間一個值得注意的差異是，process.nextTick() 允許指定額外的值，這些值在呼叫延遲函式時將作為引數傳遞。使用 queueMicrotask() 達到相同結果需要使用封閉或繫結函式

function deferred(a, b) {
  console.log('microtask', a + b);
}

console.log('start');
queueMicrotask(deferred.bind(undefined, 1, 2));
console.log('scheduled');
// Output:
// start
// scheduled
// microtask 3 copy

在處理下一個勾選佇列和微任務佇列中引發的錯誤的方式上有一些細微的差異。如果可能，應在佇列微任務回呼中處理佇列微任務回呼中引發的錯誤。如果沒有處理，可以使用 process.on('uncaughtException') 事件處理常式來擷取和處理錯誤。

若有疑問，除非需要 process.nextTick() 的特定功能，否則請使用 queueMicrotask()。

process.noDeprecation#

• <boolean>

process.noDeprecation 屬性表示是否在目前的 Node.js 程序中設定 --no-deprecation 旗標。請參閱 'warning' 事件 和 emitWarning() 方法 的文件，以取得關於此旗標行為的更多資訊。

process.permission#

• <物件>

此 API 可透過 --experimental-permission 旗標取得。

process.permission 是物件，其方法用於管理目前程序的權限。其他文件可於 權限模型 中取得。

process.permission.has(scope[, reference])#

• scope <string>
• reference <string>
• 傳回：<boolean>

驗證程序是否能夠存取給定的範圍和參考。如果未提供參考，則假設為全域範圍，例如，process.permission.has('fs.read') 會檢查程序是否具有所有檔案系統讀取權限。

參考具有基於所提供範圍的意義。例如，當範圍為檔案系統時，參考表示檔案和資料夾。

可用範圍為

• fs - 所有檔案系統
• fs.read - 檔案系統讀取操作
• fs.write - 檔案系統寫入操作
• child - 子處理序產生操作
• worker - 工作執行緒產生操作

// Check if the process has permission to read the README file
process.permission.has('fs.read', './README.md');
// Check if the process has read permission operations
process.permission.has('fs.read'); copy

process.pid#

• <整數>

process.pid 屬性傳回處理序的 PID。

import { pid } from 'node:process';

console.log(`This process is pid ${pid}`);const { pid } = require('node:process');

console.log(`This process is pid ${pid}`);copy

process.platform#

• <字串>

process.platform 屬性傳回識別 Node.js 二進位檔編譯作業系統平台的字串。

目前可能的值為

• 'aix'
• 'darwin'
• 'freebsd'
• 'linux'
• 'openbsd'
• 'sunos'
• 'win32'

import { platform } from 'node:process';

console.log(`This platform is ${platform}`);const { platform } = require('node:process');

console.log(`This platform is ${platform}`);copy

如果 Node.js 建置在 Android 作業系統上，也可能會傳回值 'android'。不過，Node.js 中的 Android 支援 為實驗性質。

process.ppid#

• <整數>

process.ppid 屬性傳回目前處理序父處理序的 PID。

import { ppid } from 'node:process';

console.log(`The parent process is pid ${ppid}`);const { ppid } = require('node:process');

console.log(`The parent process is pid ${ppid}`);copy

process.release#

• <物件>

process.release 屬性傳回包含與目前版本相關的元資料的 Object，包括原始碼 tarball 和僅標頭的 tarball 的 URL。

process.release 包含下列屬性

• name <字串> 一個值，永遠會是 'node'。
• sourceUrl <字串> 指向包含目前版本原始程式碼的 .tar.gz 檔案的絕對 URL。
• headersUrl<字串> 指向僅包含目前版本原始程式碼標頭檔的 .tar.gz 檔案的絕對 URL。此檔案比完整的原始程式碼檔案小很多，可用於編譯 Node.js 原生外掛程式。
• libUrl <字串> | <未定義> 指向與目前版本架構和版本相符的 node.lib 檔案的絕對 URL。此檔案用於編譯 Node.js 原生外掛程式。此屬性僅存在於 Node.js 的 Windows 組建中，其他所有平台都不會有。
• lts <字串> | <未定義> 識別此版本的 LTS 標籤的字串標籤。此屬性僅存在於 LTS 版本，對於所有其他版本類型（包括目前版本）都是 undefined。有效值包括 LTS 版本代號（包括不再支援的代號）。
  • 'Fermium' 適用於從 14.15.0 開始的 14.x LTS 系列。
  • 'Gallium' 適用於從 16.13.0 開始的 16.x LTS 系列。
  • 'Hydrogen' 適用於從 18.12.0 開始的 18.x LTS 系列。其他 LTS 版本代號，請參閱 Node.js 變更日誌檔案

{
  name: 'node',
  lts: 'Hydrogen',
  sourceUrl: 'https://node.dev.org.tw/download/release/v18.12.0/node-v18.12.0.tar.gz',
  headersUrl: 'https://node.dev.org.tw/download/release/v18.12.0/node-v18.12.0-headers.tar.gz',
  libUrl: 'https://node.dev.org.tw/download/release/v18.12.0/win-x64/node.lib'
} copy

在非原始程式碼樹版本的自訂組建中，可能只會出現 name 屬性。不應依賴其他屬性存在。

process.report#

• <物件>

process.report 是用來為目前程序產生診斷報告的方法物件。其他文件可以在 報告文件 中取得。

process.report.compact#

• <boolean>

以精簡格式撰寫報告，單行 JSON，比為人類閱讀而設計的多行預設格式更容易讓記錄處理系統使用。

import { report } from 'node:process';

console.log(`Reports are compact? ${report.compact}`);const { report } = require('node:process');

console.log(`Reports are compact? ${report.compact}`);copy

process.report.directory#

• <字串>

撰寫報告的目錄。預設值是空字串，表示報告會寫入 Node.js 程序的目前工作目錄。

import { report } from 'node:process';

console.log(`Report directory is ${report.directory}`);const { report } = require('node:process');

console.log(`Report directory is ${report.directory}`);copy

process.report.filename#

• <字串>

撰寫報告的檔案名稱。如果設為空字串，輸出檔名將包含時間戳記、PID 和順序號碼。預設值是空字串。

如果 process.report.filename 的值設為 'stdout' 或 'stderr'，報告將分別寫入程序的 stdout 或 stderr。

import { report } from 'node:process';

console.log(`Report filename is ${report.filename}`);const { report } = require('node:process');

console.log(`Report filename is ${report.filename}`);copy

process.report.getReport([err])#

• err <Error> 用於報告 JavaScript 堆疊的客製化錯誤。
• 傳回：<Object>

傳回目前程序的診斷報告的 JavaScript 物件表示。報告的 JavaScript 堆疊追蹤會從 err 取得（如果存在）。

import { report } from 'node:process';
import util from 'node:util';

const data = report.getReport();
console.log(data.header.nodejsVersion);

// Similar to process.report.writeReport()
import fs from 'node:fs';
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8');const { report } = require('node:process');
const util = require('node:util');

const data = report.getReport();
console.log(data.header.nodejsVersion);

// Similar to process.report.writeReport()
const fs = require('node:fs');
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8');copy

其他文件可於 報告文件 中取得。

process.report.reportOnFatalError#

• <boolean>

如果為 true，將會在發生嚴重錯誤時產生診斷報告，例如記憶體不足錯誤或 C++ 斷言失敗。

import { report } from 'node:process';

console.log(`Report on fatal error: ${report.reportOnFatalError}`);const { report } = require('node:process');

console.log(`Report on fatal error: ${report.reportOnFatalError}`);copy

process.report.reportOnSignal#

• <boolean>

如果為 true，將會在處理程序收到 process.report.signal 指定的訊號時產生診斷報告。

import { report } from 'node:process';

console.log(`Report on signal: ${report.reportOnSignal}`);const { report } = require('node:process');

console.log(`Report on signal: ${report.reportOnSignal}`);copy

process.report.reportOnUncaughtException#

• <boolean>

如果為 true，將會在發生未捕捉的例外狀況時產生診斷報告。

import { report } from 'node:process';

console.log(`Report on exception: ${report.reportOnUncaughtException}`);const { report } = require('node:process');

console.log(`Report on exception: ${report.reportOnUncaughtException}`);copy

process.report.signal#

• <字串>

用於觸發診斷報告建立的訊號。預設為 'SIGUSR2'。

import { report } from 'node:process';

console.log(`Report signal: ${report.signal}`);const { report } = require('node:process');

console.log(`Report signal: ${report.signal}`);copy

process.report.writeReport([filename][, err])#

• filename <string> 撰寫報告之檔案名稱。這應為相對路徑，將附加到 process.report.directory 中指定的目錄，或 Node.js 處理程序的目前工作目錄（如果未指定）。

• err <Error> 用於報告 JavaScript 堆疊的客製化錯誤。

• 傳回：<string> 傳回已產生報告的檔案名稱。

將診斷報告寫入檔案。如果未提供filename，預設檔名會包含日期、時間、PID 和序列號。如果存在，報告的 JavaScript 堆疊追蹤會從 err 取得。

如果 filename 的值設為 'stdout' 或 'stderr'，報告會分別寫入處理程序的 stdout 或 stderr。

import { report } from 'node:process';

report.writeReport();const { report } = require('node:process');

report.writeReport();copy

其他文件可於 報告文件 中取得。

process.resourceUsage()#

• 傳回：<Object> 目前處理程序的資源使用量。所有這些值都來自 uv_getrusage 呼叫，它會傳回 uv_rusage_t 結構。
  • userCPUTime <integer> 對應到以微秒為單位的 ru_utime。它與 process.cpuUsage().user 的值相同。
  • systemCPUTime <integer> 對應到以微秒為單位的 ru_stime。它與 process.cpuUsage().system 的值相同。
  • maxRSS <integer> 對應到 ru_maxrss，單位為 KB 的最大常駐集大小。
  • sharedMemorySize <integer> 對應到 ru_ixrss，但沒有任何平台支援。
  • unsharedDataSize <integer> 對應到 ru_idrss，但沒有任何平台支援。
  • unsharedStackSize <integer> 對應到 ru_isrss，但沒有任何平台支援。
  • minorPageFault <integer> 對應到 ru_minflt，這是處理程序的次要分頁錯誤數目，詳情請參閱 這篇文章。
  • majorPageFault <integer> 對應到 ru_majflt，這是處理程序的主要分頁錯誤數目，詳情請參閱 這篇文章。此欄位不支援 Windows。
  • swappedOut <integer> 對應到 ru_nswap，但沒有任何平台支援。
  • fsRead <integer> 對應到 ru_inblock，這是檔案系統必須執行輸入的次數。
  • fsWrite <integer> 對應到 ru_oublock，這是檔案系統必須執行輸出的次數。
  • ipcSent <integer> 對應到 ru_msgsnd，但沒有任何平台支援。
  • ipcReceived <integer> 對應到 ru_msgrcv，但沒有任何平台支援。
  • signalsCount <integer> 對應到 ru_nsignals，但沒有任何平台支援。
  • voluntaryContextSwitches <整數> 對應至 ru_nvcsw，表示 CPU 脈絡切換的次數，原因是處理程序在時段結束前自願放棄處理器（通常是等待資源可用）。Windows 不支援此欄位。
  • involuntaryContextSwitches <整數> 對應至 ru_nivcsw，表示 CPU 脈絡切換的次數，原因是優先權較高的處理程序可執行，或因為目前的處理程序超過其時段。Windows 不支援此欄位。

import { resourceUsage } from 'node:process';

console.log(resourceUsage());
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/const { resourceUsage } = require('node:process');

console.log(resourceUsage());
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/copy

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

• message <物件>
• sendHandle <net.Server> | <net.Socket>
• options <物件> 用於參數化傳送特定類型的控制代碼。options 支援下列屬性
  • keepOpen <布林值> 傳遞 net.Socket 執行個體時可使用的值。當 true 時，控制代碼會在傳送處理程序中保持開啟。預設值： false。
• callback <Function>
• 傳回：<boolean>

如果 Node.js 是使用 IPC 通道衍生的，則 process.send() 方法可傳送訊息至父處理程序。訊息會在父處理程序的 ChildProcess 物件上以 'message' 事件接收。

如果 Node.js 不是使用 IPC 通道衍生的，則 process.send 會是 undefined。

訊息會經過序列化和剖析。產生的訊息可能與最初傳送的訊息不同。

process.setegid(id)#

• id <字串> | <數字> 群組名稱或 ID

process.setegid() 方法設定處理程序的有效群組身分識別（請參閱 setegid(2)）。id 可傳遞為數字 ID 或群組名稱字串。如果指定群組名稱，此方法會在解析關聯的數字 ID 時封鎖。

import process from 'node:process';

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`);
  try {
    process.setegid(501);
    console.log(`New gid: ${process.getegid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}const process = require('node:process');

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`);
  try {
    process.setegid(501);
    console.log(`New gid: ${process.getegid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}copy

此函式僅在 POSIX 平台上可用（即非 Windows 或 Android）。此功能在 Worker 執行緒中不可用。

process.seteuid(id)#

• id <字串> | <數字> 使用者名稱或 ID

process.seteuid() 方法設定程序的有效使用者身分識別。（請參閱 seteuid(2)。）id 可以傳遞為數字 ID 或使用者名稱字串。如果指定使用者名稱，方法會在解析關聯的數字 ID 時封鎖。

import process from 'node:process';

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
  try {
    process.seteuid(501);
    console.log(`New uid: ${process.geteuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}const process = require('node:process');

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
  try {
    process.seteuid(501);
    console.log(`New uid: ${process.geteuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}copy

此函式僅在 POSIX 平台上可用（即非 Windows 或 Android）。此功能在 Worker 執行緒中不可用。

process.setgid(id)#

• id <字串> | <數字> 群組名稱或 ID

process.setgid() 方法設定程序的群組身分識別。（請參閱 setgid(2)。）id 可以傳遞為數字 ID 或群組名稱字串。如果指定群組名稱，此方法會在解析關聯的數字 ID 時封鎖。

import process from 'node:process';

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`);
  try {
    process.setgid(501);
    console.log(`New gid: ${process.getgid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}const process = require('node:process');

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`);
  try {
    process.setgid(501);
    console.log(`New gid: ${process.getgid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}copy

此函式僅在 POSIX 平台上可用（即非 Windows 或 Android）。此功能在 Worker 執行緒中不可用。

process.setgroups(groups)#

• groups <整數陣列>

process.setgroups() 方法設定 Node.js 程序的補充群組 ID。這是一個特權操作，需要 Node.js 程序具有 root 或 CAP_SETGID 功能。

groups 陣列可以包含數字群組 ID、群組名稱或兩者。

import process from 'node:process';

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501]);
    console.log(process.getgroups()); // new groups
  } catch (err) {
    console.error(`Failed to set groups: ${err}`);
  }
}const process = require('node:process');

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501]);
    console.log(process.getgroups()); // new groups
  } catch (err) {
    console.error(`Failed to set groups: ${err}`);
  }
}copy

此函式僅在 POSIX 平台上可用（即非 Windows 或 Android）。此功能在 Worker 執行緒中不可用。

process.setuid(id)#

• id <整數> | <字串>

process.setuid(id) 方法設定程序的使用者身分。(請參閱 setuid(2)。)id 可以傳遞為數字 ID 或使用者名稱字串。如果指定使用者名稱，該方法會在解析相關數字 ID 時封鎖。

import process from 'node:process';

if (process.getuid && process.setuid) {
  console.log(`Current uid: ${process.getuid()}`);
  try {
    process.setuid(501);
    console.log(`New uid: ${process.getuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}const process = require('node:process');

if (process.getuid && process.setuid) {
  console.log(`Current uid: ${process.getuid()}`);
  try {
    process.setuid(501);
    console.log(`New uid: ${process.getuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}copy

此函式僅在 POSIX 平台上可用（即非 Windows 或 Android）。此功能在 Worker 執行緒中不可用。

process.setSourceMapsEnabled(val)#

• val <布林值>

此函式啟用或停用堆疊追蹤的 Source Map v3 支援。

它提供與使用命令列選項 --enable-source-maps 啟動 Node.js 程序相同的功能。

只有在啟用 Source Map 之後載入的 JavaScript 檔案中的 Source Map 會被解析和載入。

process.setUncaughtExceptionCaptureCallback(fn)#

• fn <函式> | <null>

process.setUncaughtExceptionCaptureCallback() 函式設定一個在發生未捕捉的例外狀況時會被呼叫的函式，該函式會將例外狀況值本身作為第一個引數接收。

如果設定了此類函式，則不會發出 'uncaughtException' 事件。如果從命令列傳遞了 --abort-on-uncaught-exception 或透過 v8.setFlagsFromString() 設定，程序不會中止。針對例外狀況設定的動作，例如產生報告，也會受到影響。

若要取消設定 capture 函式，可以使用 process.setUncaughtExceptionCaptureCallback(null)。在設定其他 capture 函式的同時，使用非 null 引數呼叫此方法會擲回錯誤。

使用此函數會與已棄用的內建模組 domain 互斥。

process.sourceMapsEnabled#

• <boolean>

process.sourceMapsEnabled 屬性傳回是否已啟用追蹤堆疊的 Source Map v3 支援。

process.stderr#

• <Stream>

process.stderr 屬性傳回連接到 stderr (fd 2) 的串流。除非 fd 2 參照檔案，否則它會是 net.Socket（也就是 雙工 串流），而後者會是 可寫入 串流。

process.stderr 與其他 Node.js 串流在重要方面有所不同。如需更多資訊，請參閱 process I/O 說明。

process.stderr.fd#

• <數字>

此屬性參照 process.stderr 的底層檔案描述符值。該值固定為 2。在 Worker 執行緒中，此欄位不存在。

process.stdin#

• <Stream>

process.stdin 屬性傳回連接到 stdin (fd 0) 的串流。除非 fd 0 參照檔案，否則它會是 net.Socket（也就是 雙工 串流），而後者會是 可讀取 串流。

如需如何從 stdin 讀取的詳細資料，請參閱 readable.read()。

作為 雙工 串流，process.stdin 也可以用於與 v0.10 以前的 Node.js 腳本相容的「舊」模式。如需更多資訊，請參閱 串流相容性。

在「舊」串流模式中，stdin 串流預設為暫停，因此必須呼叫 process.stdin.resume() 才能從中讀取。另請注意，呼叫 process.stdin.resume() 本身會將串流切換為「舊」模式。

process.stdin.fd#

• <數字>

此屬性是指 process.stdin 的底層檔案描述符的值。該值固定為 0。在 Worker 執行緒中，此欄位不存在。

process.stdout#

• <Stream>

process.stdout 屬性傳回連接到 stdout（檔案描述符 1）的串流。它是一個 net.Socket（它是一個 雙工 串流），除非檔案描述符 1 指向檔案，否則它是一個 可寫入 串流。

例如，要將 process.stdin 複製到 process.stdout

import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);const { stdin, stdout } = require('node:process');

stdin.pipe(stdout);copy

process.stdout 與其他 Node.js 串流在重要的方面有所不同。有關更多資訊，請參閱 關於處理程序 I/O 的注意事項。

process.stdout.fd#

• <數字>

此屬性是指 process.stdout 的底層檔案描述符的值。該值固定為 1。在 Worker 執行緒中，此欄位不存在。

關於處理程序 I/O 的注意事項#

process.stdout 和 process.stderr 與其他 Node.js 串流在重要的方面有所不同

1. 它們分別由 console.log() 和 console.error() 在內部使用。
2. 寫入可能是同步的，具體取決於串流連接到什麼以及系統是 Windows 還是 POSIX
   • 檔案：Windows 和 POSIX 上的 同步
   • TTY（終端機）：Windows 上的 非同步，POSIX 上的 同步
   • 管道（和 socket）：Windows 上的 同步，POSIX 上的 非同步

這些行為部分是出於歷史原因，因為變更它們會造成向後不相容，但有些使用者也預期會這樣。

同步寫入可避免問題，例如使用 console.log() 或 console.error() 寫入的輸出意外交錯，或是在非同步寫入完成前呼叫 process.exit() 時完全沒有寫入。請參閱 process.exit() 以取得更多資訊。

警告：同步寫入會在寫入完成前封鎖事件迴圈。在輸出到檔案的情況下，這可能會近乎立即發生，但在系統負載過高、接收端未讀取的管道，或終端機或檔案系統速度過慢時，事件迴圈可能會經常且長時間地被封鎖，造成嚴重的負面效能影響。當寫入互動式終端機工作階段時，這可能不是問題，但執行生產記錄到程序輸出串流時，請特別小心考慮這一點。

若要檢查串流是否已連線到 TTY 環境，請檢查 isTTY 屬性。

例如

$ node -p "Boolean(process.stdin.isTTY)"
true
$ echo "foo" | node -p "Boolean(process.stdin.isTTY)"
false
$ node -p "Boolean(process.stdout.isTTY)"
true
$ node -p "Boolean(process.stdout.isTTY)" | cat
false copy

請參閱 TTY 文件以取得更多資訊。

process.throwDeprecation#

• <boolean>

process.throwDeprecation 的初始值表示是否在目前的 Node.js 程序上設定 --throw-deprecation 旗標。process.throwDeprecation 是可變的，因此不論不贊成使用的警告是否導致錯誤，都可以在執行時期變更。請參閱 'warning' 事件 和 emitWarning() 方法 的文件以取得更多資訊。

$ node --throw-deprecation -p "process.throwDeprecation"
true
$ node -p "process.throwDeprecation"
undefined
$ node
> process.emitWarning('test', 'DeprecationWarning');
undefined
> (node:26598) DeprecationWarning: test
> process.throwDeprecation = true;
true
> process.emitWarning('test', 'DeprecationWarning');
Thrown:
[DeprecationWarning: test] { name: 'DeprecationWarning' } copy

process.title#

• <字串>

process.title 屬性傳回目前的處理程序標題（即傳回 ps 的目前值）。將新值指定給 process.title 會修改 ps 的目前值。

指定新值時，不同的平台會對標題強制實施不同的最大長度限制。通常此類限制相當有限。例如，在 Linux 和 macOS 上，process.title 限制為二進位檔名稱加上命令列引數的長度，因為設定 process.title 會覆寫處理程序的 argv 記憶體。Node.js v0.8 允許更長的處理程序標題字串，方法是也覆寫 environ 記憶體，但在某些（相當模糊）情況下，這可能會不安全且令人困惑。

將值指定給 process.title 可能不會在處理程序應用程式（例如 macOS 活動監視器或 Windows 服務管理員）中產生準確的標籤。

process.traceDeprecation#

• <boolean>

process.traceDeprecation 屬性指出是否在目前的 Node.js 處理程序上設定 --trace-deprecation 旗標。請參閱 'warning' 事件 和 emitWarning() 方法 的文件，以取得有關此旗標行為的更多資訊。

process.umask()#

process.umask() 傳回 Node.js 程序的檔案模式建立遮罩。子程序會繼承父程序的遮罩。

process.umask(mask)#

• mask <string> | <integer>

process.umask(mask) 設定 Node.js 程序的檔案模式建立遮罩。子程序會繼承父程序的遮罩。傳回先前的遮罩。

import { umask } from 'node:process';

const newmask = 0o022;
const oldmask = umask(newmask);
console.log(
  `Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`,
);const { umask } = require('node:process');

const newmask = 0o022;
const oldmask = umask(newmask);
console.log(
  `Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`,
);copy

在 Worker 執行緒中，process.umask(mask) 會擲回例外。

process.uptime()#

• 傳回值：<number>

process.uptime() 方法傳回目前 Node.js 程序執行秒數。

傳回值包含小數秒。使用 Math.floor() 取得整秒。

process.version#

• <字串>

process.version 屬性包含 Node.js 版本字串。

import { version } from 'node:process';

console.log(`Version: ${version}`);
// Version: v14.8.0const { version } = require('node:process');

console.log(`Version: ${version}`);
// Version: v14.8.0copy

若要取得不帶有前置 v 的版本字串，請使用 process.versions.node。

process.versions#

• <物件>

process.versions 屬性傳回一個列出 Node.js 及其相依項版本字串的物件。process.versions.modules 指出目前的 ABI 版本，每當 C++ API 變更時，就會增加此版本。Node.js 會拒絕載入與不同模組 ABI 版本編譯的模組。

import { versions } from 'node:process';

console.log(versions);const { versions } = require('node:process');

console.log(versions);copy

會產生類似於

{ node: '20.2.0',
  acorn: '8.8.2',
  ada: '2.4.0',
  ares: '1.19.0',
  base64: '0.5.0',
  brotli: '1.0.9',
  cjs_module_lexer: '1.2.2',
  cldr: '43.0',
  icu: '73.1',
  llhttp: '8.1.0',
  modules: '115',
  napi: '8',
  nghttp2: '1.52.0',
  nghttp3: '0.7.0',
  ngtcp2: '0.8.1',
  openssl: '3.0.8+quic',
  simdutf: '3.2.9',
  tz: '2023c',
  undici: '5.22.0',
  unicode: '15.0',
  uv: '1.44.2',
  uvwasi: '0.0.16',
  v8: '11.3.244.8-node.9',
  zlib: '1.2.13' } copy

結束程式碼#

當沒有更多非同步作業待處理時，Node.js 通常會以 0 狀態碼結束。在其他情況下，會使用下列狀態碼

• 1 未捕捉的致命例外：發生未捕捉的例外，且未由網域或 'uncaughtException' 事件處理常式處理。
• 2：未使用（由 Bash 保留，供內建錯誤使用）
• 3 內部 JavaScript 分析錯誤：Node.js 引導程序中的內部 JavaScript 原始碼導致分析錯誤。這極為罕見，而且通常只會在 Node.js 本身的開發過程中發生。
• 4 內部 JavaScript 評估失敗：Node.js 引導程序中的內部 JavaScript 原始碼在評估時無法傳回函式值。這極為罕見，而且通常只會在 Node.js 本身的開發過程中發生。
• 5 致命錯誤：V8 中發生無法復原的致命錯誤。通常會將訊息印至 stderr，並加上 FATAL ERROR 前置詞。
• 6 非函式內部例外處理常式：發生未捕捉的例外，但內部致命例外處理常式函式不知何故設定為非函式，且無法呼叫。
• 7 內部例外處理常式執行時間失敗：發生未捕捉的例外，且內部致命例外處理常式函式本身在嘗試處理時擲回錯誤。例如，如果 'uncaughtException' 或 domain.on('error') 處理常式擲回錯誤，就會發生這種情況。
• 8：未使用。在先前版本的 Node.js 中，結束程式碼 8 有時表示未捕捉的例外。
• 9 無效引數：指定了未知選項，或未提供需要值的選項的值。
• 10 內部 JavaScript 執行時間失敗：Node.js 引導程序中的內部 JavaScript 原始碼在呼叫引導函式時擲出錯誤。這非常罕見，通常只會在 Node.js 本身開發期間發生。
• 12 無效的偵錯引數：已設定 --inspect 和/或 --inspect-brk 選項，但所選的埠號無效或不可用。
• 13 未完成的頂層 Await：await 在頂層程式碼中的函式外部使用，但傳遞的 Promise 從未解析。
• 14 快照失敗：已啟動 Node.js 以建置 V8 啟動快照，但由於未符合應用程式狀態的特定需求而失敗。
• >128 訊號退出：如果 Node.js 收到致命訊號，例如 SIGKILL 或 SIGHUP，則其退出碼將為 128 加上訊號碼的值。這是一種標準 POSIX 做法，因為退出碼定義為 7 位元整數，而訊號退出會設定最高位元，然後包含訊號碼的值。例如，訊號 SIGABRT 的值為 6，因此預期的退出碼將為 128 + 6，或 134。