Node.js v26.0.0 說明文件

命令列 API#

Node.js 隨附多種 CLI 選項。這些選項公開了內建的除錯功能、多種執行指令碼的方式，以及其他有用的執行階段選項。

若要在終端機中以手冊頁面檢視此文件，請執行 man node。

概要#

node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]

node inspect [<program-entry-point> | -e "script" | <host>:<port>] …

node --v8-options

不帶參數執行以啟動 REPL。

關於 node inspect 的更多資訊，請參閱 除錯器 文件。

程式進入點#

程式進入點是一個類似識別符的字串。如果字串不是絕對路徑，則會解析為從當前工作目錄開始的相對路徑。然後，該進入點字串會被解析，就像是從當前工作目錄由 require() 要求的一樣。如果找不到對應的檔案，則會拋出錯誤。

預設情況下，解析出的路徑也會被載入，就像是從 require() 要求的一樣，除非滿足以下其中一個條件——這時它會像被 import() 要求一樣載入。

• 程式啟動時使用了強制進入點以 ECMAScript 模組載入器載入的命令列旗標，例如 --import。
• 檔案副檔名為 .mjs、.mts 或 .wasm。
• 檔案沒有 .cjs 副檔名，且最近的父層 package.json 檔案包含一個頂層 "type" 欄位，其值為 "module"。

詳細資訊請參閱 模組解析與載入。

選項#

所有選項（包括 V8 選項）都允許單字由破折號 (-) 或底線 (_) 分隔。例如，--pending-deprecation 等同於 --pending_deprecation。

如果多次傳入需要單一值的選項（例如 --max-http-header-size），則會使用最後傳入的值。命令列選項的優先順序高於透過 NODE_OPTIONS 環境變數傳入的選項。

-#

stdin 的別名。類似於其他命令列工具中使用 -，意味著指令碼從 stdin 讀取，其餘選項則傳遞給該指令碼。

--#

指示 node 選項的結束。將其餘參數傳遞給指令碼。如果在此之前未提供指令碼檔名或 eval/print 指令碼，則下一個參數將被用作指令碼檔名。

--abort-on-uncaught-exception#

中斷而不是退出會導致生成核心檔案 (core file)，以便使用除錯器（例如 lldb、gdb 和 mdb）進行事後分析。

如果傳入此旗標，仍可透過 process.setUncaughtExceptionCaptureCallback()（以及使用利用它的 node:domain 模組）將行為設定為不中斷。

--allow-addons#

使用 權限模型 (Permission Model) 時，該程序預設無法使用原生附加元件 (native addons)。嘗試這樣做將拋出 ERR_DLOPEN_DISABLED，除非使用者在啟動 Node.js 時明確傳入 --allow-addons 旗標。

範例

// Attempt to require an native addon
require('nodejs-addon-example');
copy

$ node --permission --allow-fs-read=* index.js
node:internal/modules/cjs/loader:1319
  return process.dlopen(module, path.toNamespacedPath(filename));
                 ^

Error: Cannot load native addon because loading addons is disabled.
    at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12)
    at Module.require (node:internal/modules/cjs/loader:1115:19)
    at require (node:internal/modules/helpers:130:18)
    at Object.<anonymous> (/home/index.js:1:15)
    at Module._compile (node:internal/modules/cjs/loader:1233:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12) {
  code: 'ERR_DLOPEN_DISABLED'
}
copy

--allow-child-process#

使用 權限模型 時，該程序預設無法衍生任何子程序。嘗試這樣做將拋出 ERR_ACCESS_DENIED，除非使用者在啟動 Node.js 時明確傳入 --allow-child-process 旗標。

範例

const childProcess = require('node:child_process');
// Attempt to bypass the permission
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']);
copy

$ node --permission --allow-fs-read=* index.js
node:internal/child_process:388
  const err = this._handle.spawn(options);
                           ^
Error: Access to this API has been restricted
    at ChildProcess.spawn (node:internal/child_process:388:28)
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'ChildProcess'
}
copy

child_process.fork() API 會從父程序繼承執行參數。這意味著如果 Node.js 在啟用權限模型且設定了 --allow-child-process 旗標的情況下啟動，任何使用 child_process.fork() 建立的子程序都將自動接收所有相關的權限模型旗標。

此行為也適用於 child_process.spawn()，但在該情況下，旗標是透過 NODE_OPTIONS 環境變數傳播，而不是直接透過程序參數。

--allow-fs-read#

此旗標使用 權限模型 設定檔案系統讀取權限。

--allow-fs-read 旗標的有效參數為：

• * - 允許所有 FileSystemRead 操作。
• 可以使用多個 --allow-fs-read 旗標允許存取多個路徑。範例：--allow-fs-read=/folder1/ --allow-fs-read=/folder2/

範例可在 檔案系統權限 (File System Permissions) 文件中找到。

初始化模組和自訂 --require 模組具有隱式讀取權限。

$ node --permission -r custom-require.js -r custom-require-2.js index.js
copy

• custom-require.js、custom-require-2.js 和 index.js 將預設在允許讀取的清單中。

process.has('fs.read', 'index.js'); // true
process.has('fs.read', 'custom-require.js'); // true
process.has('fs.read', 'custom-require-2.js'); // true
copy

--allow-fs-write#

此旗標使用 權限模型 設定檔案系統寫入權限。

--allow-fs-write 旗標的有效參數為：

• * - 允許所有 FileSystemWrite 操作。
• 可以使用多個 --allow-fs-write 旗標允許存取多個路徑。範例：--allow-fs-write=/folder1/ --allow-fs-write=/folder2/

不再允許使用逗號 (,) 分隔路徑。當傳遞包含逗號的單一旗標時，將會顯示警告。

範例可在 檔案系統權限 (File System Permissions) 文件中找到。

--allow-inspector#

使用 權限模型 時，程序預設無法透過檢查器協定 (inspector protocol) 連線。

嘗試這樣做將拋出 ERR_ACCESS_DENIED，除非使用者在啟動 Node.js 時明確傳入 --allow-inspector 旗標。

範例

const { Session } = require('node:inspector/promises');

const session = new Session();
session.connect();
copy

$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions.
  code: 'ERR_ACCESS_DENIED',
}
copy

--allow-net#

使用 權限模型 時，程序預設無法存取網路。嘗試這樣做將拋出 ERR_ACCESS_DENIED，除非使用者在啟動 Node.js 時明確傳入 --allow-net 旗標。

範例

const http = require('node:http');
// Attempt to bypass the permission
const req = http.get('http://example.com', () => {});

req.on('error', (err) => {
  console.log('err', err);
});
copy

$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions.
  code: 'ERR_ACCESS_DENIED',
}
copy

--allow-wasi#

使用 權限模型 時，程序預設無法建立任何 WASI 執行個體。基於安全原因，除非使用者在主 Node.js 程序中明確傳入 --allow-wasi 旗標，否則該呼叫將拋出 ERR_ACCESS_DENIED。

範例

const { WASI } = require('node:wasi');
// Attempt to bypass the permission
new WASI({
  version: 'preview1',
  // Attempt to mount the whole filesystem
  preopens: {
    '/': '/',
  },
});
copy

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:30:49 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WASI',
}
copy

--allow-worker#

使用 權限模型 時，程序預設無法建立任何工作執行緒 (worker threads)。基於安全原因，除非使用者在主 Node.js 程序中明確傳入 --allow-worker 旗標，否則該呼叫將拋出 ERR_ACCESS_DENIED。

範例

const { Worker } = require('node:worker_threads');
// Attempt to bypass the permission
new Worker(__filename);
copy

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WorkerThreads'
}
copy

--build-sea=config#

從 JSON 設定檔產生 單一可執行應用程式。該參數必須是設定檔的路徑。如果路徑不是絕對路徑，它將被解析為相對於當前工作目錄的路徑。

關於設定欄位、跨平台注意事項和資產 API，請參閱 單一可執行應用程式 文件。

--build-snapshot#

當程序退出時產生快照 blob 並將其寫入磁碟，之後可透過 --snapshot-blob 載入。

在建置快照時，如果未指定 --snapshot-blob，產生的 blob 預設會寫入當前工作目錄下的 snapshot.blob。否則，它將寫入 --snapshot-blob 指定的路徑。

$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js

# Run snapshot.js to initialize the application and snapshot the
# state of it into snapshot.blob.
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

$ echo "console.log(globalThis.foo)" > index.js

# Load the generated snapshot and start the application from index.js.
$ node --snapshot-blob snapshot.blob index.js
I am from the snapshot
copy

可以使用 v8.startupSnapshot API 在建置快照時指定進入點，從而在反序列化時無需額外的進入指令碼。

$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js
$ node --snapshot-blob snapshot.blob
I am from the snapshot
copy

更多資訊，請查閱 v8.startupSnapshot API 文件。

快照目前僅支援在快照建置過程中載入單一進入點，該進入點可以載入內建模組，但不能載入額外的使用者空間模組。使用者可以在建置快照前，使用選擇的打包工具將應用程式打包成單一指令碼。

由於確保所有內建模組的可序列化性很複雜且這些模組隨時間增加，只有一部分內建模組經過充分測試，證明在快照建置過程中是可序列化的。Node.js 核心測試套件會檢查一些相當複雜的應用程式是否可以進行快照。被 Node.js 內建快照擷取 的內建模組清單被視為受支援。當快照建置器遇到無法序列化的內建模組時，可能會導致快照建置程序崩潰。在這種情況下，一個常見的解決方法是推遲載入該模組直到執行階段，使用 v8.startupSnapshot.setDeserializeMainFunction() 或 v8.startupSnapshot.addDeserializeCallback()。如果在快照建置過程中需要對額外模組進行序列化，請在 Node.js 問題追蹤器 中提交請求，並連結到 使用者空間快照的追蹤問題。

--build-snapshot-config#

指定設定快照建立行為的 JSON 設定檔路徑。

目前支援下列選項：

• builder <string> 必要。提供在建置快照前執行的指令碼名稱，就像傳入了 --build-snapshot 並以 builder 作為主要指令碼名稱一樣。
• withoutCodeCache <boolean> 選填。包含程式碼快取 (code cache) 可減少編譯快照中包含的函式所需的時間，代價是快照大小變大且可能破壞快照的可攜性。

