【Claude】疑难杂症终极排查手册 — 已解决
·
【Claude】疑难杂症终极排查手册 — 已解决
适用版本：Claude Code 全版本
受影响场景：非典型错误、偶发性问题、环境冲突、性能异常、诡异行为
阅读时长：约 35 分钟
目录
1. 问题现象分类
1.1 启动类疑难
| # | 问题 | 频率 |
|---|---|---|
| 1 | Claude Code 启动后立即退出 | 偶发 |
| 2 | 启动卡在 "Initializing..." 不动 | 偶发 |
| 3 | 不同终端启动行为不一致 | 常见 |
| 4 | 升级后首次启动报配置错误 | 常见 |
1.2 运行时疑难
| # | 问题 | 频率 |
|---|---|---|
| 5 | 工具调用间歇性失败 | 偶发 |
| 6 | Claude 突然遗忘上下文 | 常见 |
| 7 | 修改文件但不保存到磁盘 | 偶发 |
| 8 | 相同输入得到不同结果 | 偶发 |
| 9 | 中文输出乱码 | 常见 |
| 10 | 进程占用 CPU 100% | 偶发 |
1.3 环境冲突疑难
| # | 问题 | 频率 |
|---|---|---|
| 11 | 多版本 Node.js 冲突 | 常见 |
| 12 | nvm/fnm 环境下找不到 claude | 常见 |
| 13 | Docker 容器内路径异常 | 偶发 |
| 14 | WSL2 中文件系统慢 | 常见 |
| 15 | macOS 权限弹窗不断出现 | 常见 |
1.4 配置疑难
| # | 问题 | 频率 |
|---|---|---|
| 16 | settings.json 被重置 | 偶发 |
| 17 | CLAUDE.md 有时加载有时不加载 | 常见 |
| 18 | Hook 有时触发有时不触发 | 偶发 |
| 19 | 权限规则不生效 | 常见 |
| 20 | 子代理调用失败 | 偶发 |
1.5 网络疑难
| # | 问题 | 频率 |
|---|---|---|
| 21 | 白天正常晚上超时 | 偶发 |
| 22 | 换 WiFi 后无法连接 | 常见 |
| 23 | SSH 到远程后 Claude 不可用 | 常见 |
| 24 | SSE 流式响应中途断开 | 偶发 |
1.6 其他疑难
| # | 问题 | 频率 |
|---|---|---|
| 25 | Git 操作后 Claude 行为异常 | 偶发 |
| 26 | 大型 monorepo 中极慢 | 常见 |
| 27 | 并发会话互相干扰 | 偶发 |
| 28 | 内存泄漏导致崩溃 | 偶发 |
| 29 | 输出包含 HTML 标签 | 偶发 |
| 30 | 时间戳/时区错误 | 偶发 |
2. 原理深挖：疑难问题诊断方法论
2.1 诊断决策树
问题发生
│
├─ 是启动问题?
│ ├─ 检查 Node.js 版本 (node --version)
│ ├─ 检查 claude 安装 (which claude)
│ ├─ 检查配置文件 (cat .claude/settings.json)
│ └─ 查看启动日志 (claude --verbose)
│
├─ 是运行时问题?
│ ├─ 检查会话日志 (~/.claude/projects/.../sessions/)
│ ├─ 检查 Hook 是否报错 (stderr)
│ ├─ 检查磁盘空间 (df -h)
│ └─ 检查内存 (top/Activity Monitor)
│
├─ 是环境问题?
│ ├─ 检查 PATH (echo $PATH)
│ ├─ 检查 nvm/fnm (which node)
│ ├─ 检查终端差异 (对比 .zshrc vs .bashrc)
│ └─ 检查权限 (ls -la .claude/)
│
├─ 是网络问题?
│ ├─ 检查 DNS (dig api.anthropic.com)
│ ├─ 检查代理 (echo $HTTPS_PROXY)
│ ├─ 检查 TLS (openssl s_client)
│ └─ 检查防火墙
│
└─ 是配置问题?
├─ 检查 JSON 格式 (python3 -m json.tool)
├─ 检查权限规则语法
├─ 检查 Hook 脚本路径
└─ 检查 CLAUDE.md 位置
2.2 信息收集清单
排查任何问题前，收集以下信息:
1. 系统信息
- OS: uname -a / sw_vers
- Shell: echo $SHELL
- Node.js: node --version
- Claude Code: claude --version
2. 环境信息
- PATH: echo $PATH
- 代理: env | grep -i proxy
- API Key: echo $ANTHROPIC_API_KEY | head -c 10
- 工作目录: pwd
3. 配置信息
- 项目配置: cat .claude/settings.json
- 全局配置: cat ~/.claude/settings.json
- CLAUDE.md: head -20 CLAUDE.md
- .gitignore: cat .gitignore
4. 运行时信息
- 磁盘空间: df -h
- 内存: ps aux | grep claude
- 会话日志: ls ~/.claude/projects/
- 错误输出: claude --verbose 2>&1 | head -50
5. 复现步骤
- 精确的操作步骤
- 预期 vs 实际结果
- 是否可稳定复现
- 是否最近升级/变更
2.3 日志位置速查
日志类型 位置 用途
──────────────────────────────────────────────────────────────────
会话日志 ~/.claude/projects/<hash>/sessions/ 对话历史
全局配置 ~/.claude/settings.json 全局设置
项目配置 .claude/settings.json 项目设置
个人配置 .claude/settings.local.json 个人覆盖
Hook 日志 .claude/audit/ (自定义) 操作审计
成本日志 .claude/costs/ (自定义) 成本追踪
Verbose 输出 stderr (--verbose) 实时调试
Node.js 日志 ~/.npm/_logs/ 安装日志
Shell 历史 ~/.zsh_history / ~/.bash_history 命令历史
3. 根因分析：30 个疑难杂症
3.1 启动后立即退出
根因：配置文件 JSON 语法错误，Claude Code 解析失败后退出。
诊断：
python3 -m json.tool .claude/settings.json
# 如果报错，说明 JSON 格式有问题
解决：修复 JSON 语法（多余逗号、缺少引号等）。
3.2 启动卡在 "Initializing..."
根因：网络连接超时，Claude Code 在初始化时尝试连接 API 但失败。
诊断：
curl -v --connect-timeout 5 https://api.anthropic.com/v1/health
解决：检查网络/代理配置，参考第 57 篇。
3.3 不同终端行为不一致
根因：不同终端加载不同的 shell 配置文件（.zshrc vs .bash_profile），环境变量不一致。
诊断：
# 在两个终端分别运行
env | grep -i claude
env | grep -i anthropic
env | grep -i proxy
解决：统一环境变量配置到 .zshrc 和 .bashrc。
3.4 升级后配置错误
根因：新版本配置 schema 变更，旧配置不兼容。参考第 55 篇。
3.5 工具调用间歇性失败
根因：Hook 脚本执行超时或报错，导致工具调用被阻塞。
诊断：
# 直接测试 Hook 脚本
echo '{"tool_name":"Read","tool_input":{"file_path":"test.txt"}}' | \
python3 .claude/hooks/audit-pre-tool.py
解决：确保 Hook 脚本总是 exit(0)，不阻塞操作。
3.6 Claude 遗忘上下文
根因：会话过长，超出上下文窗口，早期对话被截断。
诊断：检查会话轮数和 Token 消耗。
解决：定期使用 /compact 压缩上下文，或开启新会话。
3.7 修改文件但不保存
根因：Claude Code 的 Edit 操作在内存中完成，但写入磁盘时权限不足或路径错误。
诊断：
# 检查文件权限
ls -la src/target-file.ts
# 检查磁盘空间
df -h
解决：确保文件可写，磁盘有空间。
3.8 相同输入不同结果
根因：Claude 是概率模型，相同输入会产生不同输出（temperature > 0）。
解决：这是正常行为。如需确定性，使用低 temperature 或固定 seed（SDK）。
3.9 中文输出乱码
根因：终端编码不是 UTF-8，或 Node.js 的输出编码不正确。
诊断：
echo $LANG $LC_ALL
locale
解决：
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
3.10 CPU 100%
根因：MCP 服务器进程异常、Node.js 事件循环阻塞、或 Hook 脚本死循环。
诊断：
ps aux | grep -E "claude|node|mcp" | sort -k3 -rn
解决：杀掉异常进程，检查 Hook/MCP 脚本是否有死循环。
3.11 多版本 Node.js 冲突
根因：nvm/fnm 切换 Node.js 版本后，全局安装的 claude 在新版本下不存在。
诊断：
which node
which claude
nvm list
解决：在默认 Node.js 版本下安装 claude，或用 nvm alias default 20。
3.12 nvm 环境找不到 claude
根因：nvm 的 Node.js 路径不在系统 PATH 中，Claude Code 的全局 bin 目录未加入。
解决：
# 确保 nvm 加载
source ~/.nvm/nvm.sh
nvm use 20
npm install -g @anthropic-ai/claude-code
3.13 Docker 容器内路径异常
根因：Docker 容器内工作目录与宿主机不同，Claude Code 的相对路径解析错误。
解决：在容器内使用绝对路径，或在 WORKDIR 中运行。
3.14 WSL2 文件系统慢
根因：WSL2 跨文件系统访问（/mnt/c/）性能差，Claude Code 读取 Windows 文件慢。
解决：将项目放在 WSL2 原生文件系统（~/projects/），不在 /mnt/c/ 下工作。
3.15 macOS 权限弹窗不断
根因：Claude Code 的 Bash 工具执行命令时触发 macOS 的安全机制（TCC）。
解决：在「系统设置 → 隐私与安全性 → 完全磁盘访问权限」中添加终端应用。
3.16 settings.json 被重置
根因：Claude Code 升级时自动迁移配置，覆盖了手动修改。
解决：升级前备份配置，升级后检查是否被覆盖。
3.17 CLAUDE.md 有时加载有时不加载
根因：CLAUDE.md 的加载依赖工作目录。如果在子目录运行 claude，可能找不到根目录的 CLAUDE.md。
诊断：
# 确认 CLAUDE.md 位置
find . -name "CLAUDE.md" -maxdepth 3
解决：始终在项目根目录运行 claude，或在子目录创建 CLAUDE.md。
3.18 Hook 有时不触发
根因：Hook 的 matcher 配置不匹配工具名，或 Hook 脚本路径在特定环境下不正确。
诊断：检查 Hook matcher 和脚本路径。
解决：使用 "matcher": "*" 匹配所有工具，确保脚本路径使用绝对路径。
3.19 权限规则不生效
根因：权限规则的 glob 模式不正确，或规则在 settings.local.json 中被覆盖。
诊断：
# 检查所有配置层级的权限
python3 -c "
import json, os
for f in ['.claude/settings.json', '.claude/settings.local.json', os.path.expanduser('~/.claude/settings.json')]:
if os.path.exists(f):
with open(f) as fh:
data = json.load(fh)
perms = data.get('permissions', {})
print(f'{f}: allow={perms.get(\"allow\",[])}, deny={perms.get(\"deny\",[])}')
"
解决：确保 glob 模式正确（如 Read(src/**) 而非 Read(src/*)）。
3.20 子代理调用失败
根因：子代理配置 JSON 格式错误、权限不足、或模型名弃用。
诊断：
python3 -m json.tool .claude/agents/my-agent.json
解决：修复 JSON 格式，更新模型名，检查权限配置。
3.21 白天正常晚上超时
根因：网络高峰期（晚上）代理服务器负载高或 API 限流。
解决：错峰使用，或配置重试机制。
3.22 换 WiFi 后无法连接
根因：不同 WiFi 网络的 DNS 和代理配置不同。
解决：检查新网络的代理和 DNS 配置，更新环境变量。
3.23 SSH 远程后 Claude 不可用
根因：SSH 会话不继承本地环境变量（API Key、代理等）。
解决：
# 在远程服务器上配置
export ANTHROPIC_API_KEY="sk-ant-xxx"
# 或用 SSH 转发环境变量
ssh -o SendEnv=ANTHROPIC_API_KEY user@remote
3.24 SSE 流式中途断开
根因：代理服务器超时、网络不稳定、或防火墙中断长连接。参考第 53 篇。
3.25 Git 操作后行为异常
根因：git checkout/git stash 后，项目文件变化但 Claude Code 的缓存上下文还是旧版本。
解决：Git 操作后开启新会话或使用 /compact。
3.26 大型 monorepo 极慢
根因：monorepo 中文件数量巨大，Claude Code 的文件搜索和上下文加载慢。
解决：
- 配置
.claudeignore排除不相关目录
- 用子代理限定工作范围
- 在子项目目录中运行 claude
3.27 并发会话互相干扰
根因：多个 Claude Code 会话同时操作同一项目，文件锁冲突或配置覆盖。
解决：使用 Git Worktree 为每个会话创建独立工作目录。参考第 43 篇。
3.28 内存泄漏崩溃
根因：超长会话（100+ 轮）导致 Node.js 内存堆积。
诊断：
# 监控内存
ps -o pid,rss,vsz,command -p $(pgrep -f claude)
解决：定期开新会话，避免超长对话。设置 --max-turns 限制。
3.29 输出包含 HTML 标签
根因：Claude 的输出中偶尔包含 markdown/HTML，终端不解析。
解决：这是 Claude 的正常输出格式。如果影响阅读，在提示中要求 "纯文本输出，不要使用 HTML 标签"。
3.30 时间戳/时区错误
根因：系统时区配置不正确，或会话日志使用 UTC 而本地显示用本地时区。
解决：
# 检查时区
date
timedatectl # Linux
systemsetup -gettimezone # macOS
4. 多方案解决：分场景排错
4.1 终极诊断脚本
#!/bin/bash
# ultimate-diagnose.sh — Claude Code 终极诊断
echo "============================================"
echo " Claude Code 终极诊断报告"
echo " 生成时间: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
echo "============================================"
# 1. 系统信息
echo ""
echo "=== 1. 系统信息 ==="
echo "OS: $(uname -s) $(uname -r)"
echo "Arch: $(uname -m)"
echo "Shell: $SHELL"
echo "User: $(whoami)"
echo "PWD: $(pwd)"
# 2. Node.js 环境
echo ""
echo "=== 2. Node.js 环境 ==="
echo "Node.js: $(node --version 2>/dev/null || echo '✗ 未安装')"
echo "npm: $(npm --version 2>/dev/null || echo '✗ 未安装')"
echo "nvm: $(nvm --version 2>/dev/null || echo '✗ 未安装')"
echo "Node 路径: $(which node 2>/dev/null || echo '✗')"
echo "Claude 路径: $(which claude 2>/dev/null || echo '✗')"
echo "Claude 版本: $(claude --version 2>/dev/null || echo '✗')"
# 3. 环境变量
echo ""
echo "=== 3. 关键环境变量 ==="
[ -n "$ANTHROPIC_API_KEY" ] && \
echo "ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:0:12}..." || \
echo "ANTHROPIC_API_KEY: ✗ 未设置"
[ -n "$HTTPS_PROXY" ] && echo "HTTPS_PROXY: $HTTPS_PROXY" || echo "HTTPS_PROXY: (未设置)"
[ -n "$HTTP_PROXY" ] && echo "HTTP_PROXY: $HTTP_PROXY" || echo "HTTP_PROXY: (未设置)"
[ -n "$NO_PROXY" ] && echo "NO_PROXY: $NO_PROXY" || echo "NO_PROXY: (未设置)"
[ -n "$NODE_EXTRA_CA_CERTS" ] && echo "NODE_EXTRA_CA_CERTS: $NODE_EXTRA_CA_CERTS" || echo "NODE_EXTRA_CA_CERTS: (未设置)"
[ -n "$ANTHROPIC_BASE_URL" ] && echo "ANTHROPIC_BASE_URL: $ANTHROPIC_BASE_URL" || echo "ANTHROPIC_BASE_URL: (默认)"
echo "LANG: $LANG"
echo "LC_ALL: ${LC_ALL:-（未设置）}"
# 4. 配置文件
echo ""
echo "=== 4. 配置文件 ==="
for f in ".claude/settings.json" ".claude/settings.local.json" \
"$HOME/.claude/settings.json" "CLAUDE.md"; do
if [ -f "$f" ]; then
SIZE=$(wc -c < "$f")
echo " ✓ $f ($SIZE bytes)"
# JSON 验证
if [[ "$f" == *.json ]]; then
python3 -m json.tool "$f" >/dev/null 2>&1 && \
echo " JSON: ✓ 格式正确" || echo " JSON: ✗ 格式错误"
fi
else
echo " - $f (不存在)"
fi
done
# 5. 子代理和命令
echo ""
echo "=== 5. 子代理和命令 ==="
if [ -d ".claude/agents" ]; then
AGENTS=$(ls .claude/agents/*.json 2>/dev/null | wc -l | xargs)
echo " 子代理: $AGENTS 个"
for f in .claude/agents/*.json; do
[ -f "$f" ] && echo " - $(basename $f)"
done
fi
if [ -d ".claude/commands" ]; then
COMMANDS=$(ls .claude/commands/*.md 2>/dev/null | wc -l | xargs)
echo " 命令: $COMMANDS 个"
for f in .claude/commands/*.md; do
[ -f "$f" ] && echo " - $(basename $f)"
done
fi
# 6. 网络
echo ""
echo "=== 6. 网络诊断 ==="
echo -n "DNS: "
if dig api.anthropic.com +short >/dev/null 2>&1; then
echo "✓ $(dig api.anthropic.com +short 2>/dev/null | head -1)"
else
echo "✗ 解析失败"
fi
echo -n "连接: "
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 \
${HTTPS_PROXY:+--proxy "$HTTPS_PROXY"} \
"https://api.anthropic.com/v1/health" 2>/dev/null)
if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "404" ]; then
echo "✓ (HTTP $HTTP_CODE)"
else
echo "✗ (HTTP $HTTP_CODE 或连接失败)"
fi
# 7. 磁盘和内存
echo ""
echo "=== 7. 系统资源 ==="
echo "磁盘空间:"
df -h . | tail -1 | awk '{print " "$4" 可用 / "$2" 总计 ("$5" 使用)"}'
echo "内存:"
if [[ "$OSTYPE" == "darwin"* ]]; then
MEM_TOTAL=$(sysctl -n hw.memsize 2>/dev/null | awk '{print $1/1024/1024/1024 "GB"}')
echo " 总内存: $MEM_TOTAL"
ps aux | grep -i claude | grep -v grep | awk '{print " Claude PID="$2" RSS="$6/1024"MB CPU="$3"%"}'
else
free -h | head -2
fi
# 8. 会话日志
echo ""
echo "=== 8. 会话日志 ==="
PROJECTS_DIR="$HOME/.claude/projects"
if [ -d "$PROJECTS_DIR" ]; then
PROJECT_COUNT=$(ls -d "$PROJECTS_DIR"/*/ 2>/dev/null | wc -l | xargs)
echo " 项目数: $PROJECT_COUNT"
# 最近的会话
LATEST_SESSION=$(find "$PROJECTS_DIR" -name "*.jsonl" -type f \
-exec stat -f "%m %N" {} \; 2>/dev/null | \
sort -rn | head -1)
[ -n "$LATEST_SESSION" ] && echo " 最近会话: $(echo $LATEST_SESSION | awk '{print $2}')"
fi
# 9. .gitignore 检查
echo ""
echo "=== 9. Git 配置 ==="
if [ -d ".git" ]; then
echo " Git 仓库: ✓"
# 检查 settings.local.json 是否被跟踪
if git ls-files --error-unmatch .claude/settings.local.json >/dev/null 2>&1; then
echo " ⚠ settings.local.json 被 Git 跟踪! (应加入 .gitignore)"
else
echo " ✓ settings.local.json 未被跟踪"
fi
# 检查 .env
if git ls-files --error-unmatch .env >/dev/null 2>&1; then
echo " ⚠ .env 被 Git 跟踪! (安全风险)"
fi
else
echo " Git 仓库: ✗ (非 Git 仓库)"
fi
echo ""
echo "============================================"
echo " 诊断完成"
echo "============================================"
4.2 配置修复工具
#!/usr/bin/env python3
"""
Claude Code 配置修复工具
自动检测和修复常见配置问题
"""
import json
import os
import sys
from pathlib import Path
class ConfigRepair:
"""配置修复器"""
def __init__(self):
self.issues = []
self.fixes = []
def check_json(self, filepath):
"""检查 JSON 文件格式"""
if not os.path.exists(filepath):
return True
try:
with open(filepath) as f:
json.load(f)
return True
except json.JSONDecodeError as e:
self.issues.append(f"{filepath}: JSON 格式错误 - {e}")
return False
def check_model_name(self, filepath):
"""检查模型名是否弃用"""
if not os.path.exists(filepath):
return
deprecated = [
"claude-3-opus-20240229", "claude-3-sonnet-20240229",
"claude-3-haiku-20240307", "claude-3-5-sonnet-20241022",
"claude-3-5-haiku-20241022"
]
replacements = {
"claude-3-opus-20240229": "claude-opus-4-20250514",
"claude-3-sonnet-20240229": "claude-sonnet-4-20250514",
"claude-3-haiku-20240307": "claude-haiku-4-20250422",
"claude-3-5-sonnet-20241022": "claude-sonnet-4-20250514",
"claude-3-5-haiku-20241022": "claude-haiku-4-20250422",
}
with open(filepath) as f:
content = f.read()
changed = False
for old, new in replacements.items():
if old in content:
content = content.replace(old, new)
self.issues.append(f"{filepath}: 弃用模型名 {old}")
self.fixes.append(f"{filepath}: {old} → {new}")
changed = True
if changed:
with open(filepath, "w") as f:
f.write(content)
def check_gitignore(self):
"""检查 .gitignore"""
gitignore = Path(".gitignore")
required = [".claude/settings.local.json", ".env"]
missing = []
if gitignore.exists():
content = gitignore.read_text()
for entry in required:
if entry not in content:
missing.append(entry)
else:
missing = required
if missing:
self.issues.append(f".gitignore: 缺少条目 {missing}")
self.fixes.append(f"添加到 .gitignore: {missing}")
with open(gitignore, "a") as f:
f.write("\n# Claude Code\n")
for entry in missing:
f.write(f"{entry}\n")
def check_permissions(self, filepath):
"""检查权限配置"""
if not os.path.exists(filepath):
return
try:
with open(filepath) as f:
data = json.load(f)
except:
return
perms = data.get("permissions", {})
# 检查是否有 deny 规则
if not perms.get("deny"):
self.issues.append(f"{filepath}: 无 deny 权限规则 (安全风险)")
self.fixes.append(f"{filepath}: 建议添加 deny 规则")
def check_claude_md(self):
"""检查 CLAUDE.md"""
if not os.path.exists("CLAUDE.md"):
self.issues.append("CLAUDE.md: 不存在")
self.fixes.append("创建 CLAUDE.md 项目上下文文件")
def run(self):
"""运行所有检查"""
print("=== Claude Code 配置检查 ===\n")
# 检查所有配置文件
configs = [
".claude/settings.json",
".claude/settings.local.json",
os.path.expanduser("~/.claude/settings.json"),
]
for config in configs:
self.check_json(config)
self.check_model_name(config)
self.check_permissions(config)
# 检查子代理
agents_dir = Path(".claude/agents")
if agents_dir.exists():
for agent_file in agents_dir.glob("*.json"):
self.check_json(str(agent_file))
self.check_model_name(str(agent_file))
# 检查 .gitignore
self.check_gitignore()
# 检查 CLAUDE.md
self.check_claude_md()
# 报告
if self.issues:
print(f"发现 {len(self.issues)} 个问题:")
for i, issue in enumerate(self.issues, 1):
print(f" {i}. {issue}")
else:
print("✓ 未发现问题")
if self.fixes:
print(f"\n已自动修复 {len(self.fixes)} 项:")
for fix in self.fixes:
print(f" ✓ {fix}")
return len(self.issues) == 0
repair = ConfigRepair()
repair.run()
4.3 清理与重置
#!/bin/bash
# claude-reset.sh — Claude Code 清理与重置 (不删配置)
echo "=== Claude Code 清理 ==="
# 1. 清理会话缓存
echo "1. 清理会话缓存..."
CACHE_DIR="$HOME/.claude/projects"
if [ -d "$CACHE_DIR" ]; then
SIZE=$(du -sh "$CACHE_DIR" 2>/dev/null | cut -f1)
echo " 缓存大小: $SIZE"
read -p " 清理? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
rm -rf "$CACHE_DIR"
echo " ✓ 已清理"
fi
fi
# 2. 清理 npm 缓存
echo "2. 清理 npm 缓存..."
npm cache clean --force 2>/dev/null
echo " ✓ 已清理"
# 3. 重新安装 Claude Code
echo "3. 重新安装 Claude Code..."
npm install -g @anthropic-ai/claude-code@latest
echo " ✓ 已重新安装 ($(claude --version))"
# 4. 验证配置
echo "4. 验证配置..."
if [ -f ".claude/settings.json" ]; then
python3 -m json.tool .claude/settings.json >/dev/null 2>&1 && \
echo " ✓ settings.json 格式正确" || echo " ✗ settings.json 格式错误"
fi
echo ""
echo "=== 清理完成 ==="
echo "如果问题仍然存在，尝试:"
echo " 1. 删除 .claude/ 目录 (会丢失配置!)"
echo " 2. 重新运行团队配置初始化"
echo " 3. 检查网络连接"
4.4 性能优化清单
#!/bin/bash
# performance-check.sh — 性能优化检查
echo "=== Claude Code 性能检查 ==="
# 1. 项目大小
echo "项目大小:"
du -sh . 2>/dev/null
echo ""
# 2. 文件数量
echo "文件数量:"
TOTAL=$(find . -type f -not -path './.git/*' 2>/dev/null | wc -l | xargs)
echo " 总文件: $TOTAL"
NODE_MODULES=$(find . -path './node_modules' -type d 2>/dev/null | wc -l | xargs)
echo " node_modules: $NODE_MODULES"
echo ""
# 3. CLAUDE.md 大小
if [ -f "CLAUDE.md" ]; then
SIZE=$(wc -c < CLAUDE.md)
LINES=$(wc -l < CLAUDE.md)
echo "CLAUDE.md: $LINES 行, $SIZE 字节"
if [ "$SIZE" -gt 5000 ]; then
echo " ⚠ CLAUDE.md 过大 (>5KB)，会增加每次请求的 input token"
echo " 建议精简到 2-3KB"
fi
fi
# 4. .claudeignore 检查
echo ""
if [ -f ".claudeignore" ]; then
echo ".claudeignore: ✓ 存在"
else
echo ".claudeignore: ✗ 不存在"
echo " 建议创建 .claudeignore 排除大目录"
echo " 示例内容: node_modules/, dist/, build/, *.lock"
fi
# 5. 内存使用
echo ""
echo "Claude Code 进程:"
ps aux | grep -i claude | grep -v grep | awk '{print " PID="$2" RSS="$6/1024"MB CPU="$3"% MEM="$4"%"}'
echo ""
echo "=== 性能优化建议 ==="
echo " 1. 精简 CLAUDE.md (< 3KB)"
echo " 2. 创建 .claudeignore 排除大目录"
echo " 3. 长会话定期 /compact"
echo " 4. 用子代理隔离大任务"
echo " 5. 避免全量读取大文件"
echo " 6. 使用 Haiku 处理简单任务"
5. 验证回归：全面验证
5.1 全面验证脚本
#!/bin/bash
# full-verify.sh — Claude Code 全面验证
PASS=0
FAIL=0
WARN=0
verify() {
local name=$1
local result=$2
local type=${3:-"hard"}
if [ "$result" = "0" ]; then
echo " ✓ $name"
PASS=$((PASS + 1))
elif [ "$type" = "soft" ]; then
echo " ⚠ $name"
WARN=$((WARN + 1))
else
echo " ✗ $name"
FAIL=$((FAIL + 1))
fi
}
echo "=== Claude Code 全面验证 ==="
echo ""
# 1. 基本功能
echo "--- 基本功能 ---"
claude --version >/dev/null 2>&1 && verify "Claude Code 可用" 0 || verify "Claude Code 可用" 1
node --version >/dev/null 2>&1 && verify "Node.js 可用" 0 || verify "Node.js 可用" 1
NODE_MAJOR=$(node --version 2>/dev/null | sed 's/v//' | cut -d. -f1)
[ "$NODE_MAJOR" -ge 18 ] 2>/dev/null && verify "Node.js >= 18" 0 || verify "Node.js >= 18" 1
# 2. 配置
echo ""
echo "--- 配置 ---"
[ -f ".claude/settings.json" ] && verify "settings.json 存在" 0 || verify "settings.json 存在" 1 "soft"
python3 -m json.tool .claude/settings.json >/dev/null 2>&1 && verify "settings.json JSON 格式" 0 || verify "settings.json JSON 格式" 1 "soft"
[ -f "CLAUDE.md" ] && verify "CLAUDE.md 存在" 0 || verify "CLAUDE.md 存在" 1 "soft"
# 3. 网络
echo ""
echo "--- 网络 ---"
dig api.anthropic.com +short >/dev/null 2>&1 && verify "DNS 解析" 0 || verify "DNS 解析" 1
curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 https://api.anthropic.com/v1/health 2>/dev/null | grep -qE "200|404" && verify "API 连接" 0 || verify "API 连接" 1
# 4. Git
echo ""
echo "--- Git ---"
[ -d ".git" ] && verify "Git 仓库" 0 || verify "Git 仓库" 1 "soft"
if [ -d ".git" ]; then
git ls-files --error-unmatch .claude/settings.local.json >/dev/null 2>&1 && verify "local 不入 Git" 1 || verify "local 不入 Git" 0
fi
# 5. 磁盘
echo ""
echo "--- 磁盘 ---"
DISK_AVAIL=$(df . | tail -1 | awk '{print $4}')
[ "$DISK_AVAIL" -gt 1000000 ] && verify "磁盘空间 > 1GB" 0 || verify "磁盘空间 > 1GB" 1
echo ""
echo "=== 结果: $PASS 通过, $WARN 警告, $FAIL 失败 ==="
6. 避坑最佳实践
6.1 疑难排查原则
原则 1: 先收集信息 — 用诊断脚本收集完整环境信息
原则 2: 分层排查 — 从系统 → 网络 → 配置 → 代码
原则 3: 最小复现 — 找到最小复现步骤
原则 4: 二分法 — 逐步排除可能原因
原则 5: 查日志 — 会话日志、Verbose、Hook 日志
原则 6: 先简单后复杂 — 先检查常见原因
原则 7: 不猜要验证 — 用工具验证而非猜测
原则 8: 记录解决方案 — 记录已解决的问题
6.2 高频问题速查
| 症状 | 最可能原因 | 快速检查 |
|---|---|---|
| 启动失败 | JSON 格式错误 | python3 -m json.tool |
| 连接失败 | 代理/DNS | dig + curl |
| 工具不执行 | Hook 阻塞 | 检查 Hook exit code |
| 遗忘上下文 | 会话过长 | /compact |
| 极慢 | 大项目/大文件 | .claudeignore |
| CPU 100% | 进程异常 | ps aux |
| 权限不生效 | glob 模式错误 | 检查 ** vs * |
| 配置不生效 | 层级覆盖 | 检查 local.json |
| 中文乱码 | 编码非 UTF-8 | echo $LANG |
| 找不到 claude | nvm 路径 | which claude |
6.3 预防性维护
| 频率 | 维护项 | 命令 |
|---|---|---|
| 每日 | 检查成本 | cost-analyzer |
| 每周 | 清理会话缓存 | rm ~/.claude/projects/ |
| 每月 | 检查配置同步 | check-team-config |
| 每月 | 更新 Claude Code | npm update -g |
| 每季 | 审查权限规则 | 检查 allow/deny |
| 升级前 | 备份配置 | cp -r .claude .claude-bak |
7. 附录：终极速查表
7.1 诊断命令速查
| 诊断 | 命令 |
|---|---|
| 系统信息 | uname -a; node --version; claude --version |
| 配置验证 | python3 -m json.tool .claude/settings.json |
| 网络测试 | dig api.anthropic.com; curl -v https://api.anthropic.com/v1/health |
| 代理检查 | env | grep -i proxy |
| TLS 检查 | openssl s_client -connect api.anthropic.com:443 |
| 进程检查 | ps aux | grep claude |
| 磁盘检查 | df -h |
| 日志查看 | cat ~/.claude/projects/*/sessions/*.jsonl | tail |
| Verbose 模式 | claude --verbose |
| 配置检查 | python3 config-repair.py |
7.2 全系列文章索引
| 类别 | 文章编号 | 主题 |
|---|---|---|
| 服务器错误 | 01-05 | 500/529/超时/安全/分类器 |
| 使用限制 | 06-11 | 限流/配额/并发/高峰/长会话/多项目 |
| 身份验证 | 12-16 | API Key/OAuth/令牌/SSO/组织 |
| 网络连接 | 17-18 | 连接超时/SSL证书 |
| 请求错误 | 19-23 | 400/413/422/429/长提示 |
| 综合合集 | 24-25 | 常见错误/排查流程 |
| 安装配置 | 26-28 | 安装排错/MCP连接/企业配置 |
| 高级功能 | 29-40 | Hooks/记忆/命令/上下文/Plan/思考/Worktree/子代理/CI/审查/会话/ignore |
| 进阶实战 | 41-53 | 限流/Token/Worktree/权限/Headless/调试/SDK/模型/缓存/多语言/IDE/权限/流式 |
| 深度指南 | 54-60 | MCP协议/迁移/审计/代理/成本/团队/疑难杂症 |
7.3 紧急处理速查
| 紧急情况 | 立即操作 |
|---|---|
| API Key 泄露 | 立即在 Console 撤销并重新生成 |
| 费用暴增 | 设置预算限制 + 检查是否有死循环 |
| 文件被误改 | git checkout -- . 恢复 |
| 进程卡死 | pkill -f claude 强制终止 |
| 配置损坏 | 从备份恢复 cp .claude-bak/* .claude/ |
| 完全无法使用 | npm install -g @anthropic-ai/claude-code@latest 重装 |
结语
本文作为 Claude Code 疑难杂症的终极排查手册，覆盖了 30 个非典型问题及其诊断方法。结合前 59 篇文章的深度解析，构成了完整的 Claude Code 问题解决知识库。
核心要点回顾：
- 先诊断后行动：用诊断脚本收集信息，而非盲目猜测
- 分层排查：系统 → 网络 → 配置 → 代码，逐层排除
- 日志是关键：会话日志、Verbose 输出、Hook 日志是排查依据
- JSON 格式：配置文件 JSON 语法错误是最常见的启动失败原因
- 权限 glob：
**匹配多级目录，*只匹配一级，混淆会导致权限不生效 - 环境一致性：不同终端/Shell 的环境变量差异导致行为不一致
- 性能优化：精简 CLAUDE.md、配置 .claudeignore、定期 /compact
- 预防优于治疗：定期维护、备份配置、监控成本，防患于未然
汇聚全球AI编程工具，助力开发者即刻编程。
更多推荐
0
0- 0
已为社区贡献18条内容
所有评论(0)