跳转至

Tutorial ｜ 调试 Session

难度：⭐⭐⭐ 时间：~1h 前置：基本 Claude Code 使用 产物：能定位 / 解决 session 相关问题

1. Session 是什么

Session = Claude Code 的一次对话 - 持久化到磁盘 - 可 resume / continue - 包含所有消息、工具调用、附件

位置：~/.claude/projects/<project>/<session-uuid>.jsonl

2. 4 大调试场景

2.1 Session 卡住

工具不响应 / 长时间无反应。

2.2 Session 报错

工具失败 / API 错 / hook 错。

2.3 Session 行为异常

输出不对 / 工具错 / 上下文丢失。

2.4 Session 性能问题

慢 / 卡 / 高 CPU。

3. 6 个调试工具

3.1 --debug flag

claude --debug api
claude --debug hooks
claude --debug bash
claude --debug mcp
claude --debug "api,hooks"
claude --debug "all"
claude --debug "!api"  # 反向：除了 api

类别过滤。

3.2 --verbose

claude --verbose

verbose 模式 —— 详细输出。

3.3 日志文件

# 推测
~/.claude/logs/2026-06-05.jsonl

每日一个文件。

3.4 Session 列表

claude --resume  # 列出可 resume 的 session

列表。

3.5 Inspect Mode

# 推测
claude --inspect <session-id>

inspect。

3.6 Statsig 上报

profileReport()  # 启动后输出

性能。

4. 5 个常见问题 + 调试

4.1 Session resume 失败

# 1. 看 session 是否存在
ls ~/.claude/projects/<project>/

# 2. 修复
claude --resume <session-id>

# 3. 如果坏了
claude --fork-session --resume <session-id>

3 步。

4.2 工具调用失败

# 1. debug mode
claude --debug bash

# 2. 复现
> /bash  # 推测命令

# 3. 看 sandbox 设置
# settings.json 检查

3 步。

4.3 Hook 不触发

# 1. debug hooks
claude --debug hooks

# 2. 看 hooks.json 配置
# 3. 测试 hook 命令
./hook-command.sh  # 直接跑

3 步。

4.4 MCP 连接失败

# 1. debug mcp
claude --debug mcp

# 2. 测 server
npx @modelcontextprotocol/inspector /path/to/server.js

# 3. 重新连接
claude mcp remove <name>
claude mcp add --transport stdio -- ...

3 步。

4.5 性能问题

# 1. 看 stats
claude --verbose

# 2. profileReport 输出
# 3. 找瓶颈（启动 / preAction / 第一次 render）

3 步。

5. Session 文件结构

{"type": "user", "message": {...}, "uuid": "..."}
{"type": "assistant", "message": {...}, "uuid": "..."}
{"type": "tool_use", "name": "Bash", "input": {...}}
{"type": "tool_result", "content": "..."}

JSONL 格式 —— 每行一个事件。

5.1 手动检查

# 看 session 大小
ls -lh ~/.claude/projects/<project>/<session>.jsonl

# 数消息数
wc -l ~/.claude/projects/<project>/<session>.jsonl

# 看最后 10 行
tail ~/.claude/projects/<project>/<session>.jsonl | jq .

3 工具。

5.2 jq 过滤

# 所有 tool_use
jq 'select(.type == "tool_use")' session.jsonl

# 所有错误
jq 'select(.type == "tool_result" and .is_error == true)' session.jsonl

jq。

6. 4 种 session 修复

6.1 继续

claude --continue  # 最近的 session
claude -c

继续。

6.2 Resume

claude --resume <session-id>
claude -r <session-id>

恢复。

6.3 Fork

claude --resume <session-id> --fork-session

分叉 —— 复制成新 session。

6.4 重命名

claude --name "My important session" --resume <session-id>

重命名。

7. 实战：诊断慢 session

7.1 Step 1: 确认慢

time claude --resume <session-id>

测时间。

7.2 Step 2: 启动 profile

claude --resume <session-id> --debug perf

profile。

7.3 Step 3: 找瓶颈

看输出： - main_tsx_entry → main_function_start 间隔？ - preAction_start → preAction_after_init 间隔？ - run_before_parse → run_after_parse 间隔？

3 个埋点。

7.4 Step 4: 修复

慢的环节 修复
启动 关 prefetch / 减少 plugin
init 减少 hook / 减少 plugin 加载
render 减少 console.log / 减少 useEffect

修复 3 类。

8. 实战：恢复损坏的 session

8.1 症状

claude --resume <session-id>
# 报错：Invalid session

8.2 排查

# 1. 文件存在？
ls -la ~/.claude/projects/<project>/

# 2. JSON 有效？
head -1 session.jsonl | jq .

# 3. 看最近内容
tail -100 session.jsonl

3 步。

8.3 修复

# 备份
cp session.jsonl session.jsonl.bak

# 删尾部损坏内容
head -n -10 session.jsonl > session.jsonl.fixed
mv session.jsonl.fixed session.jsonl

# 恢复
claude --resume <session-id>

修复。

9. Debug 日志位置

日志 位置（推测）
主日志 ~/.claude/logs/<date>.jsonl
Session ~/.claude/projects/<project>/<session>.jsonl
Plugin cache ~/.claude/plugins/cache/
MCP cache ~/.claude/mcp-cache/
Statsig 远程
Sentry 远程

6 个日志位置。

10. 5 个调试技巧

  1. --debug 类别过滤 —— 不一次看所有
  2. jq 过滤 session —— 找具体事件
  3. time 命令 —— 测性能
  4. 复现 —— 简单 prompt 重现
  5. 隔离 —— 关 plugin / 关 hook 隔离

5 个技巧。

11. 下一步

  • 试 --debug api
  • 用 jq 过滤 session
  • 修一个慢 session