故障排除
概述
本文档汇总了使用 Claude Code 时可能遇到的常见问题及其解决方案，帮助你快速定位并解决问题。
安装和配置问题
问题1：安装失败
错误信息：
Error: EACCES: permission denied
解决方案：
# 使用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
# 或使用 sudo（不推荐）
sudo npm install -g @anthropic-ai/claude-code
问题2：认证失败
错误信息：
Authentication failed. Please check your API key.
解决方案：
- 检查环境变量配置：
echo $ANTHROPIC_AUTH_TOKEN
- 更新配置文件：
# 编辑 ~/.claude/settings.json
{
"ANTHROPIC_AUTH_TOKEN": "your-api-key"
}
- 重新登录：
claude logout
claude login
问题3：权限错误
错误信息：
Permission denied: /path/to/file
解决方案：
# 修改文件权限
chmod +x /path/to/file
# 或使用 sudo（谨慎使用）
sudo claude
工作使用问题
问题1：上下文理解偏差
症状： Claude 不理解项目结构或生成错误的代码
解决方案：
- 优化 CLAUDE.md：
# 明确技术栈
技术栈：React 18 + TypeScript + Vite
# 清晰的目录说明
src/
├── components/ # React 组件
├── pages/ # 页面组件
└── utils/ # 工具函数
# 具体的编码规范
- 使用函数组件 + Hooks
- TypeScript 严格模式
- 提供具体示例：
像这样写组件：
const Button = ({ children, onClick }) => {
return <button onClick={onClick}>{children}</button>
}
问题2：工具调用失败
错误信息：
Tool execution failed: Command not found
解决方案：
- 检查命令是否存在：
which your-command
- 在 CLAUDE.md 中说明：
## 环境要求
- Node.js 18+
- 需要全局安装：npm install -g some-tool
- 配置权限：
/allowed-tools
问题3：MCP 连接问题
症状： MCP 工具无法使用或连接失败
解决方案：
- 检查 MCP 服务器状态：
claude --mcp-debug
- 验证配置：
// ~/.claude/mcp.json
{
"mcpServers": {
"your-server": {
"url": "http://localhost:3001/mcp"
}
}
}
- 重启服务：
# 重启 MCP 服务器
npm run mcp:restart
性能问题
问题1：响应慢
症状： Claude 响应时间过长
解决方案：
- 减少上下文：
/clear # 清除历史上下文
- 优化 CLAUDE.md：
- 移除不必要的内容
- 使用引用替代长文本
- 保持 < 300 行
- 使用特定模型：
/model haiku # 使用更快的模型
问题2：内存占用高
症状： Claude 占用过多系统内存
解决方案：
- 定期清理：
/compact # 压缩上下文
- 限制上下文窗口：
{
"maxContextTokens": 100000
}
- 使用会话管理：
/save session-name # 保存会话
/load session-name # 恢复会话
代码生成问题
问题1：生成代码不符合规范
解决方案：
- 在 CLAUDE.md 中明确规范：
## 编码规范
- 使用 2 空格缩进
- 函数命名使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 提供代码示例：
// 正确示例
const calculateTotal = (items) => {
return items.reduce((sum, item) => sum + item.price, 0)
}
- 使用 Rules 强制约束：
<!-- .claude/rules/always/coding-style.md -->
---
name: coding-style
type: always
---
1. 必须使用 TypeScript
2. 所有函数需要类型注解
3. 使用 ES6+ 语法
问题2：测试代码生成错误
解决方案：
- 指定测试框架：
## 测试规范
- 使用 Jest + React Testing Library
- 测试文件命名：*.test.tsx
- 覆盖率要求：> 80%
- 提供测试模板：
// 组件测试模板
import { render, screen } from '@testing-library/react'
import { ComponentName } from './ComponentName'
describe('ComponentName', () => {
it('renders correctly', () => {
render(<ComponentName />)
expect(screen.getByText('expected text')).toBeInTheDocument()
})
})
Git 集成问题
问题1：提交信息生成不理想
解决方案：
- 配置提交模板：
## Git 提交规范
使用 Conventional Commits 格式：
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式
- refactor: 重构
- test: 测试相关
- 提供示例：
生成这样的提交信息：
feat(auth): 添加 OAuth2 登录功能
- 实现 Google OAuth 集成
- 添加登录状态管理
- 更新用户信息 API
问题2：分支操作混乱
解决方案：
- 定义分支策略：
## 分支命名规范
- feature/功能描述
- fix/问题描述
- hotfix/紧急修复
- release/版本号
- 使用工作流命令：
<!-- .claude/commands/create-feature.md -->
创建新功能分支：
1. git checkout main
2. git pull
3. git checkout -b feature/功能名
4. git push -u origin feature/功能名
环境特定问题
Windows 问题
- 路径分隔符：
// 使用 path 模块处理路径
const path = require('path')
const fullPath = path.join(__dirname, 'folder', 'file.js')
- 命令差异：
# Windows 使用 &&
npm run build && npm run test
# 避免 Unix 特定命令
# ❌ rm -rf folder
# ✅ rimraf folder
macOS 问题
- 权限问题：
# 修复权限
sudo chown -R $(whoami) ~/.claude
- 环境变量：
# 添加到 shell 配置
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.zshrc
source ~/.zshrc
Linux 问题
- 依赖缺失：
# Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential
# CentOS/RHEL
sudo yum groupinstall "Development Tools"
获取帮助
内置帮助
/help # 查看所有命令
/doctor # 诊断常见问题
/status # 查看当前状态
/feedback # 提交反馈
日志和调试
# 启用调试模式
claude --debug
# 查看详细日志
tail -f ~/.claude/logs/claude.log
社区资源
- 官方文档：https://docs.anthropic.com/claude/docs
- GitHub Issues：https://github.com/anthropics/claude-code/issues
- 社区论坛：搜索 Claude Code 相关讨论
预防措施
1. 定期更新
# 检查更新
claude --version
npm update -g @anthropic-ai/claude-code
2. 备份配置
# 备份重要配置
cp -r ~/.claude ~/.claude.backup
3. 测试环境
在生产环境使用前：
- 在测试项目验证
- 检查所有功能正常
- 确认配置正确
紧急恢复
重置配置
# 完全重置
rm -rf ~/.claude
claude login
恢复工作区
# 回退到上一个工作状态
git checkout -- .
git clean -fd