Claude Code 启动后没有反应怎么办？

先记录完整终端输出、系统和运行时版本、当前目录及账号状态，再按环境、登录、网络和项目配置逐层排查。不要只根据最后一行错误反复重装。

Claude Code 找不到项目文件怎么办？

先确认当前工作目录、文件是否被忽略、路径是否正确，以及工具实际读取了哪些文件。应先使用只读检查，不要立即扩大访问权限。

Claude Code 修改结果不对怎么办？

先停止继续编辑，保存当前 diff 和测试结果，核对任务范围与上下文，再在隔离分支中回退或修正。不要让工具通过连续覆盖来掩盖第一次错误。

Claude Code 报错怎么办？安装、登录、上下文和权限问题排查清单

Claude Code 报错时，最有效的方法不是搜索一个“万能修复命令”，而是先把问题归类。安装、登录、网络、项目上下文和文件权限属于不同层次；如果把它们混在一起处理，往往会越改越乱。

先保存现场，再开始排查

遇到问题后先记录：

完整错误信息，而不是只截最后一行。
Windows、macOS 或 Linux 以及系统版本。
当前终端、运行时和包管理器版本。
执行命令时所在的工作目录。
账号、工作区和当前项目分支。
最近一次成功运行的时间和之后发生的改动。

如果工具已经修改了文件，先保存 diff、日志和测试结果。不要在没有备份的情况下继续让代理批量写入。

第一层：环境与命令问题

“命令不存在”或版本检查失败

这类问题通常与安装未完成、终端路径没有刷新、多个运行时冲突或当前用户环境变量有关。建议按顺序确认：

当前终端是否在安装完成后重新打开。
系统实际找到的是哪一个可执行文件。
官方要求的运行时是否被正确识别。
当前账号是否拥有安装目录的读取权限。

不要直接以管理员身份运行所有命令。管理员权限可能暂时绕过错误，却让后续文件权限和安全边界更难管理。

安装成功但打开后立即退出

记录启动日志、运行时版本、系统安全软件提示和工作目录。检查是否混用了不同教程的配置文件，或在全局目录安装了互相冲突的版本。必要时在一个全新的、无敏感信息的测试目录复现。

第二层：登录、账号和服务问题

登录后仍提示未授权

确认登录账号、工作区和当前产品是否对应。Claude 网页订阅、API Key、第三方平台账号和 Claude Code 的使用条件不能直接等同。遇到要求把验证码交给他人代登录的页面，应立即停止。

登录页面反复跳转

检查浏览器是否完成授权、系统时间是否正确、网络是否稳定，以及当前终端是否能访问官方登录流程。不要短时间内反复尝试大量验证码或密码，以免触发额外验证。

模型或功能不可用

先确认账号套餐、地区、工作区和当前官方产品说明。不要把网上文章里出现过的模型名称复制到配置文件中，也不要把第三方平台显示的名称当作 Claude Code 官方可用名称。

第三层：网络与依赖问题

请求超时或连接中断

记录发生时间、请求阶段、网络环境和是否只在某个项目出现。先用短任务和公开内容测试，再判断是网络问题、服务状态、额度限制还是输入过大。

依赖安装失败

不要一上来删除锁文件或升级全部依赖。先确认包管理器、Node.js 或其他运行时版本、代理设置和项目锁文件，再只处理与错误直接相关的依赖。修改后运行项目原本的测试和构建。

第四层：上下文与文件问题

Claude Code 找不到文件

先确认工作目录和相对路径，再检查文件名大小写、忽略规则、子模块和权限。让工具输出它实际读取到的文件清单，并人工抽查。不要用“把整个磁盘都开放给它”解决上下文不足。

回答与项目实际情况不符

通常是读取范围不足、任务描述含糊或当前分支不对。可以让它先输出入口、调用链、相关测试和不确定项，再重新执行任务。不要让它凭常识补全业务规则。

上下文过大或回答开始重复

把任务拆成模块和阶段，先建立项目地图，再处理一个具体问题。删除与任务无关的文件和日志，避免把整个仓库无差别复制到对话中。

第五层：编辑、命令和权限问题

工具改动了不该改的文件

立即停止后续编辑，保存 diff，列出意外改动，并在隔离分支中恢复到可识别状态。之后把允许修改的文件写入任务说明，要求每轮结束后报告改动清单。

测试声称通过但你看不到结果

要求输出实际执行的命令、退出码和关键日志。模型的总结不是测试证据；需要时手动重跑关键检查。

代理想执行危险命令

涉及删除、覆盖、安装、外网访问、数据库、部署或权限变化的命令，应先阅读命令的完整内容和影响范围，再由人决定是否执行。生产环境永远不应该成为第一次试验场。

一张快速分诊表

现象	先检查	暂时不要做
命令不存在	安装、路径、终端和运行时	反复全局重装
登录失败	账号、工作区、浏览器授权	交出验证码或恢复码
请求超时	网络、服务状态、输入大小	无限重试或泄露日志
找不到文件	工作目录、忽略规则、权限	开放整个磁盘
改错文件	diff、分支、任务范围	继续批量覆盖
测试不可信	实际命令、退出码和日志	只看模型口头结论

官方错误码、命令和诊断入口可能更新，具体排查前应查看 Claude Code 当前官方 troubleshooting 文档。本站的Claude Code 中文教程可以作为工作流补充，但不替代官方文档。

结论

Claude Code 故障排查应遵循“保存现场—环境—账号—网络—上下文—权限”的顺序。分类定位、最小改动和可复现验证，比复制一条来历不明的修复命令更安全，也更容易真正解决问题。