使用此旗標時，命令列上提供的額外指令碼檔案將不會被執行，而是被解譯為一般的命令列參數。

-c, --check#

檢查指令碼語法而不執行。

--completion-bash#

列印 Node.js 可用的 bash 自動完成指令碼。

node --completion-bash > node_bash_completion
source node_bash_completion
copy

-C condition, --conditions=condition#

提供自訂 條件式匯出 (conditional exports) 的解析條件。

允許任何數量的自訂字串條件名稱。

預設的 Node.js 條件 "node"、"default"、"import" 和 "require" 將始終按定義套用。

例如，以 "development" 解析來執行模組：

node -C development app.js
copy

--cpu-prof#

在啟動時啟動 V8 CPU 分析器，並在退出前將 CPU 分析檔寫入磁碟。

如果未指定 --cpu-prof-dir，產生的分析檔將放置在當前工作目錄中。

如果未指定 --cpu-prof-name，產生的分析檔名為 CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile。

$ node --cpu-prof index.js
$ ls *.cpuprofile
CPU.20190409.202950.15293.0.0.cpuprofile
copy

如果指定了 --cpu-prof-name，則提供的值將用作檔案名稱的範本。支援下列佔位符，並會在執行階段進行替換：

• ${pid} — 當前程序的 PID。

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js
$ ls *.cpuprofile
CPU.15293.cpuprofile
copy

--cpu-prof-dir#

指定 --cpu-prof 產生的 CPU 分析檔所存放的目錄。

預設值受 --diagnostic-dir 命令列選項控制。

--cpu-prof-interval#

指定 --cpu-prof 產生的 CPU 分析檔的取樣間隔（以微秒為單位）。預設值為 1000 微秒。

--cpu-prof-name#

指定 --cpu-prof 產生的 CPU 分析檔的檔案名稱。

--diagnostic-dir=directory#

設定寫入所有診斷輸出檔案的目錄。預設為當前工作目錄。

影響以下項目的預設輸出目錄：

• --cpu-prof-dir
• --heap-prof-dir
• --redirect-warnings

--disable-proto=mode#

停用 Object.prototype.__proto__ 屬性。如果 mode 為 delete，則該屬性會被完全移除。如果 mode 為 throw，存取該屬性將拋出錯誤碼為 ERR_PROTO_ACCESS 的例外。

--disable-sigusr1#

停用透過向程序發送 SIGUSR1 訊號來啟動除錯工作階段的功能。

--disable-warning=code-or-type#

依據 code 或 type 停用特定的程序警告。

從 process.emitWarning() 發出的警告可能包含 code 和 type。此選項將不會發出具有相符 code 或 type 的警告。

棄用警告 清單。

Node.js 核心警告類型為：DeprecationWarning 和 ExperimentalWarning。

例如，當使用 node --disable-warning=DEP0025 執行時，下列指令碼將不會發出 DEP0025 require('node:sys')。

import sys from 'node:sys';
const sys = require('node:sys');
copy

例如，當使用 node --disable-warning=ExperimentalWarning 執行時，下列指令碼將發出 DEP0025 require('node:sys')，但不會發出任何實驗性警告（例如 <=v21 中的 ExperimentalWarning: vm.measureMemory is an experimental feature）。

import sys from 'node:sys';
import vm from 'node:vm';

vm.measureMemory();
const sys = require('node:sys');
const vm = require('node:vm');

vm.measureMemory();
copy

--disable-wasm-trap-handler#

Node.js 在 64 位元平台上啟用基於 V8 陷阱處理器的 WebAssembly 邊界檢查，這透過消除對內聯邊界檢查的需求，顯著提高了 WebAssembly 的效能。此最佳化需要為每個 WebAssembly 記憶體執行個體配置一個大型虛擬記憶體 cage（目前對於 32 位元 WebAssembly 記憶體通常為 8GB，對於 64 位元 WebAssembly 記憶體為 16GB）以捕獲越界存取。在大多數 64 位元平台上，虛擬記憶體位址空間通常足夠大（約 128TB）以容納典型的 WebAssembly 使用，但如果機器對虛擬記憶體有手動限制（例如透過 ulimit -v），WebAssembly 記憶體配置更有可能失敗並顯示 WebAssembly.Memory(): could not allocate memory。

在啟動時，Node.js 會自動檢查是否有足夠的虛擬記憶體可用來配置至少一個 cage，如果沒有，陷阱處理器最佳化會自動停用，以便 WebAssembly 仍可以使用內聯邊界檢查執行（效能較不理想）。但如果應用程式需要建立許多 WebAssembly 記憶體執行個體，且機器仍對虛擬記憶體配置了相對較高的限制，則由於虛擬記憶體使用量增加，WebAssembly 記憶體執行個體的配置可能會比預期更快失敗。

--disable-wasm-trap-handler 完全停用了此最佳化，因此 WebAssembly 記憶體執行個體始終使用內聯邊界檢查，而不是保留大型虛擬記憶體 cage。這允許在 Node.js 程序可用的虛擬記憶體位址空間受限時建立更多執行個體。

--disallow-code-generation-from-strings#

使內建語言功能（例如 eval 和 new Function）從字串產生程式碼時拋出例外。這不會影響 Node.js node:vm 模組。

--dns-result-order=order#

設定 dns.lookup() 和 dnsPromises.lookup() 中 order 的預設值。值可以是：

• ipv4first：將預設 order 設定為 ipv4first。
• ipv6first：將預設 order 設定為 ipv6first。
• verbatim：將預設 order 設定為 verbatim。

預設值為 verbatim，且 dns.setDefaultResultOrder() 的優先順序高於 --dns-result-order。

--enable-fips#

在啟動時啟用 FIPS 相容的加密。（要求 Node.js 使用 FIPS 相容的 OpenSSL 建置。）

--enable-source-maps#

啟用堆疊追蹤的 原始碼映射 (Source Map) 支援。

使用轉譯器（如 TypeScript）時，應用程式拋出的堆疊追蹤會參考轉譯後的程式碼，而非原始原始碼位置。--enable-source-maps 啟用 Source Maps 的快取，並盡力回報相對於原始原始碼檔案的堆疊追蹤。

覆寫 Error.prepareStackTrace 可能會阻止 --enable-source-maps 修改堆疊追蹤。在覆寫函式中呼叫並回傳原始 Error.prepareStackTrace 的結果，以使用 source maps 修改堆疊追蹤。

const originalPrepareStackTrace = Error.prepareStackTrace;
Error.prepareStackTrace = (error, trace) => {
  // Modify error and trace and format stack trace with
  // original Error.prepareStackTrace.
  return originalPrepareStackTrace(error, trace);
};
copy

注意，存取 Error.stack 時啟用 source maps 可能會為您的應用程式引入延遲。如果您在應用程式中頻繁存取 Error.stack，請考慮 --enable-source-maps 的效能影響。

--entry-url#

當存在時，Node.js 會將進入點解釋為 URL，而不是路徑。

遵循 ECMAScript 模組 解析規則。

URL 中的任何查詢參數或雜湊 (hash) 皆可透過 import.meta.url 存取。

node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'
node --entry-url 'file.ts?query#hash'
node --entry-url 'data:text/javascript,console.log("Hello")'
copy

--env-file-if-exists=file#

行為與 --env-file 相同，但如果檔案不存在，不會拋出錯誤。

--env-file=file#

從相對當前目錄的檔案中載入環境變數，使其在 process.env 上可供應用程式使用。設定 Node.js 的環境變數（例如 NODE_OPTIONS）會被解析並套用。如果環境變數和檔案中定義了相同的變數，則環境中的值優先。

您可以傳入多個 --env-file 參數。後續的檔案會覆寫先前檔案中定義的現有變數。

如果檔案不存在，將拋出錯誤。

node --env-file=.env --env-file=.development.env index.js
copy

檔案格式應為每行一個鍵值對，環境變數名稱與值以 = 分隔。

PORT=3000
copy

# 之後的任何文字皆視為註解。

# This is a comment
PORT=3000 # This is also a comment
copy

