Claude Code 错误排查怎么做：客户报错处理更稳

客户发来一段报错，新手很容易马上丢给 Claude Code 问“怎么修”。更稳的做法是先把报错变成可诊断材料：问题在哪复现、错误原文是什么、环境是哪一个、最近改过什么、是否涉及敏感权限。信息整理清楚后，Claude Code 才更像助手，而不是猜谜机器。

这篇适合搭配 Claude Code 项目客户问题检查清单、Claude Code 常用命令检查清单、Claude Code 交付说明检查清单 和 /templates 使用。

适合谁

适合处理前端报错、构建失败、依赖冲突、接口返回异常、配置缺失这类小范围问题的新手。你可以先做低权限诊断，再决定是否进入修复。

也适合客户只给截图或一句“报错了”的场景。你的第一步不是改代码，而是把错误变成可复现、可验证、可交付的任务。

不适合谁

不适合客户拒绝提供错误原文和复现步骤，却要求你承诺修复结果的任务。没有证据链时，只能先诊断。

也不适合涉及生产数据、密钥、付款后台、管理员权限或安全事故的高风险排查。这些场景需要正式授权、脱敏和更严格复核。

具体步骤

第一，收集错误原文。让客户提供终端输出、控制台报错、接口状态码或构建日志。截图可以辅助，但最好要有可复制文字。

第二，确认复现路径。问清在哪个页面、哪个命令、哪个按钮、什么输入后出现报错。不能复现时，把任务定义为诊断，不要直接承诺修复。

第三，确认运行环境。本地、测试、预览、生产的错误不能混在一起。同一段代码在不同环境下可能有完全不同原因。

第四，脱敏后再分析。密钥、账号、真实用户资料、内部链接和付款信息都不能原样放进工具或交付说明。

第五，用低风险命令补证据。先查看配置、搜索错误关键词、读取 package.json、运行 lint 或 build。不要先运行部署、迁移、删除或重置命令。

第六，让 Claude Code 输出假设列表。不要只问“怎么修”，而是让它列出可能原因、需要验证的证据和下一步最小动作。

第七，写诊断结论。结论至少包含已确认事实、可能原因、已运行检查、未覆盖范围、需要客户补充的信息。

可复制排查 Prompt

请基于下面的脱敏错误信息做诊断，不要假设生产权限：
项目类型：
复现步骤：
错误原文：
运行环境：
最近变更：
我已经运行过的检查：
请输出可能原因、优先验证顺序、低风险下一步。

这类 prompt 能让 Claude Code 更少乱猜，也能帮你把排查过程写成交付说明。

诊断结论怎么写

如果找到明确原因，可以写：“错误来自构建阶段缺少测试环境变量，当前已确认本地 build 因该配置失败；未运行生产部署；需要客户补充测试环境变量后继续验证。”

如果还没找到原因，也要写清排除项。例如“已确认不是依赖安装失败，不是脚本缺失；下一步需要客户提供接口返回原文”。排查本身也可以交付，但必须说清限制。

排查记录怎么留

每次排查都建议留一份短记录：错误出现在哪里、你看过哪些文件、运行过哪些命令、哪些原因已经排除、下一步需要什么材料。记录不需要很长，但要能让你第二天继续接上。

如果客户后续追问，你可以直接对照记录回答，而不是重新翻聊天。对新手来说，这个习惯能减少很多重复劳动。

什么时候停止继续试

如果连续两三步检查都没有新证据，就不要继续乱试命令。回到客户信息：复现是否准确，环境是否一致，错误原文是否完整，最近变更是否漏掉。

停止不是放弃，而是避免把问题弄得更乱。Claude Code 适合在证据足够时分析，不适合在信息缺失时无限猜测。

风险提醒

不要把客户报错完整原样贴进公共工具。日志里经常混有路径、账号、token 片段和内部域名。

不要看到 Claude Code 给出修复建议就马上改。先判断建议是否匹配当前环境，是否会影响更多文件，是否有测试方式。

免责声明

本文仅供学习和项目流程参考，不构成安全、法律、财务或平台合规建议。Claude Code 功能、项目规则和客户验收要求可能变化，发布前需要人工复核。项目前请确认授权、脱敏、测试环境和交付边界。

CTA：排查前用 /templates 记录错误信息；需要给客户解释诊断结果时，用 /tools/proposal-generator 起草后人工复核。