Node.js除錯

本指南將幫助您開始對您的Node.js應用程式和腳本進行除錯。

啟用檢查器

當使用--inspect開關啟動時,Node.js 進程會監聽調試客戶端。默認情況下,它會在主機和端口 127.0.0.1:9229 上監聽。每個進程還會被分配一個唯一的UUID

檢查客戶端必須知道並指定主機地址、端口和 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 等。這樣做可能會讓您面臨潛在的重大安全威脅。我們建議您確保適當的防火牆和訪問控制,以防止安全漏洞。

請參閱關於“啟用遠程調試方案”部分,以了解如何安全地允許遠程調試器客戶端連接的建議。

本地應用程式可以完全存取檢查器。

即使將檢查器端口綁定到 127.0.0.1(預設值),任何在本機運行的應用程式都將具有不受限制的存取權限。這是為了方便本地調試器能夠方便附加而設計的。

瀏覽器、WebSockets 和同源策略

在網頁瀏覽器中打開的網站可以根據瀏覽器安全模型進行 WebSocket 和 HTTP 請求。必須進行初始的 HTTP 連接以獲取唯一的調試器會話 ID。同源策略防止網站能夠進行此 HTTP 連接。為了進一步防範 DNS 重新綁定攻擊,Node.js 驗證連接的 'Host' 標頭是否精確指定了 IP 地址或 localhost

這些安全策略不允許通過指定主機名來連接到遠程調試伺服器。您可以通過指定 IP 地址或使用下面描述的 SSH 隧道來繞過此限制。

檢查器客戶端

可以使用 node inspect myscript.js 來使用一個最小的 CLI 調試器。還有幾個商業和開源工具可以連接到 Node.js 檢查器。

Chrome DevTools 55+、Microsoft Edge

  • 選項 1: 在基於 Chromium 的瀏覽器中打開 chrome://inspect,或者在 Edge 中打開 edge://inspect。點擊“配置”按鈕,確保您的目標主機和端口已列出。
  • 選項 2: 從 /json/list 的輸出(參見上文)或 --inspect 的提示文本中複製 devtoolsFrontendUrl,然後粘貼到 Chrome 中。

請注意,Node.js 和 Chrome 需要在同一平台上運行。

Visual Studio Code 1.10+

  • 在“調試”面板中,點擊設置圖標以打開 .vscode/launch.json。選擇“Node.js”進行初始設置。

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

Gitpod

  • 從「調試」視圖開始一個 Node.js 調試配置,或按下 F5。參見 詳細說明

Eclipse IDE 和 Eclipse Wild Web Developer 擴展

  • 從 .js 檔案中選擇「Debug As... > Node program」,或
  • 創建一個調試配置以將調試器附加到正在運行的 Node.js 應用程序(消耗 --inspect 啟動)。

命令行選項

下表列出了各種運行時標誌對調試的影響

標誌意義
--inspect啟用檢查器代理;監聽默認地址和端口(127.0.0.1:9229)
--inspect=[host:port]啟用檢查器代理;綁定到地址或主機名 host(默認:127.0.0.1);監聽端口 port(默認:9229)
--inspect-brk啟用檢查器代理;監聽默認地址和端口(127.0.0.1:9229);在用戶代碼啟動之前中斷
--inspect-brk=[host:port]啟用檢查器代理;綁定到地址或主機名 host(默認:127.0.0.1);監聽端口 port(默認:9229);在用戶代碼啟動之前中斷
node inspect script.js產生子程序以在 --inspect 標誌下執行使用者的腳本;並使用主程序運行 CLI 調試器。
node inspect --port=xxxx script.js產生子程序以在 --inspect 標誌下執行使用者的腳本;並使用主程序運行 CLI 調試器。監聽 port 埠口(默認值:9229)

啟用遠程調試方案

我們建議您永遠不要讓調試器監聽公共 IP 地址。如果需要允許遠程調試連接,我們建議使用 ssh 隧道。我們僅提供以下示例以供說明。請在繼續之前了解允許遠程訪問特權服務的安全風險。

假設您正在遠程機器 remote.example.com 上運行 Node.js,您希望能夠進行調試。在該機器上,您應該以只監聽本地主機(默認值)的方式啟動 node 过程。

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 端口上監聽被停用的 V8 調試協議定義的調試命令,默認端口為 5858。任何講這種協議的調試器客戶端都可以連接並調試正在運行的進程;下面列出了一些流行的調試器。

V8 調試協議不再維護或文檔化。

內置調試器

使用內置命令行調試器來啟動 node debug script_name.js 以開始您的腳本。您的腳本在另一個使用 --debug-brk 選項啟動的 Node.js 進程中啟動,並且初始 Node.js 進程運行 _debugger.js 腳本並連接到您的目標。

node-inspector

使用一個中間進程來將 Chromium 中使用的 Inspector Protocol 轉換為 Node.js 中使用的 V8 調試器協議,以使用 Chrome DevTools 調試您的 Node.js 應用程序。