第十二章：常见问题与排障清单（安装/网络/权限/卡死）

12.1 命令找不到：claude: command not found

排查顺序：

1. 确认已安装并且 PATH 生效（新开一个终端再试）
2. 尝试查看版本（如果命令支持）：

claude --version

3. 如果你曾经用 npm 安装过，又改用了原生二进制/包管理器，确认没有“多版本混装”

参考（安装与迁移提示）：https://code.claude.com/docs/en/setup

12.2 登录失败或账号不对

建议做法：

• 用 /login 重新登录或切换账号
• 如果你在公司网络环境，检查代理/网络出口策略

参考（账号与接口概览）：https://code.claude.com/docs/en/overview

12.3 在错误目录启动：Claude 读不到仓库

典型症状：

• Claude 找不到你说的文件
• 跑命令失败（因为当前目录不在项目根）

修复：

cd /path/to/your-repo
claude

12.4 让 Claude 跑测试卡住

常见原因：

• 命令需要交互输入
• 命令本来就很慢（全量测试、构建）
• 命令依赖环境变量/配置但没提供

建议处理：

• 明确禁止交互式命令；要求给出非交互替代
• 先跑子集测试，再扩到全量
• 把必需环境变量写清楚（但不要粘贴密钥）

12.5 Claude 改动扩散：改了不该改的目录

根因通常是：你没有把边界写清楚。

修复方式：

边界：
- 只允许修改 src/ 与 tests/
- 禁止修改 .github/、infra/、deployment/ 等目录
关键节点先 /diff，我确认后再继续

并把这段固化到团队规则里（见第 11 章）。

12.6 本章小结

排障的关键是“按层定位”：

• 安装与 PATH → 账号与网络 → 项目目录 → 命令与依赖 → 修改边界

至此，《Claude Code从入门到精通》系列完结。你可以直接从第 3 章的首次会话模板开始，把目标/约束/验收写清楚，然后用 /diff 与 /run 把交付变成稳定流程。