dbg

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dbg Debugger

dbg 调试器

dbg

is a CLI debugger that supports Node.js (V8/CDP), Bun (WebKit/JSC), and native code (C/C++/Rust/Swift via LLDB/DAP). It uses short

@refs

for all entities -- use them instead of long IDs.

dbg

是一款CLI调试器，支持Node.js（V8/CDP）、Bun（WebKit/JSC）以及原生代码（通过LLDB/DAP调试C/C++/Rust/Swift）。它为所有实体使用简短的

@refs

引用——使用这些引用而非冗长的ID。

Supported Runtimes

支持的运行时

Runtime	Language	Launch example
Node.js	JavaScript	`dbg launch --brk node app.js`
tsx / ts-node	TypeScript	`dbg launch --brk tsx src/app.ts`
Bun	JavaScript / TypeScript	`dbg launch --brk bun app.ts`
LLDB	C / C++ / Rust / Swift	`dbg launch --brk --runtime lldb ./program`

The runtime is auto-detected from the launch command for JS runtimes. For native code, use

--runtime lldb

运行时	语言	启动示例
Node.js	JavaScript	`dbg launch --brk node app.js`
tsx / ts-node	TypeScript	`dbg launch --brk tsx src/app.ts`
Bun	JavaScript / TypeScript	`dbg launch --brk bun app.ts`
LLDB	C / C++ / Rust / Swift	`dbg launch --brk --runtime lldb ./program`

对于JS运行时，会自动从启动命令中检测运行时类型。对于原生代码，请使用

--runtime lldb

参数。

Core Debug Loop

核心调试流程

bash

undefined

bash

undefined

1. Launch with breakpoint at first line

1. 在第一行设置断点启动

dbg launch --brk node app.js

Or: dbg launch --brk bun app.ts

或者: dbg launch --brk bun app.ts

Or: dbg launch --brk --runtime lldb ./my_program

或者: dbg launch --brk --runtime lldb ./my_program

Or attach to a running process with the --inspect flag

或者附加到启用了--inspect标志的运行中进程

dbg attach 9229

2. Set breakpoints at suspicious locations

2. 在可疑位置设置断点

dbg break src/handler.ts:42 dbg break src/utils.ts:15 --condition "count > 10"

3. Run to breakpoint

3. 运行到断点处

dbg continue

4. Inspect state (shows location, source, locals, stack)

4. 检查状态（显示位置、源代码、局部变量、调用栈）

dbg state

5. Drill into values

5. 深入查看值

dbg props @v1 # expand object dbg props @v1 --depth 3 # expand nested 3 levels dbg eval "x + 1"

dbg props @v1 # 展开对象 dbg props @v1 --depth 3 # 展开嵌套3层 dbg eval "x + 1"

6. Fix and verify (JS/TS only)

6. 修复并验证（仅JS/TS支持）

dbg set count 0 # change variable dbg hotpatch src/utils.js # live-edit (reads file from disk) dbg continue # verify fix

undefined

dbg set count 0 # 修改变量 dbg hotpatch src/utils.js # 实时编辑（从磁盘读取文件） dbg continue # 验证修复效果

undefined

Debugging Strategies

调试策略

Bug investigation -- narrow down with breakpoints

Bug排查——通过断点缩小范围

bash

dbg launch --brk node app.js
dbg break src/api.ts:50                    # suspect line
dbg break src/api.ts:60 --condition "!user" # conditional
dbg continue
dbg vars                                    # check locals
dbg eval "JSON.stringify(req.body)"         # inspect deeply
dbg step over                               # advance one line
dbg state                                   # see new state

bash

dbg launch --brk node app.js
dbg break src/api.ts:50                    # 可疑代码行
dbg break src/api.ts:60 --condition "!user" # 条件断点
dbg continue
dbg vars                                    # 检查局部变量
dbg eval "JSON.stringify(req.body)"         # 深入查看内容
dbg step over                               # 单步跳过一行
dbg state                                   # 查看新状态

Native code debugging (C/C++/Rust)

原生代码调试（C/C++/Rust）

bash

dbg launch --brk --runtime lldb ./my_program
dbg break main.c:42
dbg break-fn main                          # function breakpoint (DAP only)
dbg continue
dbg vars                                    # inspect locals
dbg eval "array[i]"                         # evaluate expression
dbg step into                               # step into function

bash

dbg launch --brk --runtime lldb ./my_program
dbg break main.c:42
dbg break-fn main                          # 函数断点（仅DAP支持）
dbg continue
dbg vars                                    # 检查局部变量
dbg eval "array[i]"                         # 计算表达式
dbg step into                               # 单步进入函数

Attach to running/test process

附加到运行中/测试进程

bash

undefined

bash

undefined

Start with inspector enabled

启动时启用调试检查器

node --inspect app.js

Or: bun --inspect app.ts

或者: bun --inspect app.ts

Then attach

然后附加调试器

dbg attach 9229 dbg state

undefined

dbg attach 9229 dbg state

undefined

Trace execution flow with logpoints (no pause)

