CCClaude Code中文喂饭教程

常见问题排障

Claude Code 常见问题排障教程：排障时不要急着乱改，先让 CC 分类、定位、解释原因，再决定是否修复。

排障的核心不是“让 CC 赶紧修”，而是先把问题分清楚。很多事故都是这样发生的：一开始只是登录失败、模型配置错、权限没批，结果越改越多，最后变成项目文件也乱了、上下文也乱了。

遇到问题时，先按这个顺序走：

暂停修改 -> 分类问题 -> 只读定位 -> 确认影响范围 -> 选择最小修复 -> 验证结果
只要问题还没分类，就不要让 CC 执行“大概率能修好”的修改。排障时最怕的不是慢，而是 CC 把一个小问题扩大成多个问题。

排障总模板

不知道问题属于哪一类时，直接复制这段。

当前任务遇到问题，请先不要修改文件。

请只做排障分类：
1. 这个问题属于安装登录、模型配置、权限、上下文、代码错误、构建失败，还是验收失败？
2. 你判断的依据是什么？
3. 需要读取哪些文件或日志来确认？
4. 当前是否有文件已经被修改？
5. 最小排查步骤是什么？
6. 哪些动作需要我确认后才能执行？

请先输出分析，不要直接修复。

常见问题分类表

现象优先怀疑第一动作
CC 无法启动安装、环境变量、入口选错先确认入口和启动方式
登录失败账号、网络、浏览器认证、Token不要反复重装，先看错误信息
模型无响应API Key、Base URL、模型名、额度先做只读验证任务
CC 一直要权限权限模式、目标范围不清、命令风险高先让它解释权限请求
CC 开始乱猜上下文太乱、没读关键文件让它列出实际读过的文件
改动超范围任务边界不清、自动接受太多先查 diff，再收窄
检查失败本次修改、历史问题、环境缺失先判断是否和本次修改有关
页面效果不对没运行、没截图、没看移动端用 /run 或截图反馈

CC 读不懂项目

表现通常是：它说错技术栈、引用不存在的目录、把生成文件当源码、或者按常见框架习惯胡猜。

你刚才对项目的判断不准确。

请重新只读分析：
1. 先列出你实际读取过的文件。
2. 只基于这些文件总结项目。
3. 不确定的地方写“未确认”。
4. 不要根据常见框架猜测。

如果它还是说不清楚，可以继续要求证据：

请给每个判断都标注依据。

格式：
- 判断：
- 依据文件：
- 依据内容：
- 是否确认：

没有文件依据的内容，请标为“推测”，不要当成事实。

CC 改多了

改多了不要立刻说“撤回”，先弄清楚哪些改动有用，哪些确实越界。

本次修改超出范围了，请先暂停。

请列出：
1. 所有被修改的文件。
2. 每个文件和原任务的关系。
3. 哪些修改是必要的。
4. 哪些修改可以撤回。

请先给出收窄方案，不要直接继续改。

收窄时可以要求它按三类归档：

请把当前改动分成三类：
1. 必须保留：直接服务于原任务。
2. 可以讨论：可能有用，但超出原范围。
3. 应该撤回：无关、风险高或没有必要。

每一类都列出文件和理由。
不要执行撤回，先等我确认。

检查失败

检查失败不等于要“大修”。先判断失败来源。

检查失败了，请不要扩大修复范围。

请判断：
1. 错误是否由本次修改引入。
2. 相关文件是哪几个。
3. 最小修复方案是什么。
4. 是否存在历史问题。
5. 如果是历史问题，请不要顺手修复，只说明风险。

如果错误很多，先让 CC 抽出关键错误：

日志很长，请先提取关键错误。

要求：
1. 只列最关键的 3 条错误。
2. 说明每条错误来自哪个文件或命令。
3. 判断是否和本次修改有关。
4. 给出最小修复建议。
5. 不要根据次要 warning 扩大范围。

误批了危险权限

我可能误批准了一个高风险操作。

请立即只读检查当前状态：
1. 刚才执行了什么操作。
2. 影响了哪些文件。
3. 是否删除、覆盖或重置了内容。
4. 是否影响 Git 状态。
5. 给出最低风险恢复建议。

不要继续修改文件，除非我明确确认。

如果涉及 Git、删除、覆盖、安装依赖、网络请求，要进入更保守模式：

从现在开始进入只读排障模式。

要求：
1. 不修改文件。
2. 不删除文件。
3. 不执行 Git 写操作。
4. 不安装依赖。
5. 不访问外部网络。
6. 只检查当前状态并给出恢复建议。

上下文聊乱了

我们重新收敛上下文。

请总结当前任务：
1. 原始目标是什么。
2. 已经完成了什么。
3. 修改了哪些文件。
4. 还有什么未完成。
5. 下一步最小动作是什么。

请不要做新修改，只做总结。

排障时该问什么

排障沟通要让 CC 给“证据”，而不是给“感觉”。

可以固定追问：

请把你的判断拆成三部分：
1. 已确认事实：来自文件、日志、diff 或我明确说过的话。
2. 推测：还没有证据，但可能成立的判断。
3. 下一步验证：用什么最小动作确认推测。

不要把推测当事实。

排障结束后要复盘

问题解决后，不要马上进入下一个任务。让 CC 总结这次问题，判断是否需要沉淀到 CLAUDE.md、Skill 或排障模板。

请总结这次排障结果。

要求：
1. 根因是什么。
2. 最终修改或处理了什么。
3. 哪些检查证明问题解决了。
4. 有没有未处理的历史问题。
5. 这次经验是否应该写入 CLAUDE.md、Skill 或排障文档。
6. 下次遇到同类问题，第一步应该做什么。

验收结果

下一篇：安装和登录失败