附录 F：常见问题排查指南

安装与启动

VSCode 扩展无法安装

症状：在 VSCode 扩展市场搜索不到 Claude Code 扩展，或安装后扩展未激活。

原因：

VSCode 版本过低（需 1.82+）
网络代理或防火墙阻止扩展市场访问
扩展与现有插件冲突

解决方案：

升级 VSCode 到最新版本（Code > Check for Updates）
检查网络代理设置，确保 https://marketplace.visualstudio.com 可访问
尝试通过命令行安装：code --install-extension anthropic.claude-code
暂时禁用其他 AI 编程扩展（如 Copilot、Cody），排查冲突

CLI 命令找不到

症状：终端中运行 claude 提示 command not found。

原因：

Node.js 未安装或版本过低（需 18+）
npm 全局安装路径未加入 PATH
使用 pnpm/npx 安装时链接未正确创建

解决方案：

确认 Node.js 版本：node --version，需 ≥ 18
确认安装状态：npm list -g @anthropic-ai/claude-code
重新安装：npm install -g @anthropic-ai/claude-code
检查 PATH：echo $PATH，确认 npm 全局 bin 目录在其中（通常是 ~/.npm-global/bin 或 /usr/local/bin）
重启终端使 PATH 生效

首次启动认证失败

症状：运行 claude 后浏览器打开 OAuth 页面，但授权后终端仍提示未认证。

原因：

浏览器网络环境与终端不同（如终端走代理但浏览器不走）
Anthropic 账号未完成 API 额度开通
OAuth 回调端口被占用或防火墙阻止

解决方案：

确认已在 console.anthropic.com 完成账号注册和 API Key 生成
使用 API Key 直接认证：运行 claude login --api-key 并粘贴你的 key
检查防火墙是否放行本地回环端口（通常是 45454）
尝试 claude logout 后重新 claude login

模型与 API

API 调用超时

症状：Claude 响应时间过长，最终显示超时错误，或操作中断。

原因：

网络延迟过高（尤其是国内访问 Anthropic API）
请求上下文过大，模型处理时间增加
Anthropic 服务端负载高或正在维护
本地代理配置不当导致连接不稳定

解决方案：

检查 Anthropic 服务状态：访问 status.anthropic.com
缩小上下文：使用 /compact 压缩对话历史，或减少 .claude/settings.json 中 permissions.allow 的文件范围
优化代理设置：如使用代理，确保为 HTTPS 长连接优化，建议使用 HTTP/2 代理
设置更长的超时时间：在 .claude/settings.json 中调整 timeout 字段（单位毫秒）
如果是企业用户，联系 Anthropic 销售开通专用带宽

Token 配额耗尽

症状：API 返回 429 错误，提示 rate limit 或 quota exceeded。

原因：

达到 API Key 的速率限制（按 RPM/TPM 计）
月度配额已用完
并发请求过多

解决方案：

查看当前用量：console.anthropic.com > API Keys > Usage
降低对话频率，避免短时间内发送大量请求
使用 /compact 减少上下文 token 消耗
升级 API 套餐或在 console 中申请提额
对于团队使用，建议为每个开发者创建独立 API Key 以分散配额

模型响应质量差

症状：Claude 给出的回答不准确、不完整，或产生幻觉。

原因：

使用的模型版本过旧（如 Claude 3 Haiku）
提示词不够明确，缺少必要上下文
对话历史过长导致注意力分散
CLAUDE.md 缺少关键项目信息

解决方案：

确认当前使用的模型：检查 .claude/settings.json 中的 model 字段，或在对话中用 /model 查看
切换到更强大的模型：/model 选择 Claude 4 Sonnet 或 Opus
优化 CLAUDE.md：补充项目架构、常用命令和编码规范，帮助 Claude 理解上下文
使用 /compact 清除无关对话，保留关键决策信息
将复杂问题拆分为多个简单问题逐步解决
在对话中使用 @file 明确指定需要关注的文件

