nodejs-docs

Node.js API (nodejs.org)

濃縮 Node.js API 文件為模型容易出錯的重點：不安全的預設值、陷阱、棄用功能。每個陳述以它本身的 nodejs.org 頁面結尾。

涵蓋的版本

閱讀的文件版本為 v26.13.0。許多專案執行的是 v24 LTS 系列，因此參考資料會標記哪些是較新的內容：「在 v25.x 中新增」或「在 v26.x 中新增」表示在 v24 上遺失，除非提供了反向移植版本。https://nodejs.org/docs/latest/api/

在依賴標記的功能之前，請檢查 process.version 或進行功能偵測（process.features.typescript、process.features.require_module）。https://nodejs.org/docs/latest/api/process.html

閱讀下列規則，然後開啟對應的參考檔案。

最高價值的規則

• 在開啟檔案之前，絕對不要呼叫 access()、exists() 或 stat()：直接開啟並處理 ENOENT / EEXIST（使用旗標 'wx' 進行獨佔建立）。https://nodejs.org/docs/latest/api/fs.html#fsaccesspath-mode-callback
• 明確關閉每個 FileHandle，理想情況下使用 await using。交由 GC 處理的 FileHandle 會擲出錯誤。https://nodejs.org/docs/latest/api/deprecations.html#DEP0137
• 使用 pipeline() 組合串流，而不是 .pipe() 鏈，並注意 write() 回傳 false 的情況。https://nodejs.org/docs/latest/api/stream.html#readablepipedestination-options
• 為每個事件發射器、串流、socket、請求和子程序添加 'error' 監聽器：未處理的 'error' 會使程序崩潰。https://nodejs.org/docs/latest/api/events.html#error-events
• 根據 err.code 進行分支，絕對不要根據 err.message。https://nodejs.org/docs/latest/api/errors.html#errorcode
• 設定 process.exitCode 而不是呼叫 process.exit()，後者可能會截斷 stdout。https://nodejs.org/docs/latest/api/process.html#processexitcode
• 在 'uncaughtException' 之後絕不恢復工作：同步清理並退出。https://nodejs.org/docs/latest/api/process.html#warning-using-uncaughtexception-correctly
• 偏好使用 queueMicrotask() 而非傳統的 process.nextTick()。https://nodejs.org/docs/latest/api/process.html#when-to-use-queuemicrotask-vs-processnexttick
• 使用 execFile()/spawn() 時不啟動 shell。傳遞 args 並設定 shell: true 不會對其進行跳脫處理。https://nodejs.org/docs/latest/api/deprecations.html#DEP0190
• 消耗每個 HTTP 用戶端回應主體（至少呼叫 res.resume()），附加 req.on('error')，並記住 timeout 不會中止：請呼叫 destroy()。https://nodejs.org/docs/latest/api/http.html#class-httpclientrequest
• 在沒有反向代理的伺服器上，保持 headersTimeout 非零。https://nodejs.org/docs/latest/api/http.html#serverheaderstimeout
• 使用 WHATWG URL。url.parse() 已被棄用，且不會為其發佈 CVE。https://nodejs.org/docs/latest/api/deprecations.html#DEP0169
• path.isAbsolute() 並不能阻止路徑遍歷，且 path.normalize() 是詞法層面的，可能會改變系統解析路徑的方式：請解析，然後檢查結果是否保持在根目錄內。https://nodejs.org/docs/latest/api/path.html#pathisabsolutepath
• 預設使用 Buffer.alloc()，對於視圖使用 Buffer.subarray()，且絕不使用 new Buffer()。https://nodejs.org/docs/latest/api/deprecations.html#DEP0005
• 使用 crypto.timingSafeEqual() 比較等長緩衝區中的秘密。https://nodejs.org/docs/latest/api/crypto.html#cryptotimingsafeequala-b
• 在解壓縮不受信任的資料時，為 zlib 設定 maxOutputLength（預設為 buffer.kMaxLength）。https://nodejs.org/docs/latest/api/zlib.html#class-options
• 在 package.json 中設定 "type"，並在 "exports" 條件中將 "default" 放在最後。https://nodejs.org/docs/latest/api/packages.html#determining-module-system
• require() ESM 適用於同步圖。圖中任何位置的頂層 await 都會擲出 ERR_REQUIRE_ASYNC_MODULE。https://nodejs.org/docs/latest/api/modules.html#loading-ecmascript-modules-using-require
• 類型剝離會執行 .ts 檔案而不進行類型檢查：沒有 enum、明確的 .ts 副檔名、import type，且沒有 tsconfig 的 paths。自 v25.2.0 起穩定（反向移植至 v24.12.0），可使用 process.features.typescript 偵測。https://nodejs.org/docs/latest/api/typescript.html#typescript-features , https://nodejs.org/docs/latest/api/typescript.html#type-stripping
• 使用 module.registerHooks() 註冊模組鉤子。module.register() 在 v26 中已被棄用。https://nodejs.org/docs/latest/api/deprecations.html#DEP0205
• 偏好使用 AsyncLocalStorage 而非 async_hooks.createHook()。https://nodejs.org/docs/latest/api/async_hooks.html
• 在 node:test 中使用 await t.test() 進行子測試。https://nodejs.org/docs/latest/api/test.html#subtests
• node:vm 和 WASI 不是沙箱，權限模型也不是執行不受信任程式碼的安全方式：絕對不要為此目的使用它們。https://nodejs.org/docs/latest/api/permissions.html#process-based-permissions
• 使用 using / await using 處置伺服器、串流和子程序，而不是使用 AbortSignal。保留訊號用於取消和逾時。https://nodejs.org/docs/latest/api/deprecations.html#DEP0209
• dns.lookup() 是執行緒池上的 getaddrinfo，不是 DNS 查詢。https://nodejs.org/docs/latest/api/dns.html#implementation-considerations
• 使用 os.availableParallelism() 調整池的大小。https://nodejs.org/docs/latest/api/os.html#osavailableparallelism
• node:sqlite：繫結參數，絕不內插到 SQL 中。https://nodejs.org/docs/latest/api/sqlite.html#binding-parameters
• 使用 --pending-deprecation 執行 CI，以揭露棄用功能。https://nodejs.org/docs/latest/api/deprecations.html

