偵錯工具#

穩定度：2 - 穩定

Node.js 內建一個命令列偵錯工具。雖然 Node.js 偵錯客戶端並非功能全備的偵錯工具，但已具備基礎的逐步執行與檢查功能。

若要使用它，請在啟動 Node.js 時加上 inspect 引數，後接要偵錯的指令碼路徑。

$ node inspect myscript.js
< Debugger listening on ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
< For help, see: https://nodejs.com.tw/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
 ok
Break on start in myscript.js:2
  1 // myscript.js
> 2 global.x = 5;
  3 setTimeout(() => {
  4   debugger;
debug>

偵錯工具會自動在第一行可執行程式碼處中斷。若要改為執行直到遇到第一個中斷點（由 debugger 陳述式指定），請將 NODE_INSPECT_RESUME_ON_START 環境變數設為 1。

$ cat myscript.js
// myscript.js
global.x = 5;
setTimeout(() => {
  debugger;
  console.log('world');
}, 1000);
console.log('hello');
$ NODE_INSPECT_RESUME_ON_START=1 node inspect myscript.js
< Debugger listening on ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2
< For help, see: https://nodejs.com.tw/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
< hello
<
break in myscript.js:4
  2 global.x = 5;
  3 setTimeout(() => {
> 4   debugger;
  5   console.log('world');
  6 }, 1000);
debug> next
break in myscript.js:5
  3 setTimeout(() => {
  4   debugger;
> 5   console.log('world');
  6 }, 1000);
  7 console.log('hello');
debug> repl
Press Ctrl+C to leave debug repl
> x
5
> 2 + 2
4
debug> next
< world
<
break in myscript.js:6
  4   debugger;
  5   console.log('world');
> 6 }, 1000);
  7 console.log('hello');
  8
debug> .exit
$

repl 指令允許遠端評估程式碼。next 指令可執行至下一行。輸入 help 可查看其他可用的指令。

在不輸入任何指令的情況下按下 enter，會重複執行上一次的偵錯指令。

監看式 (Watchers)#

在偵錯時可以監看運算式和變數的值。每當觸發中斷點時，監看清單中的每個運算式都會在當前環境中進行評估，並顯示在中斷點原始碼列表的正上方。

若要開始監看某個運算式，請輸入 watch('my_expression')。輸入 watchers 指令會列出目前已啟用的監看式。若要移除監看式，請輸入 unwatch('my_expression')。

指令參考#

逐步執行 (Stepping)#

  • cont, c: 繼續執行
  • next, n: 執行至下一行 (Step next)
  • step, s: 進入函式內部 (Step in)
  • out, o: 跳出函式 (Step out)
  • pause: 暫停執行中的程式碼（類似開發者工具中的暫停按鈕）

中斷點 (Breakpoints)#

  • setBreakpoint(), sb(): 在當前行設定中斷點
  • setBreakpoint(line), sb(line): 在特定行設定中斷點
  • setBreakpoint('fn()'), sb(...): 在函式主體的第一行陳述式設定中斷點
  • setBreakpoint('script.js', 1), sb(...): 在 script.js 的第一行設定中斷點
  • setBreakpoint('script.js', 1, 'num < 4'), sb(...): 在 script.js 的第一行設定條件式中斷點，僅在 num < 4 評估為 true 時中斷
  • clearBreakpoint('script.js', 1), cb(...): 清除 script.js 第 1 行的中斷點

亦可在尚未載入的檔案（模組）中設定中斷點

$ node inspect main.js
< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
< For help, see: https://nodejs.com.tw/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
Break on start in main.js:1
> 1 const mod = require('./mod.js');
  2 mod.hello();
  3 mod.hello();
debug> setBreakpoint('mod.js', 22)
Warning: script 'mod.js' was not loaded yet.
debug> c
break in mod.js:22
 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 21
>22 exports.hello = function() {
 23   return 'hello from module';
 24 };
debug>

亦可設定條件式中斷點，僅在給定運算式評估為 true 時中斷

$ node inspect main.js
< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
< For help, see: https://nodejs.com.tw/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
Break on start in main.js:7
  5 }
  6
> 7 addOne(10);
  8 addOne(-1);
  9
debug> setBreakpoint('main.js', 4, 'num < 0')
  1 'use strict';
  2
  3 function addOne(num) {
> 4   return num + 1;
  5 }
  6
  7 addOne(10);
  8 addOne(-1);
  9
debug> cont
break in main.js:4
  2
  3 function addOne(num) {
> 4   return num + 1;
  5 }
  6
debug> exec('num')
-1
debug>

資訊#

  • backtrace, bt: 列印當前執行框架的追蹤資訊 (backtrace)
  • list(5): 列出原始碼並顯示 5 行上下文（前後各 5 行）
  • watch(expr): 新增運算式至監看清單
  • unwatch(expr): 從監看清單移除運算式
  • unwatch(index): 移除監看清單中指定索引的運算式
  • watchers: 列出所有監看式及其值（每次中斷點時會自動列出）
  • repl: 開啟偵錯工具的 REPL，以便在偵錯指令碼的環境中進行評估
  • exec expr, p expr: 在偵錯指令碼的環境中執行運算式並列印其值
  • profile: 啟動 CPU 設定檔分析 (profiling) 工作階段
  • profileEnd: 停止當前的 CPU 設定檔分析工作階段
  • profiles: 列出所有已完成的 CPU 設定檔分析工作階段
  • profiles[n].save(filepath = 'node.cpuprofile'): 將 CPU 設定檔分析工作階段儲存為 JSON 至磁碟
  • takeHeapSnapshot(filepath = 'node.heapsnapshot'): 拍攝記憶體堆疊快照並儲存為 JSON 至磁碟

執行控制#

  • run: 執行指令碼（偵錯工具啟動時會自動執行）
  • restart: 重啟指令碼
  • kill: 終止指令碼

其他#

  • scripts: 列出所有已載入的指令碼
  • version: 顯示 V8 版本

進階用法#

Node.js 的 V8 Inspector 整合#

V8 Inspector 整合允許將 Chrome 開發者工具連結至 Node.js 執行個體以進行偵錯與效能分析。它使用 Chrome 開發者工具通訊協定 (Chrome DevTools Protocol)。

在啟動 Node.js 應用程式時傳入 --inspect 旗標即可啟用 V8 Inspector。亦可透過該旗標指定自訂連接埠，例如 --inspect=9222 會在 9222 連接埠接聽開發者工具的連線。

使用 --inspect 旗標會讓程式碼在偵錯工具連線前立即執行。這意味著在您開始偵錯之前程式碼就已經開始執行，若您希望從一開始就進行偵錯，這可能不是最理想的方式。

在這種情況下，您有兩種替代方案：

  1. --inspect-wait 旗標：此旗標會等待偵錯工具連線後才執行程式碼。這讓您可以從程式執行的一開始就進行偵錯。
  2. --inspect-brk 旗標：與 --inspect 不同，此旗標會在偵錯工具連線後，立即在程式碼的第一行中斷。這對於想要從一開始就逐步偵錯程式碼的情況非常有用，且程式碼不會在偵錯前先行執行。

因此，在決定使用 --inspect、--inspect-wait 還是 --inspect-brk 時，請考慮您是希望程式碼立即執行、等待偵錯工具連線後執行，還是在第一行中斷以便逐步偵錯。

$ node --inspect index.js
Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
For help, see: https://nodejs.com.tw/en/docs/inspector

（在上述範例中，URL 結尾處的 UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29 是即時生成的，在不同的偵錯工作階段中會有所不同。）