cc-switch 模型切换无效

症状：运行 cc-switch 命令后，实际使用的模型未变化。

原因：

配置文件路径错误或权限不足
多个配置文件冲突（全局 vs 项目级）
目标模型在你的 API 层级不可用
VSCode 扩展缓存了旧配置未刷新

解决方案：

手动检查配置文件：cat ~/.claude/settings.json 和项目目录下 .claude/settings.json
确认目标模型在你的 API tier 中可用（console.anthropic.com > Limits）
运行 claude --version 确认 CLI 版本支持目标模型
VSCode 用户：重启扩展或执行 Cmd+Shift+P > Developer: Reload Window
如配置文件冲突，项目级配置优先，删除或合并全局配置中的模型设置

权限问题

操作被拒绝但应该允许

症状：Claude 拒绝执行某个操作（如读取文件、运行命令），提示权限不足。

原因：

项目 .claude/settings.json 中的 permissions.deny 列表包含了该操作
全局 ~/.claude/settings.json 继承了拒绝策略
该操作类型的默认行为是"先询问后执行"，响应超时被当作拒绝

解决方案：

检查项目 .claude/settings.json 和全局 ~/.claude/settings.json 中的 permissions.deny 配置

如需允许，将对应命令或路径添加到 permissions.allow：

json

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Read(/path/to/project/**)"
    ]
  }
}

使用更具体的 allow 规则可覆盖 deny 规则
确认操作类型在 .claude/settings.json 中未被设为 "ask"（需用户确认），如不需要确认可设为 "allow"

权限弹窗太多

症状：每次操作都弹出确认对话框，严重影响工作效率。

原因：

项目配置中将多个常用操作设置为"始终询问"模式
未配置 .claude/settings.json，Claude 对高风险操作默认需要确认
权限规则写得太宽泛，每次匹配到的路径不同

解决方案：

在项目 .claude/settings.json 中配置常用操作的自动允许：

json

{
  "permissions": {
    "allow": [
      "Bash(git diff:*)",
      "Bash(git status:*)",
      "Bash(npm run:*)",
      "Read(./src/**)",
      "Write(./src/**)"
    ]
  }
}

使用通配符 * 和 ** 匹配多路径，减少逐条配置
对于完全不希望被允许的操作，在 deny 中明确声明，避免触发确认
运行 claude --dangerously-skip-permissions 在可信项目中跳过所有权限检查（仅限临时使用）

危险操作没有被阻止

症状：Claude 执行了你不希望它执行的危险操作，如删除了重要文件。

原因：

permissions.allow 配置过于宽松，匹配到了危险操作
全局配置中的 deny 规则不够全面
未使用 permissions.deny 明确禁止特定操作

解决方案：

在 permissions.deny 中添加危险操作黑名单：

json

{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Write(./.env)",
      "Write(./.git/**)"
    ]
  }
}

使用版本控制（Git），危险操作后可通过 git checkout 恢复
定期审查 .claude/settings.json 中的权限规则，确保 allow 规则不过度宽松
在 settings.json 中设置 "permissionMode": "default" 恢复默认安全策略

上下文问题

Claude 忘记之前的对话

症状：对话进行到一半，Claude 突然不记得之前讨论过的内容。

原因：

对话 token 数超过了模型上下文窗口（自动压缩时丢弃了较早的消息）
手动或自动 /compact 压缩掉了关键信息
会话被中断后恢复（如网络断开重连），部分历史丢失

解决方案：

使用 /compact 前手动检查压缩摘要——确认关键信息被保留，否则取消并在提示中重申
在 CLAUDE.md 中记录持久化的项目上下文（架构、约定），这部分不会被压缩
将重要的阶段性结论写入项目文档或 TODO，而非仅保留在对话中
开启长对话时，定期要求 Claude 回顾并总结当前进度，将总结写入 PLAN.md 或项目文件中
使用 /context 查看当前上下文使用情况，在接近上限前提早规划

上下文用量过大

症状：对话初始响应很快，但随着对话推进越来越慢，/context 显示接近或达到上限。

原因：

对话中包含了过多的大文件内容
大量中间输出（如反复测试的日志）留在上下文中
未及时压缩，冗余信息占据窗口

解决方案：

定期运行 /compact 压缩对话，保留摘要
避免一次性读取过多大文件；使用 grep 定位关键部分再读取
将阶段性输出写入文件（用 Write 工具），而不是全部留在对话中
开启新对话处理独立任务，而非在一个长对话中完成所有事
在 CLAUDE.md 中写好项目背景，减少每次对话需要加载的冗余上下文
使用 /context 监控用量，提前规划压缩时机

/compact 后丢失关键信息

症状：执行 /compact 后，Claude 不再知道之前讨论的重要细节。

原因：

自动生成的压缩摘要没有包含你认为重要的信息
压缩算法无法识别哪些是"关键信息"，仅按通用策略保留摘要
压缩后模型上下文被清空，只保留压缩摘要

解决方案：

在压缩前，手动要求 Claude 总结当前进展的关键信息，并写入文件或明确告知"请记住以下几点"
压缩后立即测试：问 Claude 一个只有在前段对话中才讨论过的细节，看是否还记得
如果不满意压缩结果，使用 Git 恢复对话前的状态（如对话日志有备份）
将重要信息持久化：写入项目 CLAUDE.md、TODO.md 或在对话中明确要求 Claude 在压缩后主动回顾关键约束
考虑在关键决策点开新对话，而非无限延长单次对话

代码编辑问题

Claude 修改了不该改的文件

症状：Claude 在解决一个问题时，修改了无关文件或产生了意料之外的变更。

原因：

任务描述不够精确，Claude 自行扩大了修改范围
CLAUDE.md 中缺乏代码规范说明，Claude 按自身理解做了格式化或重构
上下文中有误导性的信息，引导 Claude 做出错误判断

解决方案：

明确指定只修改哪些文件：例如 "只修改 src/utils.ts，不要动其他文件"
在 CLAUDE.md 中说明项目的代码风格规范，禁止自动格式化
使用 Git 审查每次 Claude 的变更：git diff 检查变更范围
每次修改后立即提交，避免积累过多未审查的变更
如果发生意外修改，使用 git checkout -- <file> 恢复未预期的变更

Diff 显示异常

症状：Claude 生成的 diff 无法正常应用，或显示的变更与实际不符。

原因：

文件在 Claude 修改期间被外部程序改动（如编辑器自动保存）
文件编码问题（如 UTF-8 BOM、CRLF vs LF）
diff 中的上下文行数与文件当前状态不匹配

解决方案：

在 Claude 修改文件前，保存并关闭其他编辑器中的该文件
统一文件编码和换行符：在项目根目录配置 .editorconfig：
```
root = true
[*]
charset = utf-8
end_of_line = lf
```
使用 git diff 查看实际变更，手动解决冲突
如果 diff 应用失败，将当前文件内容提供给 Claude，要求其基于最新内容重新生成修改

内联编辑不触发

症状：在 VSCode 中选中代码后，内联编辑 (Inline Edit) 功能没有弹出或无法使用。

原因：

Claude Code 扩展未激活或需要重新加载
内联编辑功能在当前文件类型/语言中不支持
VSCode 快捷键冲突
扩展版本过旧，尚未支持该功能

解决方案：

确认扩展已激活：VSCode 状态栏应显示 Claude 图标，点击可查看状态
重新加载窗口：Cmd+Shift+P > Developer: Reload Window
检查快捷键绑定：内联编辑默认快捷键为 Cmd+I（Mac）/ Ctrl+I（Windows），确认未被其他扩展占用
更新扩展到最新版本
尝试在 .ts, .js, .py, .md 等已验证支持的文件类型中测试
如仍无效，使用终端模式 /edit 命令作为替代

性能问题

Claude 响应很慢

症状：发送消息后，等待很长时间才能收到 Claude 的回复。

原因：

上下文过大，模型处理时间长
网络到 Anthropic API 的延迟高
使用的模型较重（如 Opus 比 Sonnet 慢）
Anthropic 服务端排队（高峰时段）
本地项目中大型文件的索引导致预处理延迟

解决方案：

使用 /context 检查当前 token 用量，如接近上限则 /compact
切换到更快的模型：/model 选择 Claude 4 Sonnet（比 Opus 快 2-3 倍）
测试网络延迟：curl -w "\ntime_total: %{time_total}s\n" https://api.anthropic.com/v1/messages
避免在高峰时段使用（北美上午 9-12 点 PT 为高峰）
使用 --model 参数指定模型跳过自动检测
将项目中的大型非必要文件加入 .gitignore 或 .claudeignore 减少索引范围

大项目加载慢

症状：在大型项目中启动 Claude 或切换会话时，初始化/索引阶段耗时很长。

原因：

项目中文件数量庞大（node_modules、dist 等未排除）
CLAUDE.md 中引用了大量文件或目录
项目配置文件（如 tsconfig.json）解析复杂

解决方案：

创建 .claudeignore 文件排除不需要索引的目录：
```
node_modules/
.vitepress/dist/
.git/
*.min.js
*.map
```
精简 CLAUDE.md：移除不必要的文件引用，保持简洁的项目概述
使用 /add-dir 逐步添加工作目录，而非在启动时索引整个项目
对大型 monorepo，在子包目录中创建独立的 .claude/settings.json，分而治之
定期清理项目：删除未使用的依赖、构建产物和临时文件

频繁超时

症状：Claude 操作（读文件、执行命令、等待 API 响应）频繁超时。

原因：

网络不稳定，丢包率高
代理服务器连接池耗尽
请求的 token 数量巨大
本地系统资源不足（内存、CPU）

解决方案：

检查网络稳定性：ping -c 20 api.anthropic.com 观察丢包率
如使用代理，检查代理服务器状态和连接数限制
减少单次请求的 token 量：分批处理大量文件，而非一次性全部读取
在 .claude/settings.json 中增加超时时间：
json
```
{
  "timeout": 120000
}
```
关闭其他占用网络带宽的应用（视频会议、大文件下载）
检查系统资源：确保有足够的空闲内存（建议 ≥ 4GB），CPU 负载不过高
尝试切换到不同的网络（如从 Wi-Fi 切换到有线，或更换 DNS）

附录 F：常见问题排查指南 ​

安装与启动 ​

VSCode 扩展无法安装 ​

CLI 命令找不到 ​

首次启动认证失败 ​

模型与 API ​

API 调用超时 ​

Token 配额耗尽 ​

模型响应质量差 ​

cc-switch 模型切换无效 ​

权限问题 ​

操作被拒绝但应该允许 ​

权限弹窗太多 ​

危险操作没有被阻止 ​

上下文问题 ​

Claude 忘记之前的对话 ​

上下文用量过大 ​

/compact 后丢失关键信息 ​

代码编辑问题 ​

Claude 修改了不该改的文件 ​

Diff 显示异常 ​

内联编辑不触发 ​

性能问题 ​

Claude 响应很慢 ​

大项目加载慢 ​

频繁超时 ​

附录 F：常见问题排查指南

安装与启动

VSCode 扩展无法安装

CLI 命令找不到

首次启动认证失败

模型与 API

API 调用超时

Token 配额耗尽

模型响应质量差

cc-switch 模型切换无效

权限问题

操作被拒绝但应该允许

权限弹窗太多

危险操作没有被阻止

上下文问题

Claude 忘记之前的对话

上下文用量过大

/compact 后丢失关键信息

代码编辑问题

Claude 修改了不该改的文件

Diff 显示异常

内联编辑不触发

性能问题

Claude 响应很慢

大项目加载慢

频繁超时