除錯 Node.js
本指南將幫助你開始除錯你的 Node.js 應用和指令碼。
啟用 Inspector
當使用 --inspect 開關啟動時，Node.js 程序會監聽除錯客戶端。預設情況下，它會監聽主機和埠 127.0.0.1:9229。每個程序也會被分配一個唯一的 UUID。
Inspector 客戶端必須知道並指定主機地址、埠和 UUID 才能連線。一個完整的 URL 看起來會像這樣 ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e。
如果 Node.js 收到一個 SIGUSR1 訊號，它也會開始監聽除錯訊息。（SIGUSR1 在 Windows 上不可用。）在 Node.js 7 及更早版本中，這會啟用舊版的偵錯程式 API。在 Node.js 8 及更高版本中，它會啟用 Inspector API。
安全影響
由於偵錯程式可以完全訪問 Node.js 執行環境，能夠連線到此埠的惡意行為者可能能夠代表 Node.js 程序執行任意程式碼。瞭解在公共和私有網路上暴露偵錯程式埠的安全影響非常重要。
公開暴露除錯埠是不安全的
如果偵錯程式繫結到公共 IP 地址或 0.0.0.0，任何能夠訪問您 IP 地址的客戶端都將能夠無限制地連線到偵錯程式，並能夠執行任意程式碼。
預設情況下，node --inspect 繫結到 127.0.0.1。如果您打算允許外部連線到偵錯程式，您需要明確提供一個公共 IP 地址或 0.0.0.0 等。這樣做可能會使您面臨潛在的重大安全威脅。我們建議您確保有適當的防火牆和訪問控制措施，以防止安全暴露。
請參閱“啟用遠端除錯場景”部分，瞭解如何安全地允許遠端偵錯程式客戶端連線的一些建議。
本地應用程式可以完全訪問 inspector
即使您將 inspector 埠繫結到 127.0.0.1（預設），在您的機器上本地執行的任何應用程式都將擁有無限制的訪問許可權。這是為了方便本地偵錯程式能夠輕鬆地附加而設計的。
瀏覽器、WebSocket 和同源策略
在 Web 瀏覽器中開啟的網站可以在瀏覽器安全模型下發出 WebSocket 和 HTTP 請求。需要進行初始 HTTP 連線以獲取唯一的偵錯程式會話 ID。同源策略阻止網站進行此 HTTP 連線。為了增加對DNS 重繫結攻擊的安全性，Node.js 會驗證連線的“Host”頭是否精確指定了 IP 地址或 localhost。
這些安全策略不允許透過指定主機名連線到遠端除錯伺服器。您可以透過指定 IP 地址或使用 ssh 隧道（如下所述）來繞過此限制。
Inspector 客戶端
一個最小的 CLI 偵錯程式可透過 node inspect myscript.js 使用。一些商業和開源工具也可以連線到 Node.js Inspector。
Chrome DevTools 55+、Microsoft Edge
- 選項 1：在基於 Chromium 的瀏覽器中開啟
chrome://inspect或在 Edge 中開啟edge://inspect。點選“配置”按鈕，並確保您的目標主機和埠已列出。 - 選項 2：從
/json/list的輸出（見上文）或 --inspect 提示文字中複製devtoolsFrontendUrl，並貼上到 Chrome 中。
更多資訊請參見 https://github.com/ChromeDevTools/devtools-frontend 和 https://www.microsoftedgeinsider.com。
Visual Studio Code 1.10+
- 在“除錯”面板中，單擊設定圖示以開啟
.vscode/launch.json。選擇“Node.js”進行初始設定。
更多資訊請參見 https://github.com/microsoft/vscode。
Visual Studio 2017+
- 從選單中選擇“除錯 > 開始除錯”或按 F5。
- 詳細說明.
JetBrains WebStorm 和其他 JetBrains IDE
- 建立一個新的 Node.js 除錯配置並點選“除錯”。對於 Node.js 7+，預設會使用
--inspect。要停用，請在 IDE 登錄檔中取消選中js.debugger.node.use.inspect。要了解更多關於在 WebStorm 和其他 JetBrains IDE 中執行和除錯 Node.js 的資訊，請檢視 WebStorm 線上幫助。
chrome-remote-interface
- 用於簡化與 Inspector 協議 端點連線的庫。
更多資訊請參見 https://github.com/cyrus-and/chrome-remote-interface。
Gitpod
- 從
Debug檢視啟動一個 Node.js 除錯配置或按F5。詳細說明
更多資訊請參見 https://www.gitpod.io。
帶有 Eclipse Wild Web Developer 擴充套件的 Eclipse IDE
- 從 .js 檔案中，選擇“除錯方式... > Node 程式”，或者
- 建立一個除錯配置以將偵錯程式附加到正在執行的 Node.js 應用程式（已使用
--inspect啟動）。
更多資訊請參見 https://eclipse.org/eclipseide。
命令列選項
下表列出了各種執行時標誌對除錯的影響
| 標誌 | 含義 |
|---|---|
| --inspect | 啟用 inspector 代理；在預設地址和埠（127.0.0.1:9229）上監聽 |
| --inspect=[host:port] | 啟用 inspector 代理；繫結到地址或主機名 host（預設：127.0.0.1）；在埠 port 上監聽（預設：9229） |
| --inspect-brk | 啟用 inspector 代理；在預設地址和埠（127.0.0.1:9229）上監聽；在使用者程式碼開始前中斷 |
| --inspect-brk=[host:port] | 啟用 inspector 代理；繫結到地址或主機名 host（預設：127.0.0.1）；在埠 port 上監聽（預設：9229）；在使用者程式碼開始前中斷 |
| --inspect-wait | 啟用 inspector 代理；在預設地址和埠（127.0.0.1:9229）上監聽；等待偵錯程式附加。 |
| --inspect-wait=[host:port] | 啟用 inspector 代理；繫結到地址或主機名 host（預設：127.0.0.1）；在埠 port 上監聽（預設：9229）；等待偵錯程式附加。 |
| --disable-sigusr1 | 停用透過向程序傳送 SIGUSR1 訊號來啟動除錯會話的能力。 |
| node inspect script.js | 生成子程序以在 --inspect 標誌下執行使用者指令碼；並使用主程序執行 CLI 偵錯程式。 |
| node inspect --port=xxxx script.js | 生成子程序以在 --inspect 標誌下執行使用者指令碼；並使用主程序執行 CLI 偵錯程式。在埠 port 上監聽（預設：9229） |
啟用遠端除錯場景
我們建議您永遠不要讓偵錯程式在公共 IP 地址上監聽。如果您需要允許遠端除錯連線，我們建議使用 ssh 隧道。我們提供以下示例僅用於說明目的。在繼續之前，請了解允許遠端訪問特權服務的安全風險。
假設您正在遠端機器 remote.example.com 上執行 Node.js，並且您希望能夠進行除錯。在該機器上，您應該啟動 node 程序，讓 inspector 僅監聽 localhost（預設）。
node --inspect server.js
現在，在您想要發起除錯客戶端連線的本地機器上，您可以設定一個 ssh 隧道
ssh -L 9221:localhost:9229 [email protected]
這將啟動一個 ssh 隧道會話，其中到您本地機器上埠 9221 的連線將被轉發到 remote.example.com 上的埠 9229。您現在可以將偵錯程式（如 Chrome DevTools 或 Visual Studio Code）附加到 localhost:9221，它應該能夠像 Node.js 應用程式在本地執行一樣進行除錯。
舊版偵錯程式
自 Node.js 7.7.0 起，舊版偵錯程式已被棄用。請改用 --inspect 和 Inspector。
當在版本 7 及更早版本中使用 --debug 或 --debug-brk 開關啟動時，Node.js 會在一個 TCP 埠（預設為 5858）上監聽由已停用的 V8 除錯協議定義的除錯命令。任何支援此協議的偵錯程式客戶端都可以連線並除錯正在執行的程序；下面列出了一些流行的客戶端。
V8 除錯協議已不再維護或提供文件。
內建偵錯程式
啟動 node debug script_name.js 以在內建的命令列偵錯程式下啟動您的指令碼。您的指令碼在另一個以 --debug-brk 選項啟動的 Node.js 程序中開始，而初始的 Node.js 程序執行 _debugger.js 指令碼並連線到您的目標。更多資訊請參見文件。
node-inspector
透過使用一箇中間程序，將 Chromium 中使用的 Inspector 協議轉換為 Node.js 中使用的 V8 偵錯程式協議，來使用 Chrome DevTools 除錯您的 Node.js 應用。更多資訊請參見 https://github.com/node-inspector/node-inspector。