Claude Code 常见问题与解决方案

本文整理了 Claude Code 使用过程中最常见的 30 个问题，按问题类型分类，提供可操作的解决方案。

一、安装与配置问题

Q1：npm 安装报错 EACCES 或 permission denied

原因：npm 全局目录无写权限
解决方案：

# 方法1：配置 npm 权限目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# 方法2：使用 nvm 安装 Node.js
nvm install 20 && nvm use 20
npm install -g @anthropic-ai/claude-code

Q2：claude: command not found

解决方案：

# 确认安装位置
npm list -g @anthropic-ai/claude-code

# 查找实际路径
npm config get prefix

# 添加到 PATH
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Q3：API Key 无效或被拒绝

原因：Key 格式错误、余额不足、地区限制
解决方案：

1. 确认 Key 以 sk-ant-api03- 开头
2. 检查 console.anthropic.com 账户余额
3. 确认已接受服务条款
4. 尝试重新生成 Key

二、网络与代理问题

Q4：代理设置后仍然无法连接

解决方案：

# 检查代理是否生效
env | grep -i proxy

# 测试 API 连通性
curl -I https://api.anthropic.com \
  --proxy http://127.0.0.1:7890

# Claude Code 使用代理
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
claude -p "测试连接"

Q5：国内用户访问 Anthropic API 超时

解决方案：

# 使用国内可访问的代理
export https_proxy=http://your-proxy:port

# 或使用环境变量配置代理
export ANTHROPIC_API_KEY="your-key"

# 验证连接
claude -p "ping" --allowedTools "Bash"

三、使用中的问题

Q6：Claude Code 生成的代码编译失败

原因：AI 对项目上下文理解不完整，或对语言特性不熟悉
解决方案：

1. 在 CLAUDE.md 中补充项目技术栈信息
2. 提供相关代码示例作为参考
3. 分步骤执行，每次验证后再继续
4. 使用 --allowedTools 限制操作范围

Q7：Claude 不读取我的 CLAUDE.md

解决方案：

1. 确认文件在当前工作目录或父目录
2. 文件名必须精确为 CLAUDE.md（大小写敏感）
3. 检查文件格式是否为标准 Markdown
4. 确认文件可读：cat CLAUDE.md

Q8：上下文过长导致 AI 回答质量下降

解决方案：

# 手动压缩上下文
claude -p "/compact"

# 设置自动压缩
# 在 ~/.claude/settings.json 中：
{
  "autoCompact": true,
  "compactThreshold": 4000
}

Q9：Claude 删除了我的代码

原因：未使用 --allowedTools 限制，或 CLAUDE.md 中未配置保护规则
解决方案：

1. 立即使用 Git 恢复：git checkout -- .
2. 配置 ~/.claude/settings.json：

{
  "dangerousTools": ["Write", "Bash"],
  "confirmBeforeDestructive": true
}

3. 在 CLAUDE.md 中添加保护规则：

## 禁止行为
- 禁止重写 100 行以上的文件
- 禁止删除非临时文件

Q10：Claude 执行了错误的命令

解决方案：

1. 使用 /undo 回退上一次操作
2. Git 恢复：git restore .
3. 审查 CLAUDE.md 中的命令白名单

四、Bash 命令问题

Q11：Bash 命令执行报错但我认为是对的

原因：Claude 对命令参数顺序或选项不熟悉
解决方案：

1. 使用 Bash 工具执行并查看实际错误
2. 手动执行确认命令本身正确
3. 提供更明确的命令规范

Q12：长时间运行命令导致超时

解决方案：

# 使用 timeout 设置超时时间
claude -p "编译项目" --allowedTools "Bash"

# 对于超长任务，使用后台执行
nohup ./long-task.sh &

五、权限与安全

Q13：–dangerously-skip-permissions 安全吗

结论：不安全，仅用于隔离测试环境
安全使用原则：

• 仅在容器化或 VM 环境中使用
• 不在有生产数据的机器上使用
• 配合 allowedCommands 白名单使用

Q14：如何防止 AI 执行危险命令

配置方案：

// ~/.claude/settings.json
{
  "blockedCommands": [
    "rm -rf /",
    "drop database",
    "git push --force origin main",
    ":(){:|:&};:"
  ],
  "dangerousTools": ["Bash", "Write"]
}

六、Skill 与自定义

Q15：Skill 触发后不生效

原因：trigger 关键词未匹配
解决方案：

1. 检查 Skill 文件中的 trigger 数组
2. 使用精确的触发词而非模糊匹配
3. 确认 Skill 文件在 ~/.claude/skills/ 目录

Q16：多个 Skill 同时触发

解决方案：

// 在 skill 中设置优先级
module.exports = {
  name: "Go Expert",
  priority: 10,  // 数字越高优先级越高
  // ...
};

七、付费与账号

Q17：Claude Code 是否免费

答案：Claude Code 需要有效的 API Key，按 token 用量付费。使用 Claude Max 订阅可获得更高的使用配额和优先访问。

Q18：如何查看 API 使用量

解决方案：

1. 访问 console.anthropic.com/dashboard
2. 查看 Usage 标签页
3. 设置预算提醒

八、与其他工具集成

Q19：与 GitLab/Gitea 集成

# 配置 Git 主机
git config --global url."https://".insteadOf "git://"

# 使用 HTTPS 克隆仓库
git clone https://your-gitlab.com/repo.git

Q20：与 Docker 开发环境集成

# 在 Docker 容器中使用
docker exec -it my-dev-container claude -p "运行测试"

# 持久化配置
docker exec my-dev-container sh -c 'echo "export ANTHROPIC_API_KEY=xxx" >> ~/.bashrc'

九、性能问题

Q21：Claude Code 响应很慢

解决方案：

1. 检查网络延迟：ping api.anthropic.com
2. 减少上下文长度：清理不必要的文件
3. 使用本地缓存加速
4. 考虑使用更近的代理服务器

Q22：大量文件操作时卡死

解决方案：

# 使用 Glob 限制文件范围
claude -p "审查代码" --allowedTools "Read,Grep,Glob"

# 避免一次性处理大量文件
claude -p "分批审查 /pkg 下的 Go 文件" --allowedTools "Read,Glob,Bash"

十、最佳实践建议

场景	建议
新项目	先写 CLAUDE.md，再开始编码
Bug 修复	优先使用 /debug skill
代码审查	限制 Read/Grep/Glob 权限
长时间任务	使用 tmux 保持会话
生产环境	永远不使用 –dangerously-skip-permissions

遇到不在此列表中的问题，可通过 /help 查看 Claude Code 内置帮助，或在 GitHub Issues 反馈。

相关外部链接

资源	链接	说明
Claude Code 官方文档	https://docs.anthropic.com/zh-CN/claude-code	问题解决参考
Anthropic API 状态	https://status.anthropic.com	API 服务状态
Anthropic 帮助中心	https://support.anthropic.com	官方技术支持
Claude Code GitHub Issues	https://github.com/anthropics/claude-code/issues	常见问题反馈和解决方案