參考檔案

檔案	閱讀目的
references/fs.md	TOCTOU、FileHandle、readFile/writeFile、rm、glob、fs.watch
references/path-and-url.md	path、遍歷、file: URL、WHATWG URL、querystring
references/crypto.md	KeyObject、timingSafeEqual、雜湊、pbkdf2、scrypt、弱演算法
references/ciphers-and-webcrypto.md	AEAD 標籤、GCM、金鑰包裝、subtle、金鑰格式
references/streams.md	pipeline、背壓、highWaterMark、finished、實作串流
references/web-streams-and-stream-iter.md	Web Streams、node:stream/iter
references/buffer.md	alloc 與 allocUnsafe、編碼、Blob
references/zlib.md	解壓縮炸彈、flush、Zstd
references/http-client.md	http.request、代理、keep-alive、代理伺服器
references/http-server.md	逾時、優雅關機、HTTPS 伺服器
references/net-dns-dgram.md	TCP、BlockList、dns.lookup 與 resolve、UDP
references/tls.md	SNI、密碼套件、CA 儲存庫、session resumption
references/http2.md	安全伺服器、allowHTTP1、強化
references/process.md	退出碼、訊號、uncaughtException、拒絕
references/cli-and-env-files.md	NODE_OPTIONS、--env-file、--watch
references/permissions.md	--permission、已知差距
references/errors.md	error.code、cause、錯誤碼
references/events-and-timers.md	captureRejections、events.once、EventTarget、計時器
references/async-context-and-diagnostics-channel.md	AsyncLocalStorage、diagnostics_channel
references/util-and-console.md	util、Console
references/os-tty-readline-repl.md	os、tty、readline、REPL
references/test-runner.md	子測試、隔離、涵蓋率、報告器、模擬
references/assert-and-bench.md	node:assert/strict、深度相等、node:bench
references/esm-and-commonjs.md	"type"、JSON 匯入、import.meta、require(esm)
references/packages.md	"exports"、"imports"、條件、雙重套件
references/typescript-and-module-hooks.md	類型剝離、registerHooks、findPackageJSON
references/globals.md	fetch、AbortSignal、全域變數
references/child-process.md	execFile 與 exec、maxBuffer、IPC
references/worker-threads-and-cluster.md	池、傳輸列表、叢集
references/vm-wasi-vfs.md	vm、WASI、node:vfs
references/performance-and-profiling.md	perf_hooks、堆積快照
references/debugging-and-reports.md	檢查器、診斷報告
references/sqlite.md	Database、預設值、繫結、型別轉換
references/sea-and-native.md	SEA、Node-API 規則、node:ffi
references/deprecations.md	DEP 代碼、已移除的 API、codemods

已讀取的頁面、版本和擷取日期列於 SOURCES.md。