cs-note/claude-code-best/docs/features/debug-mode.md

---
tags:
  - debug
  - CLI
  - Bun
  - 调试
create time: 2026-06-09 22:30
---

# Debug 模式

## 概述

通过 VS Code attach 模式调试 CLI 运行时。TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试，因此使用 **attach 模式**连接到正在运行的 Bun 进程。

## 正文

### 步骤

#### 1. 终端启动 inspect 服务

```bash
bun run dev:inspect
```

会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。

#### 2. VS Code 附着调试器

1. 在 `src/` 文件中打断点
2. F5 -> 选择 **"Attach to Bun (TUI debug)"**

> [!warning]
> `dev:inspect` 和 `launch.json` 中的 WebSocket 地址会在每次启动时变化，需要同步更新两处。

### 原理

`dev:inspect` 脚本实际执行的是 `scripts/dev-debug.ts`：

```typescript
// scripts/dev-debug.ts
process.env.BUN_INSPECT = "localhost:8888/<token>"
await import("./dev")
```

通过设置 `BUN_INSPECT` 环境变量启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，然后导入 dev 模式入口。VS Code 的 `bun` 扩展通过 WebSocket 连接到输出的地址实现 attach。

### JetBrains IDE

理论上 JetBrains 系列（WebStorm / IntelliJ 等）也支持 attach 到 Bun inspect 服务（Run -> Attach to Process），但尚未实际验证过。

> [!tip]
> 如果你验证成功，欢迎补充文档。

### 相关文件

| 文件 | 说明 |
|---|---|
| `package.json` -> `dev:inspect` | 启动 inspect 服务的 npm script |
| `.vscode/launch.json` | VS Code attach 调试配置 |
| `scripts/dev.ts` | dev 模式入口，注入 MACRO defines |

## 关联笔记

- [[claude-code-best/docs/features/fork-subagent]]