node-devtools-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Node DevTools CLI

Command-line interface for non-blocking debugging of Node.js backend processes. Connects via the Inspector Protocol (Chrome DevTools Protocol) and provides tracepoints, logpoints, exceptionpoints, and watch expressions without pausing execution.

这是一款用于非阻塞式调试Node.js后端进程的命令行界面工具。它通过Inspector Protocol（Chrome DevTools Protocol）进行连接，可在不暂停执行的情况下提供跟踪点、日志点、异常点和监视表达式功能。

Installation

安装

Same package as browser-devtools-mcp:

bash

npm install -g browser-devtools-mcp

与browser-devtools-mcp为同一包：

bash

npm install -g browser-devtools-mcp

Quick Start

快速开始

bash

undefined

bash

undefined

1. Start daemon (if not running)

1. 启动守护进程（如果未运行）

node-devtools-cli daemon start

2. Connect to a Node.js process (by PID)

2. 通过PID连接到Node.js进程

node-devtools-cli --session-id my-debug debug connect --pid 12345

3. Set a tracepoint on server.js line 42

3. 在server.js的第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)

4. 触发代码路径（例如，向你的应用发起API请求）

5. Get captured snapshots

5. 获取捕获的快照

node-devtools-cli --session-id my-debug --json debug get-tracepoint-snapshots

undefined

node-devtools-cli --session-id my-debug --json debug get-tracepoint-snapshots

undefined

Global Options

全局选项

Option	Description	Default
`--port <number>`	Daemon server port	`2020`
`--session-id <string>`	Session for Node connection persistence	auto
`--json`	Output as JSON (recommended for AI)	`false`
`--quiet`	Suppress log messages	`false`
`--verbose`	Enable debug output	`false`
`--timeout <ms>`	Operation timeout	`30000`

AI Agent Recommended:

bash

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

选项	描述	默认值
`--port <number>`	守护进程服务器端口	`2020`
`--session-id <string>`	用于保持Node连接的会话标识	自动生成
`--json`	以JSON格式输出（推荐AI使用）	`false`
`--quiet`	抑制日志消息	`false`
`--verbose`	启用调试输出	`false`
`--timeout <ms>`	操作超时时间	`30000`

AI Agent 推荐用法：

bash

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

Tool Domains

工具领域

Domain	Description	Reference
debug	Connection, tracepoints, logpoints, exceptionpoints, watch, snapshots
run	JavaScript execution in connected Node process

领域	描述	参考
debug	连接、跟踪点、日志点、异常点、监视、快照
run	在已连接的Node进程中执行JavaScript

Connection Methods

连接方式

Connect via

debug connect

with one of:

Method	Option	Example
PID	`--pid <number>`	`--pid 12345`
Process name	`--process-name <pattern>`	`--process-name "server.js"`
Docker container	`--container-id` or `--container-name`	`--container-name my-api`
Inspector port	`--port <number>`	`--port 9229`
WebSocket URL	`--ws-url <url>`	`--ws-url "ws://127.0.0.1:9229/abc"`

If the process doesn't have

--inspect

active, the CLI activates it via SIGUSR1 (no code changes). For Docker: expose port 9229 and use

--inspect=0.0.0.0:9229

可通过

debug connect

命令，使用以下任意一种方式连接：

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

如果目标进程未启用

--inspect

，CLI会通过SIGUSR1信号启用该功能（无需修改代码）。对于Docker环境：需暴露9229端口，并使用

--inspect=0.0.0.0:9229

配置。

CLI Management Commands

CLI管理命令

Daemon

守护进程管理

bash

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

bash

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

Session

会话管理

bash

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

bash

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

Tools

工具管理

bash

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

bash

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

Config & Updates

配置与更新

bash

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

bash

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

Examples

示例

Connect by PID

通过PID连接

bash

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

bash

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

触发代码：curl http://localhost:3000/api/users

Get snapshots

获取快照

node-devtools-cli $SESSION --json debug get-tracepoint-snapshots

undefined

node-devtools-cli $SESSION --json debug get-tracepoint-snapshots

undefined

Connect by Process Name

通过进程名连接

bash

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

bash

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

Docker Container

Docker容器连接

bash

undefined

bash

undefined

App runs in container with -p 9229:9229

应用运行在已映射9229:9229端口的容器中

node-devtools-cli debug connect
--container-name my-node-app
--host host.docker.internal
--port 9229

undefined

node-devtools-cli debug connect
--container-name my-node-app
--host host.docker.internal
--port 9229

undefined

Exception Catching

异常捕获

bash

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

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

bash

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-exceptionpoint-snapshots

undefined

node-devtools-cli $SESSION --json debug get-exceptionpoint-snapshots

undefined

Run JS in Node Process

在Node进程中运行JavaScript

bash

undefined

bash

undefined

After connect

连接成功后执行

node-devtools-cli run js-in-node --script "process.memoryUsage()" node-devtools-cli run js-in-node --script "require('os').loadavg()"

undefined

node-devtools-cli run js-in-node --script "process.memoryUsage()" node-devtools-cli run js-in-node --script "require('os').loadavg()"

undefined

Interactive Mode

交互模式

bash

node-devtools-cli interactive

Command	Description
`help`	Show commands
`exit` , `quit`	Exit
`debug connect`	Connect to process
`debug status`	Connection status
`<domain> <tool>`	Execute tool

bash

node-devtools-cli interactive

命令	描述
`help`	显示命令列表
`exit` , `quit`	退出交互模式
`debug connect`	连接到进程
`debug status`	查看连接状态
`<domain> <tool>`	执行对应领域的工具命令

Shell Completions

Shell补全

bash

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

bash

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