使用日志点追踪执行流程（不会暂停）

bash

dbg logpoint src/auth.ts:20 "login attempt: ${username}"
dbg logpoint src/auth.ts:45 "auth result: ${result}"
dbg continue
dbg console    # see logged output

bash

dbg logpoint src/auth.ts:20 "login attempt: ${username}"
dbg logpoint src/auth.ts:45 "auth result: ${result}"
dbg continue
dbg console    # 查看日志输出

Exception debugging

异常调试

bash

dbg catch uncaught          # pause on uncaught exceptions
dbg continue                # runs until exception
dbg state                   # see where it threw
dbg eval "err.message"      # inspect the error
dbg stack                   # full call stack

bash

dbg catch uncaught          # 在未捕获异常处暂停
dbg continue                # 运行至异常触发位置
dbg state                   # 查看异常抛出位置
dbg eval "err.message"      # 检查错误信息
dbg stack                   # 查看完整调用栈

TypeScript source map support

TypeScript源映射支持

dbg automatically resolves

.ts

paths via source maps. Set breakpoints using

.ts

paths, see

.ts

source in output. Use

--generated

to see compiled

.js

if needed.

dbg会自动通过源映射解析

.ts

文件路径。可以使用

.ts

文件路径设置断点，输出中会显示

.ts

源代码。如果需要查看编译后的

.js

代码，请使用

--generated

参数。

Ref System

引用系统

Every output assigns short refs. Use them everywhere:

```
@v1..@vN
```
-- variables:
```
dbg props @v1
```
,
```
dbg set @v2 true
```
```
@f0..@fN
```
-- stack frames:
```
dbg eval --frame @f1 "this"
```

BP#1..N

-- breakpoints:

dbg break-rm BP#1

dbg break-toggle BP#1

```
LP#1..N
```
-- logpoints:
```
dbg break-rm LP#1
```

Refs

@v

@f

reset on each pause.

BP#

LP#

persist until removed.

所有输出都会分配简短的引用标识，可在任意命令中使用：

```
@v1..@vN
```
-- 变量：
```
dbg props @v1
```
、
```
dbg set @v2 true
```
```
@f0..@fN
```
-- 调用栈帧：
```
dbg eval --frame @f1 "this"
```

BP#1..N

-- 断点：

dbg break-rm BP#1

、

dbg break-toggle BP#1

```
LP#1..N
```
-- 日志点：
```
dbg break-rm LP#1
```

@v

@f

类型的引用会在每次暂停时重置。

BP#

LP#

类型的引用会保留直到被删除。

Key Flags

关键标志

```
--json
```
-- machine-readable JSON output on any command
```
--session NAME
```
-- target a specific session (default: "default")
```
--runtime NAME
```
-- select debug adapter (e.g.
```
lldb
```
for native code)
```
--generated
```
-- bypass source maps, show compiled JS (on state/source/stack)

```
--json
```
-- 所有命令输出机器可读的JSON格式
```
--session NAME
```
-- 指定目标会话（默认值："default"）
```
--runtime NAME
```
-- 选择调试适配器（例如，原生代码使用
```
lldb
```
）
```
--generated
```
-- 绕过源映射，显示编译后的JS代码（适用于state/source/stack命令）

Command Reference

命令参考

See references/commands.md for full command details and options.

完整的命令详情和选项请参考references/commands.md。

Tips

提示

```
dbg state
```
after stepping always shows location + source + locals -- usually enough context
```
dbg state -c
```
for source only,
```
-v
```
for vars only,
```
-s
```
for stack only -- save tokens
```
dbg eval
```
supports
```
await
```
-- useful for async inspection (JS/TS)
```
dbg blackbox "node_modules/**"
```
-- skip stepping into dependencies
```
dbg hotpatch file
```
reads the file from disk -- edit the file first, then hotpatch (JS/TS only)
```
dbg break-fn funcName
```
-- function breakpoints work with DAP runtimes (LLDB)
Execution commands (
```
continue
```
,
```
step
```
,
```
pause
```
,
```
run-to
```
) auto-return status
```
dbg stop
```
kills the debugged process and daemon

单步执行后使用
```
dbg state
```
，总会显示位置、源代码和局部变量——通常已足够提供上下文信息
使用
```
dbg state -c
```
仅显示源代码，
```
-v
```
仅显示变量，
```
-s
```
仅显示调用栈——节省输出内容
```
dbg eval
```
支持
```
await
```
——对异步代码调试非常有用（仅JS/TS）
```
dbg blackbox "node_modules/**"
```
-- 跳过进入依赖包代码的单步执行
```
dbg hotpatch file
```
会从磁盘读取文件——请先编辑文件，再执行hotpatch命令（仅JS/TS）
```
dbg break-fn funcName
```
-- 函数断点仅支持DAP运行时（LLDB）
执行类命令（
```
continue
```
、
```
step
```
、
```
pause
```
、
```
run-to
```
）会自动返回状态
```
dbg stop
```
会终止被调试的进程和守护进程