node-devtools-cli

Node DevTools 命令行工具

用于非阻塞调试 Node.js 后端进程的命令行界面。通过 Inspector Protocol（Chrome DevTools Protocol）连接，并提供跟踪点、日志点、异常点和监视表达式，且不会暂停执行。

安装

与 browser-devtools-mcp 使用同一个包：

npm install -g browser-devtools-mcp

快速开始

# 1. Start daemon (if not running)
node-devtools-cli daemon start

# 2. Connect to a Node.js process (by PID)
node-devtools-cli --session-id my-debug debug connect --pid 12345

# 3. Set a tracepoint on server.js line 42
node-devtools-cli --session-id my-debug debug put-tracepoint \
  --url-pattern "server.js" \
  --line-number 42

# 4. Trigger the code path (e.g., make API request to your app)
# 5. Get captured snapshots
node-devtools-cli --session-id my-debug --json debug get-probe-snapshots

全局选项

选项	说明	默认值
--port <number>	守护进程服务端口	2020
--session-id <string>	用于持久化 Node 连接的会话	自动
--json	以 JSON 格式输出（推荐用于 AI）	false
--quiet	隐藏日志消息	false
--verbose	启用调试输出	false
--timeout <ms>	操作超时时间	30000

AI Agent 推荐选项：

node-devtools-cli --json --quiet --session-id "debug-session" <command>

工具域

域	说明	参考
debug	连接、跟踪点、日志点、异常点、监视、快照

连接方式

使用 debug connect 连接，可选择以下任一方式：

方式	选项	示例
PID	--pid <number>	--pid 12345
进程名称	--process-name <pattern>	--process-name "server.js"
Docker 容器	--container-id 或 --container-name	--container-name my-api
Inspector 端口	--inspector-port <number>	--inspector-port 9229
WebSocket URL	--ws-url <url>	--ws-url "ws://127.0.0.1:9229/abc"

如果进程未启用 --inspect，命令行工具会通过 SIGUSR1 启用它（无需更改代码）。对于 Docker：公开端口 9229，并使用 --inspect=0.0.0.0:9229。

命令行管理命令

守护进程

node-devtools-cli daemon status
node-devtools-cli daemon start
node-devtools-cli daemon stop
node-devtools-cli daemon restart
node-devtools-cli daemon info

会话

node-devtools-cli session list
node-devtools-cli session info <session-id>
node-devtools-cli session delete <session-id>

工具

node-devtools-cli tools list
node-devtools-cli tools search <query>
node-devtools-cli tools info <tool-name>

配置与更新

node-devtools-cli config
node-devtools-cli update --check

示例

按 PID 连接

SESSION="--session-id api-debug"

# Connect
node-devtools-cli $SESSION debug connect --pid $(pgrep -f "node server.js")

# Set tracepoint on route handler
node-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 25

# Trigger: curl http://localhost:3000/api/users
# Get snapshots
node-devtools-cli $SESSION --json debug get-probe-snapshots

按进程名称连接

node-devtools-cli debug connect --process-name "api"

Docker 容器

# App runs in container with -p 9229:9229
node-devtools-cli debug connect \
  --container-name my-node-app \
  --host host.docker.internal \
  --inspector-port 9229

捕获异常

SESSION="--session-id exc-debug"

node-devtools-cli $SESSION debug connect --pid 12345
node-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

# Trigger error in app
# Check snapshots
node-devtools-cli $SESSION --json debug get-probe-snapshots --types exceptionpoint

交互模式

node-devtools-cli interactive

命令	说明
help	显示命令
exit、quit	退出
debug connect	连接到进程
debug status	连接状态
<domain> <tool>	执行工具

Shell 补全

eval "$(node-devtools-cli completion bash)"
eval "$(node-devtools-cli completion zsh)"