值可以以引號 `、" 或 ' 開頭和結尾。這些引號會從值中省略。

USERNAME="nodejs" # will result in `nodejs` as the value.
copy

支援多行值。

MULTI_LINE="THIS IS
A MULTILINE"
# will result in `THIS IS\nA MULTILINE` as the value.
copy

鍵之前的 export 關鍵字會被忽略。

export USERNAME="nodejs" # will result in `nodejs` as the value.
copy

如果您想從可能不存在的檔案中載入環境變數，可以使用 --env-file-if-exists 旗標。

-e, --eval "script"#

將下列參數評估為 JavaScript。在 REPL 中預定義的模組也可以在 script 中使用。

如果 script 以 - 開頭，請使用 = 傳遞（例如 node --print --eval=-42），以便將其解析為 --eval 的值。

在 Windows 上，使用 cmd.exe 時單引號無法正確運作，因為它僅辨識雙引號 " 進行引用。在 Powershell 或 Git bash 中，' 和 " 皆可使用。

可以執行包含內聯型別的程式碼，除非提供了 --no-strip-types 旗標。

--experimental-addon-modules#

啟用 .node 附加元件的實驗性匯入支援。

--experimental-config-file=config#

如果存在，Node.js 將在指定路徑尋找設定檔。Node.js 將讀取該設定檔並套用設定。設定檔應為具有下列結構的 JSON 檔案。$schema 中的 vX.Y.Z 必須替換為您使用的 Node.js 版本。

{
  "$schema": "https://nodejs.com.tw/dist/vX.Y.Z/docs/node-config-schema.json",
  "nodeOptions": {
    "import": [
      "amaro/strip"
    ],
    "watch-path": "src",
    "watch-preserve-output": true
  },
  "test": {
    "test-isolation": "process"
  },
  "watch": {
    "watch-preserve-output": true
  }
}
copy

設定檔支援命名空間專屬選項。

• nodeOptions 欄位包含 NODE_OPTIONS 中允許的 CLI 旗標。

• 像 test、watch 和 permission 這樣的命名空間欄位包含該子系統專屬的設定。

當設定檔中存在命名空間時，Node.js 會自動啟用對應的旗標（例如 --test、--watch、--permission）。這允許您在不需在命令列上明確傳入旗標的情況下，設定子系統專屬的選項。

例如：

{
  "test": {
    "test-isolation": "process"
  }
}
copy

等同於：

node --test --test-isolation=process
copy

要在仍使用命名空間選項的同時停用自動旗標，您可以在命名空間內將旗標明確設為 false。

{
  "test": {
    "test": false,
    "test-isolation": "process"
  }
}
copy

不支援 No-op 旗標。目前並非所有 V8 旗標皆受支援。

可以使用 官方 JSON 結構描述 (schema) 來驗證設定檔，該檔案可能因 Node.js 版本而異。設定檔中的每個鍵對應於可作為命令列參數傳入的旗標。鍵的值即為傳遞給該旗標的值。

例如，上述設定檔等同於下列命令列參數：

node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
copy

設定的優先順序如下：

1. NODE_OPTIONS 和命令列選項
2. 設定檔
3. Dotenv NODE_OPTIONS

設定檔中的值不會覆寫環境變數和命令列選項中的值，但會覆寫由 --env-file 旗標解析的 NODE_OPTIONS 環境變數檔案中的值。

鍵不能在相同或不同命名空間內重複。

如果設定檔包含未知鍵或無法在命名空間中使用的鍵，設定解析器將拋出錯誤。

Node.js 不會對使用者提供的設定進行清理或驗證，因此絕對不要使用不受信任的設定檔。

--experimental-default-config-file#

如果存在 --experimental-default-config-file 旗標，Node.js 將在當前工作目錄中尋找 node.config.json 檔案並將其作為設定檔載入。

--experimental-eventsource#

在全域範圍啟用 EventSource Web API 的公開。

--experimental-import-meta-resolve#

啟用實驗性 import.meta.resolve() 父 URL 支援，允許傳入第二個 parentURL 參數以進行上下文解析。

先前將整個 import.meta.resolve 功能納入受限。

--experimental-inspector-network-resource#

啟用檢查器網路資源的實驗性支援。

--experimental-loader=module#

不建議使用此旗標，並可能在未來的 Node.js 版本中移除。請改用 --import 搭配 register()。

指定包含導出的 非同步模組自訂掛鉤 (asynchronous module customization hooks) 的模組。module 可以是任何被 import 指定符 接受的字串。

如果與 權限模型 搭配使用，此功能需要 --allow-worker。

--experimental-network-inspection#

啟用 Chrome DevTools 網路檢查的實驗性支援。

--experimental-print-required-tla#

如果被 require() 的 ES 模組包含頂層 await，此旗標允許 Node.js 評估該模組，嘗試定位頂層 awaits，並列印其位置以幫助使用者找到它們。

--experimental-quic#

啟用 QUIC 協定的實驗性支援。

--experimental-sea-config#

使用此旗標產生可注入 Node.js 二進位檔案以製作 單一可執行應用程式 的 blob。詳情請參閱關於 此設定 的文件。

--experimental-shadow-realm#

使用此旗標啟用 ShadowRealm 支援。

--experimental-storage-inspection#

啟用儲存檢查的實驗性支援。

--experimental-stream-iter#

啟用實驗性 node:stream/iter 模組。

--experimental-test-coverage#

當與 node:test 模組結合使用時，程式碼覆蓋率報告將作為測試執行器輸出的一部分產生。如果沒有執行任何測試，則不會產生覆蓋率報告。更多詳細資訊，請參閱關於 從測試收集程式碼覆蓋率 的文件。

--experimental-test-module-mocks#

在測試執行器中啟用模組模擬 (module mocking)。

如果與 權限模型 搭配使用，此功能需要 --allow-worker。

--experimental-vm-modules#

在 node:vm 模組中啟用實驗性 ES 模組支援。

--experimental-wasi-unstable-preview1#

啟用實驗性 WebAssembly 系統介面 (WASI) 支援。

--experimental-worker-inspection#

啟用 Chrome DevTools 工作執行緒檢查的實驗性支援。

--expose-gc#

此旗標將公開 V8 的 gc 擴充功能。

if (globalThis.gc) {
  globalThis.gc();
}
copy

--force-context-aware#

停用載入非 上下文感知 (context-aware) 的原生附加元件。

--force-fips#

在啟動時強制使用 FIPS 相容的加密。（無法從指令碼程式碼停用。）（要求與 --enable-fips 相同。）

--force-node-api-uncaught-exceptions-policy#

在 Node-API 非同步回呼上強制執行 uncaughtException 事件。

為防止現有的附加元件導致程序崩潰，此旗標預設未啟用。將來，此旗標將預設啟用以強制執行正確行為。

--frozen-intrinsics#

啟用實驗性凍結內建元件 (frozen intrinsics)，如 Array 和 Object。

僅支援根上下文。無法保證 globalThis.Array 真的是預設的內建參考。在此旗標下程式碼可能會崩潰。

為允許新增 polyfills，--require 和 --import 皆會在凍結內建元件之前執行。

--heap-prof#

在啟動時啟動 V8 堆積分析器 (heap profiler)，並在退出前將堆積分析檔寫入磁碟。

如果未指定 --heap-prof-dir，產生的分析檔將放置在當前工作目錄中。

如果未指定 --heap-prof-name，產生的分析檔名為 Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile。

$ node --heap-prof index.js
$ ls *.heapprofile
Heap.20190409.202950.15293.0.001.heapprofile
copy

--heap-prof-dir#

指定 --heap-prof 產生的堆積分析檔所存放的目錄。

預設值受 --diagnostic-dir 命令列選項控制。

--heap-prof-interval#

指定 --heap-prof 產生的堆積分析檔的平均取樣間隔（以位元組為單位）。預設值為 512 * 1024 位元組。

--heap-prof-name#

指定 --heap-prof 產生的堆積分析檔的檔案名稱。

--heapsnapshot-near-heap-limit=max_count#

當 V8 堆積使用量接近堆積限制時，將 V8 堆積快照寫入磁碟。count 應為非負整數（在此情況下，Node.js 寫入磁碟的快照不會超過 max_count 個）。

產生快照時，可能會觸發記憶體回收 (garbage collection) 並降低堆積使用量。因此在 Node.js 執行個體最終耗盡記憶體之前，可能會有多個快照被寫入磁碟。這些堆積快照可以進行比較，以確定連續快照拍攝期間配置了哪些物件。不能保證 Node.js 會精確地將 max_count 個快照寫入磁碟，但當 max_count 大於 0 時，它會盡力在 Node.js 執行個體耗盡記憶體之前產生至少一個且最多 max_count 個快照。

產生 V8 快照需要時間和記憶體（由 V8 堆積管理的記憶體和 V8 堆積之外的原生記憶體）。堆積越大，所需的資源就越多。Node.js 將調整 V8 堆積以容納額外的 V8 堆積記憶體開銷，並盡力避免用盡該程序可用的所有記憶體。當程序使用的記憶體超過系統認為合適的範圍時，該程序可能會被系統突然終止，具體取決於系統設定。

$ node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.js
Wrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshot
Wrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshot
Wrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot

<--- Last few GCs --->

[49580:0x110000000]     4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms  (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed
[49580:0x110000000]     4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms  (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
....
copy

--heapsnapshot-signal=signal#

啟用一個訊號處理器，當接收到指定訊號時，導致 Node.js 程序寫入堆積傾印 (heap dump)。signal 必須是有效的訊號名稱。預設為停用。

$ node --heapsnapshot-signal=SIGUSR2 index.js &
$ ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
node         1  5.5  6.1 787252 247004 ?       Ssl  16:43   0:02 node --heapsnapshot-signal=SIGUSR2 index.js
$ kill -USR2 1
$ ls
Heap.20190718.133405.15554.0.001.heapsnapshot
copy

-h, --help#

列印 node 命令列選項。此選項的輸出比本文件簡略。

--icu-data-dir=file#

指定 ICU 資料載入路徑。（覆寫 NODE_ICU_DATA。）

--import=module#

在啟動時預載入指定模組。如果多次提供該旗標，每個模組將按出現順序循序執行，從 NODE_OPTIONS 中提供的模組開始。

遵循 ECMAScript 模組 解析規則。使用 --require 載入 CommonJS 模組。使用 --require 預載入的模組將在 --import 預載入的模組之前執行。

模組會被預載入到主執行緒以及任何工作執行緒、衍生程序或叢集程序中。

--input-type=type#

此項將 Node.js 設定為將 --eval 或 STDIN 輸入解釋為 CommonJS 或 ES 模組。有效值為 "commonjs"、"module"、"module-typescript" 和 "commonjs-typescript"。"-typescript" 值在旗標 --no-strip-types 下不可用。預設為無值，如果傳入 --no-experimental-detect-module 則為 "commonjs"。

如果未提供 --input-type，Node.js 將嘗試透過下列步驟偵測語法：

1. 將輸入作為 CommonJS 執行。
2. 如果步驟 1 失敗，將輸入作為 ES 模組執行。
3. 如果步驟 2 失敗並出現 SyntaxError，則移除型別。
4. 如果步驟 3 失敗並出現錯誤碼 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX 或 ERR_INVALID_TYPESCRIPT_SYNTAX，拋出步驟 2 的錯誤（包含訊息中的 TypeScript 錯誤），否則作為 CommonJS 執行。
5. 如果步驟 4 失敗，將輸入作為 ES 模組執行。

為了避免多次語法偵測步驟的延遲，可以使用 --input-type=type 旗標來指定應如何解釋 --eval 輸入。

REPL 不支援此選項。使用 --input-type=module 搭配 --print 將拋出錯誤，因為 --print 不支援 ES 模組語法。

--insecure-http-parser#

啟用 HTTP 解析器上的寬鬆旗標。這可能允許與不符合標準的 HTTP 實作進行交互操作。

啟用時，解析器將接受以下內容：

• 無效的 HTTP 標頭值。
• 無效的 HTTP 版本。
• 允許包含 Transfer-Encoding 和 Content-Length 標頭的訊息。
• 允許當 Connection: close 存在時，訊息後包含額外資料。
• 允許在提供 chunked 後包含額外的傳輸編碼。
• 允許使用 \n 作為標記分隔符，而非 \r\n。
• 允許在區塊 (chunk) 後不提供 \r\n。
• 允許在區塊大小之後及 \r\n 之前存在空格。

以上所有內容都將使您的應用程式暴露於請求走私 (request smuggling) 或中毒攻擊 (poisoning attack)。請避免使用此選項。

--inspect-brk[=[host:]port]#

在 host:port 啟用檢查器，並在使用者指令碼開頭中斷。預設 host:port 為 127.0.0.1:9229。如果指定埠號 0，將使用隨機可用埠號。

請參閱 Node.js 的 V8 檢查器整合 以進一步了解 Node.js 除錯器。

關於 host 參數的使用，請參閱下方的 安全性警告。

--inspect-port=[host:]port#

設定檢查器啟用時使用的 host:port。在透過發送 SIGUSR1 訊號啟用檢查器時很有用。除非傳入了 --disable-sigusr1。

預設主機為 127.0.0.1。如果指定埠號 0，將使用隨機可用埠號。

關於 host 參數的使用，請參閱下方的 安全性警告。

--inspect-publish-uid=stderr,http#

指定檢查器 WebSocket URL 的公開方式。

預設情況下，檢查器 WebSocket URL 可在 stderr 和 http://host:port/json/list 的 /json/list 端點下存取。

--inspect-wait[=[host:]port]#

在 host:port 啟用檢查器，並等待除錯器連接。預設 host:port 為 127.0.0.1:9229。如果指定埠號 0，將使用隨機可用埠號。

請參閱 Node.js 的 V8 檢查器整合 以進一步了解 Node.js 除錯器。

關於 host 參數的使用，請參閱下方的 安全性警告。

--inspect[=[host:]port]#

在 host:port 啟用檢查器。預設為 127.0.0.1:9229。如果指定埠號 0，將使用隨機可用埠號。

V8 檢查器整合允許 Chrome DevTools 和 IDE 等工具除錯及分析 Node.js 執行個體。這些工具透過 TCP 埠連線到 Node.js 執行個體，並使用 Chrome DevTools 協定 進行通訊。請參閱 Node.js 的 V8 檢查器整合 以進一步了解 Node.js 除錯器。

警告：將檢查器繫結到公開的 IP:port 組合是不安全的#

將檢查器繫結到具有開放埠的公開 IP（包括 0.0.0.0）是不安全的，因為這允許外部主機連線到檢查器並執行 遠端程式碼執行 攻擊。

如果指定主機，請確保下列其中一點：

• 主機無法從公用網路存取。
• 防火牆禁止該埠上的非預期連線。

更具體地說，如果該埠（預設為 9229）未受到防火牆保護，--inspect=0.0.0.0 是不安全的。

更多資訊，請參閱 除錯安全隱憂 章節。

-i, --interactive#

即使 stdin 看起來不是終端機，也會開啟 REPL。

--jitless#

停用 可執行記憶體的執行階段配置。基於安全考量，某些平台可能需要此項。它也可以減少其他平台上的攻擊面，但效能影響可能很嚴重。

--localstorage-file=file#

用於儲存 localStorage 資料的檔案。如果檔案不存在，則會在第一次存取 localStorage 時建立。同一個檔案可由多個 Node.js 程序並發共用。

--max-http-header-size=size#

指定 HTTP 標頭的最大大小（以位元組為單位）。預設為 16 KiB。

--max-old-space-size-percentage=percentage#

將 V8 老記憶體區塊的最大記憶體大小設為可用系統記憶體的百分比。當同時指定兩者時，此旗標優先於 --max-old-space-size。

percentage 參數必須是大於 0 且最高為 100 的數字，代表要配置給 V8 堆積的可用系統記憶體百分比。

注意： 此旗標使用 --max-old-space-size，由於整數溢位問題，該旗標在 32 位元平台上可能不可靠。

# Using 50% of available system memory
node --max-old-space-size-percentage=50 index.js

# Using 75% of available system memory
node --max-old-space-size-percentage=75 index.js
copy

--napi-modules#

此選項為 no-op（無作用）。保留它是為了相容性。

--network-family-autoselection-attempt-timeout#

設定網路系列自動選擇嘗試超時的預設值。更多資訊，請參閱 net.getDefaultAutoSelectFamilyAttemptTimeout()。

--no-addons#

停用 node-addons 匯出條件以及載入原生附加元件。當指定 --no-addons 時，呼叫 process.dlopen 或要求原生 C++ 附加元件將會失敗並拋出例外。

--no-async-context-frame#

停用由 AsyncContextFrame 支援的 AsyncLocalStorage，並改用依賴 async_hooks 的先前實作。保留先前的模型是為了與 Electron 相容，以及處理內容流程可能不同的情況。然而，如果發現流程有差異，請回報。

--no-deprecation#

靜默棄用警告。

--no-experimental-detect-module#

停用使用 語法偵測 來決定模組類型。

--no-experimental-global-navigator#

停用在全域範圍公開 Navigator API。

--no-experimental-repl-await#

使用此旗標停用 REPL 中的頂層 await。

--no-experimental-require-module#

--no-require-module 的舊版別名。

--no-experimental-sqlite#

停用實驗性 node:sqlite 模組。

--no-experimental-websocket#

停用在全域範圍公開 <WebSocket>。

--no-experimental-webstorage#

停用 Web Storage 支援。

--no-extra-info-on-fatal-exception#

隱藏導致退出的致命例外上的額外資訊。

--no-force-async-hooks-checks#

停用 async_hooks 的執行階段檢查。當啟用 async_hooks 時，這些檢查仍會動態啟用。

--no-global-search-paths#

不要從全域路徑（如 $HOME/.node_modules 和 $NODE_PATH）搜尋模組。

--no-network-family-autoselection#

除非連線選項明確啟用，否則停用系列自動選擇演算法。

--no-require-module#

停用在 require() 中載入同步 ES 模組圖的支援。

請參閱 使用 require() 載入 ECMAScript 模組。

--no-strip-types#

停用 TypeScript 檔案的型別移除。更多資訊，請參閱 TypeScript 型別移除 文件。

--no-warnings#

靜默所有程序警告（包括棄用警告）。

--node-memory-debug#

為 Node.js 內部記憶體洩漏啟用額外的除錯檢查。這通常僅對正在除錯 Node.js 本身的開發人員有用。

--openssl-config=file#

在啟動時載入 OpenSSL 設定檔。除其他用途外，如果 Node.js 是使用已啟用 FIPS 的 OpenSSL 建置，則可用於啟用 FIPS 相容加密。

--openssl-legacy-provider#

啟用 OpenSSL 3.0 舊版提供者 (legacy provider)。更多資訊，請參閱 OSSL_PROVIDER-legacy。

--openssl-shared-config#

啟用從 OpenSSL 設定檔讀取預設 OpenSSL 設定區段 openssl_conf。預設設定檔名稱為 openssl.cnf，但可使用環境變數 OPENSSL_CONF 或命令列選項 --openssl-config 進行變更。預設 OpenSSL 設定檔的位置取決於 OpenSSL 如何連結到 Node.js。共用 OpenSSL 設定可能會有非預期的影響，建議使用 Node.js 專屬的設定區段 nodejs_conf（這也是不使用此選項時的預設值）。

--pending-deprecation#

發出待處理的棄用警告。

待處理棄用警告通常與執行階段棄用警告相同，顯著的例外是它們預設是關閉的，除非設定了 --pending-deprecation 命令列旗標或 NODE_PENDING_DEPRECATION=1 環境變數。待處理棄用警告用於提供一種選擇性的「早期預警」機制，開發人員可以利用該機制來偵測棄用的 API 使用情況。

--permission#

為當前程序啟用權限模型。啟用時，下列權限受限：

• 檔案系統 - 可透過 --allow-fs-read, --allow-fs-write 旗標管理
• 網路 - 可透過 --allow-net 旗標管理
• 子程序 - 可透過 --allow-child-process 旗標管理
• 工作執行緒 - 可透過 --allow-worker 旗標管理
• WASI - 可透過 --allow-wasi 旗標管理
• 附加元件 - 可透過 --allow-addons 旗標管理

--permission-audit#

僅針對權限模型啟用稽核 (audit)。啟用時，會執行權限檢查但不會拒絕存取。相反地，會透過診斷通道針對每個權限違規發出警告。

--preserve-symlinks#

指示模組載入器在解析和快取模組時保留符號連結。

預設情況下，當 Node.js 從符號連結到磁碟上不同位置的路徑載入模組時，Node.js 會取消參照連結並使用模組在磁碟上的實際「真實路徑」作為識別符，並作為根路徑來定位其他依賴模組。在大多數情況下，這種預設行為是可以接受的。然而，當使用符號連結的對等依賴項 (peer dependencies) 時，如下例所示，如果 moduleA 嘗試要求 moduleB 作為對等依賴項，預設行為會導致拋出例外。

{appDir}
 ├── app
 │   ├── index.js
 │   └── node_modules
 │       ├── moduleA -> {appDir}/moduleA
 │       └── moduleB
 │           ├── index.js
 │           └── package.json
 └── moduleA
     ├── index.js
     └── package.json
copy

--preserve-symlinks 命令列旗標指示 Node.js 使用模組的符號連結路徑而非真實路徑，從而允許找到符號連結的對等依賴項。

但請注意，使用 --preserve-symlinks 可能會有其他副作用。特別是，如果原生模組在依賴樹中從多於一個位置連結，則該模組可能會載入失敗（Node.js 會將其視為兩個獨立模組並嘗試載入該模組多次，導致拋出例外）。

--preserve-symlinks 旗標不適用於主模組，這使得 node --preserve-symlinks node_module/.bin/<foo> 可以運作。若要將相同的行為套用於主模組，請同時使用 --preserve-symlinks-main。

--preserve-symlinks-main#

指示模組載入器在解析和快取主模組 (require.main) 時保留符號連結。

此旗標存在是為了讓主模組可以選擇採用與 --preserve-symlinks 為所有其他匯入所提供的相同行為；然而為了與舊版 Node.js 相容，它們是分開的旗標。

--preserve-symlinks-main 不代表 --preserve-symlinks；當不希望在解析相對路徑之前遵循符號連結時，除了 --preserve-symlinks 外，請使用 --preserve-symlinks-main。

更多資訊請參閱 --preserve-symlinks。

-p, --print "script"#

與 -e 相同，但會列印結果。

--prof#

產生 V8 分析器輸出。

--prof-process#

處理使用 V8 選項 --prof 產生的 V8 分析器輸出。

--redirect-warnings=file#

將程序警告寫入給定檔案，而不是列印到 stderr。如果檔案不存在將建立，如果存在則會附加到其中。如果嘗試寫入檔案時發生錯誤，警告將改為寫入 stderr。

file 名稱可以是絕對路徑。如果不是，其寫入的預設目錄受 --diagnostic-dir 命令列選項控制。

--report-compact#

以精簡格式寫入報告（單行 JSON），比設計給人類閱讀的預設多行格式更容易被日誌處理系統消耗。

--report-dir=directory, --report-directory=directory#

報告生成的所在地點。

--report-exclude-env#

當傳入 --report-exclude-env 時，生成的診斷報告將不包含 environmentVariables 資料。

--report-exclude-network#

從診斷報告中排除 header.networkInterfaces。預設未設定此項，網路介面會被包含在內。

--report-filename=filename#

寫入報告的檔案名稱。

如果檔案名稱設為 'stdout' 或 'stderr'，報告將分別寫入程序的 stdout 或 stderr。

--report-on-fatalerror#

啟用在導致應用程式終止的致命錯誤（Node.js 執行階段內部的錯誤，如記憶體不足）時觸發報告。有助於檢查各種診斷資料元素，如堆積、堆疊、事件迴圈狀態、資源消耗等，以分析致命錯誤。

--report-on-signal#

啟用在執行中的 Node.js 程序接收到指定（或預定義）的訊號時產生報告。觸發報告的訊號透過 --report-signal 指定。

--report-signal=signal#

設定或重設報告產生的訊號（Windows 不支援）。預設訊號為 SIGUSR2。

--report-uncaught-exception#

啟用在程序因未捕獲的例外而退出時產生報告。當結合原生堆疊和其他執行階段環境資料來檢查 JavaScript 堆疊時非常有用。

-r, --require module#

在啟動時預載入指定模組。

遵循 require() 的模組解析規則。module 可以是檔案路徑或 node 模組名稱。

使用 --require 預載入的模組將在 --import 預載入的模組之前執行。

模組會被預載入到主執行緒以及任何工作執行緒、衍生程序或叢集程序中。

--run#

這會執行 package.json 的 "scripts" 物件中的指定指令。如果提供的 "command" 不存在，它將列出可用的指令碼。

--run 將向上搜尋到根目錄並找到一個 package.json 檔案來執行指令。

--run 會將當前目錄的每個祖先的 ./node_modules/.bin 加入 PATH 前面，以便在存在多個 node_modules 目錄時從不同資料夾執行二進位檔（如果 ancestor-folder/node_modules/.bin 是一個目錄的話）。

--run 在包含相關 package.json 的目錄中執行該指令。

例如，下列指令將執行當前資料夾中 package.json 的 test 指令碼：

$ node --run test
copy

您也可以將參數傳遞給指令。-- 之後的任何參數都將附加到指令碼。

$ node --run test -- --verbose
copy

預期限制#

node --run 的設計目的並非為了匹配 npm run 或其他套件管理器的 run 指令行為。Node.js 的實作刻意保持精簡，以便將效能集中在最常見的使用案例上。其他 run 實作中刻意被排除的功能包括：

• 除了指定的腳本外，還會執行 pre 或 post 腳本。
• 定義套件管理器專屬的環境變數。

環境變數#

當使用 --run 執行腳本時，會設定以下環境變數：

• NODE_RUN_SCRIPT_NAME：正在執行的腳本名稱。例如，如果使用 --run 來執行 test，則此變數的值為 test。
• NODE_RUN_PACKAGE_JSON_PATH：正在處理的 package.json 路徑。

--secure-heap-min=n#

使用 --secure-heap 時，--secure-heap-min 旗標會指定安全堆積（secure heap）的最小配置大小。最小值為 2。最大值為 --secure-heap 的設定值或 2147483647（取兩者中較小者）。給定的值必須是 2 的冪次方。

--secure-heap=n#

初始化一個大小為 n 位元組的 OpenSSL 安全堆積。初始化後，該安全堆積會用於 OpenSSL 在金鑰產生及其他操作期間的特定類型配置。這在防止敏感資訊因指標越界（overrun 或 underrun）而洩露時很有用。

安全堆積的大小是固定的，無法在執行階段調整，因此如果使用它，務必選擇足夠大的堆積大小以涵蓋所有應用程式的使用需求。

給定的堆積大小必須是 2 的冪次方。任何小於 2 的值都會停用安全堆積。

預設情況下，安全堆積是停用的。

Windows 不提供安全堆積。

詳情請參閱 CRYPTO_secure_malloc_init。

--snapshot-blob=path#

與 --build-snapshot 一起使用時，--snapshot-blob 指定寫入產生的快照 blob 的路徑。若未指定，產生的 blob 會寫入當前工作目錄下的 snapshot.blob。

若在沒有 --build-snapshot 的情況下使用，--snapshot-blob 會指定用於還原應用程式狀態的 blob 路徑。

載入快照時，Node.js 會檢查：

1. 執行中的 Node.js 二進位檔版本、架構與平台，必須與產生快照的二進位檔完全相同。
2. V8 旗標與 CPU 功能必須與產生快照的二進位檔相容。

如果不匹配，Node.js 將拒絕載入快照並以狀態碼 1 退出。

--test#

啟動 Node.js 命令列測試執行器。此旗標不能與 --watch-path、--check、--eval、--interactive 或偵測器（inspector）同時使用。詳情請參閱從命令列執行測試的文件。

--test-concurrency#

測試執行器 CLI 同時執行的最大測試檔案數。如果 --test-isolation 設為 'none'，則忽略此旗標，並將併發數設為 1。否則，預設併發數為 os.availableParallelism() - 1。

--test-coverage-branches=threshold#

要求最低的分支覆蓋率百分比。如果程式碼覆蓋率未達到指定的閾值，處理序將以代碼 1 退出。

--test-coverage-exclude#

使用 glob 模式從程式碼覆蓋率中排除特定檔案，該模式可匹配絕對與相對檔案路徑。

此選項可指定多次，以排除多個 glob 模式。

如果同時提供了 --test-coverage-exclude 和 --test-coverage-include，檔案必須同時符合兩者標準才會包含在覆蓋率報告中。

預設情況下，所有匹配的測試檔案都會從覆蓋率報告中排除。指定此選項將覆蓋預設行為。

--test-coverage-functions=threshold#

要求最低的函式覆蓋率百分比。如果程式碼覆蓋率未達到指定的閾值，處理序將以代碼 1 退出。

--test-coverage-include#

使用 glob 模式將特定檔案包含在程式碼覆蓋率中，該模式可匹配絕對與相對檔案路徑。

此選項可指定多次，以包含多個 glob 模式。

如果同時提供了 --test-coverage-exclude 和 --test-coverage-include，檔案必須同時符合兩者標準才會包含在覆蓋率報告中。

--test-coverage-lines=threshold#

要求最低的行覆蓋率百分比。如果程式碼覆蓋率未達到指定的閾值，處理序將以代碼 1 退出。

--test-force-exit#

設定測試執行器在所有已知測試執行完成後立即結束處理序，即使事件迴圈原本仍處於活躍狀態亦同。

--test-global-setup=module#

指定一個在所有測試執行前進行評估的模組，可用於設定測試的全域狀態或裝置（fixtures）。

詳情請參閱全域設定與拆除的文件。

--test-isolation=mode#

設定測試執行器中使用的測試隔離類型。當 mode 為 'process' 時，每個測試檔案會在獨立的子處理序中執行。當 mode 為 'none' 時，所有測試檔案會在與測試執行器相同的處理序中執行。預設隔離模式為 'process'。若未存在 --test 旗標，此旗標將被忽略。更多資訊請參閱測試執行器執行模型章節。

--test-name-pattern#

一個正規表示式，設定測試執行器僅執行名稱符合指定模式的測試。詳情請參閱依名稱篩選測試的文件。

如果同時提供了 --test-name-pattern 和 --test-skip-pattern，測試必須同時滿足兩個要求才能被執行。

--test-only#

設定測試執行器僅執行設定了 only 選項的最上層測試。當停用測試隔離時，此旗標非必要。

--test-reporter#

執行測試時使用的測試報告器。詳情請參閱測試報告器的文件。

--test-reporter-destination#

對應測試報告器的輸出目標。詳情請參閱測試報告器的文件。

--test-rerun-failures#

指定一個檔案路徑，允許測試執行器在執行之間保存測試套件的狀態。測試執行器將使用此檔案判斷哪些測試已經成功或失敗，從而允許在不重新執行整個測試套件的情況下，僅重新執行失敗的測試。如果檔案不存在，測試執行器將會建立它。詳情請參閱重新執行失敗測試的文件。

--test-shard#

要執行的測試套件分片（shard），格式為 <index>/<total>，其中：

• index 為正整數，代表分割部分的索引。
• total 為正整數，代表分割部分的總數。

此指令會將所有測試檔案平均分為 total 等份，並僅執行位於 index 部分的檔案。

例如，若要將測試套件分為三部分，請使用：

node --test --test-shard=1/3
node --test --test-shard=2/3
node --test --test-shard=3/3
copy

--test-skip-pattern#

一個正規表示式，設定測試執行器略過名稱符合指定模式的測試。詳情請參閱依名稱篩選測試的文件。

如果同時提供了 --test-name-pattern 和 --test-skip-pattern，測試必須同時滿足兩個要求才能被執行。

--test-timeout#

測試執行失敗前的等待毫秒數。如果未指定，子測試會繼承其父層的值。預設值為 Infinity。

--test-update-snapshots#

重新產生測試執行器用於快照測試的快照檔案。

--throw-deprecation#

針對棄用警告拋出錯誤。

--title=title#

啟動時設定 process.title。

--tls-cipher-list=list#

指定替代的預設 TLS 密碼清單。要求 Node.js 必須在編譯時支援 crypto（預設支援）。

--tls-keylog=file#

將 TLS 金鑰材料記錄到檔案。金鑰材料採用 NSS SSLKEYLOGFILE 格式，可由軟體（如 Wireshark）用來解密 TLS 流量。

--tls-max-v1.2#

將 tls.DEFAULT_MAX_VERSION 設定為 'TLSv1.2'。可用於停用對 TLSv1.3 的支援。

--tls-max-v1.3#

將預設 tls.DEFAULT_MAX_VERSION 設定為 'TLSv1.3'。可用於啟用對 TLSv1.3 的支援。

--tls-min-v1.0#

將預設 tls.DEFAULT_MIN_VERSION 設定為 'TLSv1'。用於與舊版 TLS 用戶端或伺服器相容。

--tls-min-v1.1#

將預設 tls.DEFAULT_MIN_VERSION 設定為 'TLSv1.1'。用於與舊版 TLS 用戶端或伺服器相容。

--tls-min-v1.2#

將預設 tls.DEFAULT_MIN_VERSION 設定為 'TLSv1.2'。這是 12.x 及更高版本的預設值，此選項僅保留以與舊版 Node.js 相容。

--tls-min-v1.3#

將預設 tls.DEFAULT_MIN_VERSION 設定為 'TLSv1.3'。可用於停用安全性較低的 TLSv1.2 支援。

--trace-deprecation#

為棄用警告列印堆疊追蹤。

--trace-env#

將當前 Node.js 執行個體中對環境變數的存取資訊列印至 stderr，包括：

• Node.js 在內部進行的環境變數讀取。
• 形式為 process.env.KEY = "SOME VALUE" 的寫入。
• 形式為 process.env.KEY 的讀取。
• 形式為 Object.defineProperty(process.env, 'KEY', {...}) 的定義。
• 形式為 Object.hasOwn(process.env, 'KEY')、process.env.hasOwnProperty('KEY') 或 'KEY' in process.env 的查詢。
• 形式為 delete process.env.KEY 的刪除。
• 形式為 ...process.env 或 Object.keys(process.env) 的枚舉。

僅會列印被存取的環境變數名稱，不會列印其值。

若要列印存取的堆疊追蹤，請使用 --trace-env-js-stack 和/或 --trace-env-native-stack。

--trace-env-js-stack#

在 --trace-env 的基礎上，額外列印該存取的 JavaScript 堆疊追蹤。

--trace-env-native-stack#

在 --trace-env 的基礎上，額外列印該存取的原生（native）堆疊追蹤。

--trace-event-categories#

當使用 --trace-events-enabled 啟用追蹤事件記錄時，應被追蹤的類別清單（以逗號分隔）。

--trace-event-file-pattern#

指定追蹤事件資料檔案路徑的樣板字串，支援 ${rotation} 和 ${pid}。

--trace-events-enabled#

啟用追蹤事件記錄資訊的收集。

--trace-exit#

每當執行環境被主動退出時（例如呼叫 process.exit()），列印堆疊追蹤。

--trace-require-module=mode#

列印關於使用 require() 載入 ECMAScript 模組的使用資訊。

當 mode 為 all 時，會列印所有使用情況。當 mode 為 no-node-modules 時，會排除來自 node_modules 資料夾的使用。

--trace-sigint#

在 SIGINT 時列印堆疊追蹤。

--trace-sync-io#

每當事件迴圈的第一圈之後偵測到同步 I/O 時，列印堆疊追蹤。

--trace-tls#

將 TLS 封包追蹤資訊列印至 stderr。這可用於除錯 TLS 連線問題。

--trace-uncaught#

為未捕獲的例外列印堆疊追蹤；通常只會列印與 Error 物件建立相關的堆疊追蹤，而此選項會讓 Node.js 也列印與拋出該值相關的堆疊追蹤（該值不一定是 Error 例項）。

啟用此選項可能會對垃圾回收行為產生負面影響。

--trace-warnings#

為處理序警告（包括棄用警告）列印堆疊追蹤。

--track-heap-objects#

追蹤用於堆積快照的堆積物件配置。

--unhandled-rejections=mode#

使用此旗標可變更當發生未處理的 rejection 時的行為。可選擇以下模式之一：

• throw：觸發 unhandledRejection。如果未設定此 hook，則將未處理的 rejection 作為未捕獲的例外引發。這是預設值。
• strict：將未處理的 rejection 作為未捕獲的例外引發。如果該例外被捕獲，則會觸發 unhandledRejection。
• warn：無論是否設定了 unhandledRejection hook，總是觸發警告，但不會列印棄用警告。
• warn-with-error-code：觸發 unhandledRejection。如果未設定此 hook，則觸發警告，並將處理序結束碼設為 1。
• none：關閉所有警告。

如果 rejection 發生在命令列進入點的 ES 模組靜態載入階段，它將總是作為未捕獲的例外引發。

--use-bundled-ca, --use-openssl-ca#

使用當前 Node.js 版本提供的內建 Mozilla CA 儲存庫，或使用 OpenSSL 預設的 CA 儲存庫。預設儲存庫可在編譯時選定。

Node.js 提供的內建 CA 儲存庫是發布時固定的 Mozilla CA 儲存庫快照，在所有支援的平台上皆相同。

使用 OpenSSL 儲存庫允許對儲存庫進行外部修改。對於大多數 Linux 和 BSD 發行版，此儲存庫由發行版維護者和系統管理員負責維護。OpenSSL CA 儲存庫的位置取決於 OpenSSL 函式庫的設定，但這可以在執行階段透過環境變數更改。

請參閱 SSL_CERT_DIR 和 SSL_CERT_FILE。

--use-env-proxy#

啟用後，Node.js 會在啟動期間解析 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 環境變數，並透過指定的代理伺服器傳輸請求。

這等同於設定 NODE_USE_ENV_PROXY=1 環境變數。當兩者皆設定時，--use-env-proxy 優先。

--use-largepages=mode#

在啟動時將 Node.js 靜態程式碼重新映射至大記憶體頁面（large memory pages）。如果目標系統支援，這將使 Node.js 靜態程式碼移至 2 MiB 頁面，而非 4 KiB 頁面。

以下是 mode 的有效值：

• off：不嘗試映射。這是預設值。
• on：如果作業系統支援，將嘗試映射。映射失敗將被忽略，並向標準錯誤列印訊息。
• silent：如果作業系統支援，將嘗試映射。映射失敗將被忽略且不進行回報。

--use-system-ca#

Node.js 會使用系統儲存庫中受信任的 CA 憑證，並結合 --use-bundled-ca 選項與 NODE_EXTRA_CA_CERTS 環境變數。在非 Windows 和 macOS 的平台上，這會從 OpenSSL 受信任的目錄和檔案載入憑證，類似於 --use-openssl-ca，差異在於它會在首次載入後快取憑證。

在 Windows 和 macOS 上，憑證信任原則類似於 Chromium 對本地受信任憑證的原則，但存在一些差異：

在 macOS 上，會遵守以下設定：

• 預設與系統金鑰圈（Default and System Keychains）
  • 信任
    • 任何「使用此憑證時」旗標設為「永遠信任」（Always Trust）的憑證，或
    • 任何「安全通訊端層 (SSL)」旗標設為「永遠信任」的憑證。
  • 憑證也必須是有效的，且「X.509 基本原則」設為「永遠信任」。

在 Windows 上，會遵守以下設定：

• 本機電腦（透過 certlm.msc 存取）
  • 信任
    • 受信任的根憑證授權單位（Trusted Root Certification Authorities）
    • 受信任的人員（Trusted People）
    • 企業信任 -> 企業 -> 受信任的根憑證授權單位
    • 企業信任 -> 企業 -> 受信任的人員
    • 企業信任 -> 群組原則 -> 受信任的根憑證授權單位
    • 企業信任 -> 群組原則 -> 受信任的人員
• 目前使用者（透過 certmgr.msc 存取）
  • 信任
    • 受信任的根憑證授權單位（Trusted Root Certification Authorities）
    • 企業信任 -> 群組原則 -> 受信任的根憑證授權單位

在 Windows 和 macOS 上，Node.js 在使用憑證前會檢查使用者對受信任憑證的設定，確保其未禁止用於 TLS 伺服器驗證。

Node.js 目前不支援根據系統設定來撤銷或不信任來自其他來源的憑證。

在其他系統上，Node.js 從 Node.js 所連結的 OpenSSL 版本所遵循的預設憑證檔案（通常為 /etc/ssl/cert.pem）和預設憑證目錄（通常為 /etc/ssl/certs）載入憑證。這通常適用於主流 Linux 發行版和其他類 Unix 系統。如果設定了覆蓋 OpenSSL 環境變數（通常為 SSL_CERT_FILE 和 SSL_CERT_DIR，取決於 Node.js 連結的 OpenSSL 設定），則會使用指定的路徑來載入憑證。如果使用者因故無法使用 Node.js 連結的 OpenSSL 版本所慣用的路徑，可以使用這些環境變數作為替代方案。

--v8-options#

列印 V8 命令列選項。

--v8-pool-size=num#

設定用於分配背景作業的 V8 執行緒池大小。

如果設為 0，Node.js 將根據平行處理能力的估算值選擇合適的執行緒池大小。

平行處理能力是指在特定機器上可同時進行的計算數。通常與 CPU 數量相同，但在虛擬機器（VM）或容器等環境中可能會有所差異。

-v, --version#

列印 node 版本。

--watch#

以監控模式啟動 Node.js。在監控模式下，監控的檔案若有變更，會導致 Node.js 處理序重新啟動。預設情況下，監控模式會監控進入點及其所有 require 或 import 的模組。請使用 --watch-path 指定要監控的路徑。

此旗標不能與 --check、--eval、--interactive 或 REPL 同時使用。

注意：--watch 旗標需要檔案路徑作為引數，且與 --run 或內聯腳本輸入不相容，因為 --run 具有優先權並會忽略監控模式。若未提供檔案，Node.js 將以狀態碼 9 退出。

node --watch index.js
copy

--watch-kill-signal#

自訂在監控模式重新啟動時傳送給處理序的訊號。

node --watch --watch-kill-signal SIGINT test.js
copy

--watch-path#

以監控模式啟動 Node.js 並指定要監控的路徑。在監控模式下，監控路徑的變更會導致 Node.js 處理序重新啟動。這將關閉對 require 或 import 模組的監控，即使與 --watch 同時使用亦同。

此旗標不能與 --check、--eval、--interactive、--test 或 REPL 同時使用。

注意：使用 --watch-path 會隱含啟用 --watch，後者需要檔案路徑，且與 --run 不相容，因為 --run 具有優先權並會忽略監控模式。

node --watch-path=./src --watch-path=./tests index.js
copy

此選項僅在 macOS 和 Windows 上支援。若在不支援的平台上使用此選項，將會拋出 ERR_FEATURE_UNAVAILABLE_ON_PLATFORM 例外。

--watch-preserve-output#

停用監控模式重新啟動處理序時的控制台清除行為。

node --watch --watch-preserve-output test.js
copy

--zero-fill-buffers#

自動將所有新配置的 Buffer 例項填入零。

環境變數#

FORCE_COLOR=[1, 2, 3]#

FORCE_COLOR 環境變數用於啟用 ANSI 彩色輸出。其值可以是：

• 1、true 或空字串 '' 代表支援 16 色，
• 2 代表支援 256 色，或
• 3 代表支援 1600 萬色。

當使用 FORCE_COLOR 並設定為支援的值時，NO_COLOR 和 NODE_DISABLE_COLORS 環境變數將被忽略。

任何其他值都會導致彩色輸出被停用。

NODE_COMPILE_CACHE=dir#

為 Node.js 執行個體啟用模組編譯快取。詳情請參閱模組編譯快取文件。

NODE_COMPILE_CACHE_PORTABLE=1#

設定為 1 時，只要相對於快取目錄的模組配置保持不變，模組編譯快取便可在不同目錄位置重複使用。

NODE_DEBUG=module[,…]#

應列印除錯資訊的核心模組清單（以逗號分隔）。

NODE_DEBUG_NATIVE=module[,…]#

應列印除錯資訊的核心 C++ 模組清單（以逗號分隔）。

NODE_DISABLE_COLORS=1#

設定時，REPL 將不會使用顏色。

NODE_DISABLE_COMPILE_CACHE=1#

停用 Node.js 執行個體的模組編譯快取。詳情請參閱模組編譯快取文件。

NODE_EXTRA_CA_CERTS=file#

設定時，將使用 file 中的額外憑證來擴充廣為人知的「根」CA（如 VeriSign）。檔案應包含一個或多個 PEM 格式的受信任憑證。如果檔案遺失或格式錯誤，會透過 process.emitWarning() 發出警告（僅一次），但除此之外的所有錯誤都會被忽略。

當為 TLS 或 HTTPS 用戶端/伺服器明確指定 ca 選項屬性時，無論是廣為人知的 CA 還是額外的憑證都不會被使用。

當 node 以 setuid root 執行或設定了 Linux 檔案權限時，此環境變數將被忽略。

NODE_EXTRA_CA_CERTS 環境變數僅在 Node.js 處理序首次啟動時讀取。在執行階段使用 process.env.NODE_EXTRA_CA_CERTS 更改其值對當前處理序無效。

NODE_ICU_DATA=file#

ICU (Intl 物件) 資料的資料路徑。當使用 small-icu 支援編譯時，此路徑將擴充內建資料。

NODE_NO_WARNINGS=1#

設定為 1 時，處理序警告將被關閉。

NODE_OPTIONS=options...#

以空格分隔的命令列選項清單。options... 會在命令列選項之前進行解譯，因此命令列選項會覆蓋或累加 options... 中的任何設定。如果使用環境中不允許的選項（例如 -p 或腳本檔案），Node.js 將以錯誤退出。

如果選項值包含空格，可以使用雙引號進行跳脫。

NODE_OPTIONS='--require "./my path/file.js"'
copy

傳遞為命令列選項的單例旗標將覆蓋傳遞至 NODE_OPTIONS 的相同旗標。

# The inspector will be available on port 5555
NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555
copy

可多次傳遞的旗標，將被視為先處理 NODE_OPTIONS 中的執行個體，隨後再處理命令列中的執行個體。

NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
# is equivalent to:
node --require "./a.js" --require "./b.js"
copy

下表列出了允許的 Node.js 選項。如果選項同時支援 --XX 和 --no-XX 變體，兩者皆受支援，但下表僅列出一種。

• --allow-addons
• --allow-child-process
• --allow-fs-read
• --allow-fs-write
• --allow-inspector
• --allow-net
• --allow-wasi
• --allow-worker
• --conditions, -C
• --cpu-prof-dir
• --cpu-prof-interval
• --cpu-prof-name
• --cpu-prof
• --diagnostic-dir
• --disable-proto
• --disable-sigusr1
• --disable-warning
• --disable-wasm-trap-handler
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --entry-url
• --experimental-abortcontroller
• --experimental-addon-modules
• --experimental-detect-module
• --experimental-eventsource
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-print-required-tla
• --experimental-quic
• --experimental-require-module
• --experimental-shadow-realm
• --experimental-specifier-resolution
• --experimental-stream-iter
• --experimental-test-isolation
• --experimental-top-level-await
• --experimental-vm-modules
• --experimental-wasi-unstable-preview1
• --force-context-aware
• --force-fips
• --force-node-api-uncaught-exceptions-policy
• --frozen-intrinsics
• --heap-prof-dir
• --heap-prof-interval
• --heap-prof-name
• --heap-prof
• --heapsnapshot-near-heap-limit
• --heapsnapshot-signal
• --http-parser
• --icu-data-dir
• --import
• --input-type
• --insecure-http-parser
• --inspect-brk
• --inspect-port, --debug-port
• --inspect-publish-uid
• --inspect-wait
• --inspect
• --localstorage-file
• --max-http-header-size
• --max-old-space-size-percentage
• --napi-modules
• --network-family-autoselection-attempt-timeout
• --no-addons
• --no-async-context-frame
• --no-deprecation
• --no-experimental-global-navigator
• --no-experimental-repl-await
• --no-experimental-sqlite
• --no-experimental-strip-types
• --no-experimental-websocket
• --no-experimental-webstorage
• --no-extra-info-on-fatal-exception
• --no-force-async-hooks-checks
• --no-global-search-paths
• --no-network-family-autoselection
• --no-strip-types
• --no-warnings
• --no-webstorage
• --node-memory-debug
• --openssl-config
• --openssl-legacy-provider
• --openssl-shared-config
• --pending-deprecation
• --permission-audit
• --permission
• --preserve-symlinks-main
• --preserve-symlinks
• --prof-process
• --redirect-warnings
• --report-compact
• --report-dir, --report-directory
• --report-exclude-env
• --report-exclude-network
• --report-filename
• --report-on-fatalerror
• --report-on-signal
• --report-signal
• --report-uncaught-exception
• --require-module
• --require, -r
• --secure-heap-min
• --secure-heap
• --snapshot-blob
• --test-coverage-branches
• --test-coverage-exclude
• --test-coverage-functions
• --test-coverage-include
• --test-coverage-lines
• --test-global-setup
• --test-isolation
• --test-name-pattern
• --test-only
• --test-reporter-destination
• --test-reporter
• --test-rerun-failures
• --test-shard
• --test-skip-pattern
• --throw-deprecation
• --title
• --tls-cipher-list
• --tls-keylog
• --tls-max-v1.2
• --tls-max-v1.3
• --tls-min-v1.0
• --tls-min-v1.1
• --tls-min-v1.2
• --tls-min-v1.3
• --trace-deprecation
• --trace-env-js-stack
• --trace-env-native-stack
• --trace-env
• --trace-event-categories
• --trace-event-file-pattern
• --trace-events-enabled
• --trace-exit
• --trace-require-module
• --trace-sigint
• --trace-sync-io
• --trace-tls
• --trace-uncaught
• --trace-warnings
• --track-heap-objects
• --unhandled-rejections
• --use-bundled-ca
• --use-env-proxy
• --use-largepages
• --use-openssl-ca
• --use-system-ca
• --v8-pool-size
• --watch-kill-signal
• --watch-path
• --watch-preserve-output
• --watch
• --zero-fill-buffers

允許的 V8 選項有：

• --abort-on-uncaught-exception
• --disallow-code-generation-from-strings
• --enable-etw-stack-walking
• --expose-gc
• --interpreted-frames-native-stack
• --jitless
• --max-heap-size
• --max-old-space-size
• --max-semi-space-size
• --perf-basic-prof-only-functions
• --perf-basic-prof
• --perf-prof-unwinding-info
• --perf-prof
• --stack-trace-limit

--perf-basic-prof-only-functions、--perf-basic-prof、--perf-prof-unwinding-info 和 --perf-prof 僅在 Linux 上可用。

--enable-etw-stack-walking 僅在 Windows 上可用。

NODE_PATH=path[:…]#

以 ':' 分隔的目錄清單，會加在模組搜尋路徑的前面。

在 Windows 上，這是以 ';' 分隔的清單。

NODE_PENDING_DEPRECATION=1#

設定為 1 時，發出待處理的棄用警告。

待處理棄用警告通常與執行階段棄用警告相同，顯著的例外是它們預設是關閉的，除非設定了 --pending-deprecation 命令列旗標或 NODE_PENDING_DEPRECATION=1 環境變數。待處理棄用警告用於提供一種選擇性的「早期預警」機制，開發人員可以利用該機制來偵測棄用的 API 使用情況。

NODE_PENDING_PIPE_INSTANCES=instances#

設定當管線伺服器等待連線時，待處理的管線例項控制代碼數量。此設定僅適用於 Windows。

NODE_PRESERVE_SYMLINKS=1#

設定為 1 時，指示模組載入器在解析和快取模組時保留符號連結。

NODE_REDIRECT_WARNINGS=file#

設定時，處理序警告將輸出至指定的檔案，而非列印至 stderr。若檔案不存在則會建立，若存在則會附加內容。如果嘗試將警告寫入檔案時發生錯誤，警告將改為寫入 stderr。這等同於使用 --redirect-warnings=file 命令列旗標。

NODE_REPL_EXTERNAL_MODULE=file#

將替代內建 REPL 載入的 Node.js 模組路徑。將此值覆蓋為空字串 ('') 將會使用內建的 REPL。

NODE_REPL_HISTORY=file#

用於儲存永久 REPL 歷史記錄的檔案路徑。預設路徑為 ~/.node_repl_history，可被此變數覆蓋。將值設為空字串 ('' 或 ' ') 可停用永久 REPL 歷史記錄。

NODE_SKIP_PLATFORM_CHECK=value#

如果 value 等於 '1'，Node.js 啟動期間將跳過對受支援平台的檢查。Node.js 可能無法正確執行。任何在不支援平台上遇到的問題將不會被修復。

NODE_TEST_CONTEXT=value#

如果 value 等於 'child'，測試報告器選項將被覆蓋，且測試輸出將以 TAP 格式發送至 stdout。如果提供任何其他值，Node.js 不保證使用的報告器格式及其穩定性。

NODE_TLS_REJECT_UNAUTHORIZED=value#

如果 value 等於 '0'，將停用 TLS 連線的憑證驗證。這會使 TLS 及擴充的 HTTPS 變得不安全。強烈建議不要使用此環境變數。

NODE_USE_ENV_PROXY=1#

啟用後，Node.js 會在啟動期間解析 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 環境變數，並透過指定的代理伺服器傳輸請求。

這也可以透過 --use-env-proxy 命令列旗標啟用。當兩者皆設定時，--use-env-proxy 優先。

NODE_USE_SYSTEM_CA=1#

Node.js 使用系統儲存庫中受信任的 CA 憑證，並結合 --use-bundled-ca 選項與 NODE_EXTRA_CA_CERTS 環境變數。

這也可以透過 --use-system-ca 命令列旗標啟用。當兩者皆設定時，--use-system-ca 優先。

NODE_V8_COVERAGE=dir#

設定時，Node.js 將開始輸出 V8 JavaScript 程式碼覆蓋率與 Source Map 資料至作為引數提供的目錄（覆蓋率資訊會以 JSON 格式寫入，檔案名稱以 coverage 為字首）。

NODE_V8_COVERAGE 會自動傳播至子處理序，使檢測（instrument）呼叫 child_process.spawn() 系列函式的應用程式變得更加容易。可將 NODE_V8_COVERAGE 設為空字串以防止傳播。

覆蓋率輸出#

覆蓋率以頂層鍵 result 下的一組 ScriptCoverage 物件陣列輸出。

{
  "result": [
    {
      "scriptId": "67",
      "url": "internal/tty.js",
      "functions": []
    }
  ]
}
copy

Source map 快取#

如果找到，source map 資料會附加至 JSON 覆蓋率物件的頂層鍵 source-map-cache 中。

source-map-cache 是一個物件，其鍵代表提取 source map 的檔案，值包含原始 source-map URL (鍵 url)、解析後的 Source Map v3 資訊 (鍵 data) 以及原始檔案的行長度 (鍵 lineLengths)。

{
  "result": [
    {
      "scriptId": "68",
      "url": "file:///absolute/path/to/source.js",
      "functions": []
    }
  ],
  "source-map-cache": {
    "file:///absolute/path/to/source.js": {
      "url": "./path-to-map.json",
      "data": {
        "version": 3,
        "sources": [
          "file:///absolute/path/to/original.js"
        ],
        "names": [
          "Foo",
          "console",
          "info"
        ],
        "mappings": "MAAMA,IACJC,YAAaC",
        "sourceRoot": "./"
      },
      "lineLengths": [
        13,
        62,
        38,
        27
      ]
    }
  }
}
copy

NO_COLOR=<any>#

NO_COLOR 是 NODE_DISABLE_COLORS 的別名。此環境變數的值可任意設定。

OPENSSL_CONF=file#

於啟動時載入 OpenSSL 設定檔。除了其他用途外，若 Node.js 在編譯時加上了 ./configure --openssl-fips，這可用於啟用 FIPS 相容的加密功能。

如果使用了 --openssl-config 命令列選項，則該環境變數會被忽略。

SSL_CERT_DIR=dir#

如果啟用了 --use-openssl-ca，或在 macOS 和 Windows 以外的平台上啟用了 --use-system-ca，此變數將覆蓋並設定 OpenSSL 存放受信任憑證的目錄。

請注意，除非明確設定了子環境，否則此環境變數將被任何子處理序繼承；如果它們使用 OpenSSL，可能會導致它們信任與 node 相同的 CA。

SSL_CERT_FILE=file#

如果啟用了 --use-openssl-ca，或在 macOS 和 Windows 以外的平台上啟用了 --use-system-ca，此變數將覆蓋並設定 OpenSSL 存放受信任憑證的檔案。

請注意，除非明確設定了子環境，否則此環境變數將被任何子處理序繼承；如果它們使用 OpenSSL，可能會導致它們信任與 node 相同的 CA。

TZ#

TZ 環境變數用於指定時區設定。

雖然 Node.js 並不支援在其他環境中處理 TZ 的各種方式，但它支援基礎的 時區 ID（如 'Etc/UTC'、'Europe/Paris' 或 'America/New_York'）。它可能支援一些其他的縮寫或別名，但不建議使用且無法保證其運作。

$ TZ=Europe/Dublin node -pe "new Date().toString()"
Wed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time)
copy

UV_THREADPOOL_SIZE=size#

將 libuv 執行緒池中使用的執行緒數量設定為 size。

Node.js 盡可能使用非同步系統 API，但在沒有此類 API 的情況下，libuv 的執行緒池會用於基於同步系統 API 建立非同步 node API。使用執行緒池的 Node.js API 包括：

• 所有 fs API（檔案監控 API 及明確同步的 API 除外）
• 非同步 crypto API，如 crypto.pbkdf2()、crypto.scrypt()、crypto.randomBytes()、crypto.randomFill()、crypto.generateKeyPair()
• dns.lookup()
• 所有 zlib API（明確同步的 API 除外）

由於 libuv 的執行緒池大小固定，這意味著如果這些 API 中的任何一個因故耗時過長，其他（看似無關）在 libuv 執行緒池中執行的 API 將會體驗到效能下降。為了減輕此問題，一個潛在的解決方案是將 'UV_THREADPOOL_SIZE' 環境變數設定為大於 4（目前預設值）的值來增加 libuv 執行緒池大小。然而，在處理序內部使用 process.env.UV_THREADPOOL_SIZE=size 設定並不保證有效，因為執行緒池可能早已在執行階段初始化過程中建立完畢，遠早於使用者程式碼執行前。更多資訊請參閱 libuv 執行緒池文件。

有用的 V8 選項#

V8 擁有其自身的 CLI 選項集。任何提供給 node 的 V8 CLI 選項都將傳遞給 V8 處理。V8 選項不保證穩定性。V8 團隊本身不認為它們是其正式 API 的一部分，並保留隨時更改的權利。同樣地，它們也不在 Node.js 的穩定性保證範圍內。許多 V8 選項僅對 V8 開發人員有價值。儘管如此，仍有一小部分 V8 選項適用於 Node.js，並在此處記錄如下：

--abort-on-uncaught-exception#

--disallow-code-generation-from-strings#

--enable-etw-stack-walking#

--expose-gc#

--harmony-shadow-realm#

--heap-snapshot-on-oom#

--interpreted-frames-native-stack#

--jitless#

--max-heap-size#

指定處理序的最大堆積大小（以 MB 為單位）。

此選項通常用於限制處理序 JavaScript 堆積可使用的記憶體總量。

--max-old-space-size=SIZE (以 MiB 為單位)#

設定 V8 老舊記憶體區段（old memory section）的最大記憶體大小。隨著記憶體消耗接近極限，V8 將花費更多時間進行垃圾回收，以嘗試釋放未使用的記憶體。

在擁有 2 GiB 記憶體的機器上，考慮將此值設為 1536 (1.5 GiB) 以保留一些記憶體供其他用途使用，並避免發生記憶體置換（swapping）。

node --max-old-space-size=1536 index.js
copy

--max-semi-space-size=SIZE (以 MiB 為單位)#

設定 V8 清除垃圾回收器（scavenge garbage collector）的 半空間（semi-space）最大大小（以 MiB 為單位）。增加半空間的最大大小可能會提高 Node.js 的處理效能，但代價是更高的記憶體消耗。

由於 V8 堆積的年輕世代（young generation）大小是半空間大小的三倍（請參閱 V8 中的 YoungGenerationSizeFromSemiSpaceSize），因此半空間每增加 1 MiB，將影響三個個別半空間中的每一個，並導致堆積大小增加 3 MiB。效能提升取決於您的工作負載（請參閱 #42511）。

預設值取決於記憶體限制。例如，在記憶體限制為 512 MiB 的 64 位元系統上，半空間的最大大小預設為 1 MiB。對於記憶體限制在 2GiB 或以下的情況，在 64 位元系統上，半空間的最大預設大小將小於 16 MiB。

為了獲得應用程式的最佳配置，您應該在為應用程式執行基準測試時嘗試不同的 max-semi-space-size 值。

例如，在 64 位元系統上進行基準測試：

for MiB in 16 32 64 128; do
    node --max-semi-space-size=$MiB index.js
done
copy

--perf-basic-prof#

--perf-basic-prof-only-functions#

--perf-prof#

--perf-prof-unwinding-info#

--prof#

--security-revert#

--stack-trace-limit=limit#

錯誤堆疊追蹤中要收集的最大堆疊影格數。設定為 0 可停用堆疊追蹤收集。預設值為 10。

node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
copy