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
- 用於輕鬆連接至 Inspector Protocol 端點的程式庫。
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 應用程序。