【Claude】疑难杂症终极排查手册 — 已解决

【Claude】疑难杂症终极排查手册 — 已解决适用版本Claude Code 全版本受影响场景非典型错误、偶发性问题、环境冲突、性能异常、诡异行为阅读时长约 35 分钟目录问题现象分类原理深挖疑难问题诊断方法论根因分析30 个疑难杂症多方案解决分场景排错验证回归全面验证避坑最佳实践附录终极速查表1. 问题现象分类1.1 启动类疑难#问题频率1Claude Code 启动后立即退出偶发2启动卡在 Initializing... 不动偶发3不同终端启动行为不一致常见4升级后首次启动报配置错误常见1.2 运行时疑难#问题频率5工具调用间歇性失败偶发6Claude 突然遗忘上下文常见7修改文件但不保存到磁盘偶发8相同输入得到不同结果偶发9中文输出乱码常见10进程占用 CPU 100%偶发1.3 环境冲突疑难#问题频率11多版本 Node.js 冲突常见12nvm/fnm 环境下找不到 claude常见13Docker 容器内路径异常偶发14WSL2 中文件系统慢常见15macOS 权限弹窗不断出现常见1.4 配置疑难#问题频率16settings.json 被重置偶发17CLAUDE.md 有时加载有时不加载常见18Hook 有时触发有时不触发偶发19权限规则不生效常见20子代理调用失败偶发1.5 网络疑难#问题频率21白天正常晚上超时偶发22换 WiFi 后无法连接常见23SSH 到远程后 Claude 不可用常见24SSE 流式响应中途断开偶发1.6 其他疑难#问题频率25Git 操作后 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 21 | 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 配置文件.zshrcvs.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 或固定 seedSDK。3.9 中文输出乱码根因终端编码不是 UTF-8或 Node.js 的输出编码不正确。诊断echo $LANG $LC_ALL locale解决export LANGen_US.UTF-8 export LC_ALLen_US.UTF-83.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-code3.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_KEYsk-ant-xxx # 或用 SSH 转发环境变量 ssh -o SendEnvANTHROPIC_API_KEY userremote3.24 SSE 流式中途断开根因代理服务器超时、网络不稳定、或防火墙中断长连接。参考第 53 篇。3.25 Git 操作后行为异常根因git checkout/git stash后项目文件变化但 Claude Code 的缓存上下文还是旧版本。解决Git 操作后开启新会话或使用/compact。3.26 大型 monorepo 极慢根因monorepo 中文件数量巨大Claude Code 的文件搜索和上下文加载慢。解决配置.claudeignore排除不相关目录用子代理限定工作范围在子项目目录中运行 claude3.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 # macOS4. 多方案解决分场景排错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 21 \ 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 21; 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/1024MB 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 21; then echo ⚠ settings.local.json 被 Git 跟踪! (应加入 .gitignore) else echo ✓ settings.local.json 未被跟踪 fi # 检查 .env if git ls-files --error-unmatch .env /dev/null 21; 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-codelatest echo ✓ 已重新安装 ($(claude --version)) # 4. 验证配置 echo 4. 验证配置... if [ -f .claude/settings.json ]; then python3 -m json.tool .claude/settings.json /dev/null 21 \ 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/1024MB 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 全面验证 PASS0 FAIL0 WARN0 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 21 verify Claude Code 可用 0 || verify Claude Code 可用 1 node --version /dev/null 21 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 21 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 21 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 21 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连接失败代理/DNSdig curl工具不执行Hook 阻塞检查 Hook exit code遗忘上下文会话过长/compact极慢大项目/大文件.claudeignoreCPU 100%进程异常ps aux权限不生效glob 模式错误检查 ** vs *配置不生效层级覆盖检查 local.json中文乱码编码非 UTF-8echo $LANG找不到 claudenvm 路径which claude6.3 预防性维护频率维护项命令每日检查成本cost-analyzer每周清理会话缓存rm ~/.claude/projects/每月检查配置同步check-team-config每月更新 Claude Codenpm update -g每季审查权限规则检查 allow/deny升级前备份配置cp -r .claude .claude-bak7. 附录终极速查表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 proxyTLS 检查openssl s_client -connect api.anthropic.com:443进程检查ps aux | grep claude磁盘检查df -h日志查看cat ~/.claude/projects/*/sessions/*.jsonl | tailVerbose 模式claude --verbose配置检查python3 config-repair.py7.2 全系列文章索引类别文章编号主题服务器错误01-05500/529/超时/安全/分类器使用限制06-11限流/配额/并发/高峰/长会话/多项目身份验证12-16API Key/OAuth/令牌/SSO/组织网络连接17-18连接超时/SSL证书请求错误19-23400/413/422/429/长提示综合合集24-25常见错误/排查流程安装配置26-28安装排错/MCP连接/企业配置高级功能29-40Hooks/记忆/命令/上下文/Plan/思考/Worktree/子代理/CI/审查/会话/ignore进阶实战41-53限流/Token/Worktree/权限/Headless/调试/SDK/模型/缓存/多语言/IDE/权限/流式深度指南54-60MCP协议/迁移/审计/代理/成本/团队/疑难杂症7.3 紧急处理速查紧急情况立即操作API Key 泄露立即在 Console 撤销并重新生成费用暴增设置预算限制 检查是否有死循环文件被误改git checkout -- .恢复进程卡死pkill -f claude强制终止配置损坏从备份恢复cp .claude-bak/* .claude/完全无法使用npm install -g anthropic-ai/claude-codelatest重装结语本文作为 Claude Code 疑难杂症的终极排查手册覆盖了 30 个非典型问题及其诊断方法。结合前 59 篇文章的深度解析构成了完整的 Claude Code 问题解决知识库。核心要点回顾先诊断后行动用诊断脚本收集信息而非盲目猜测分层排查系统 → 网络 → 配置 → 代码逐层排除日志是关键会话日志、Verbose 输出、Hook 日志是排查依据JSON 格式配置文件 JSON 语法错误是最常见的启动失败原因权限 glob**匹配多级目录*只匹配一级混淆会导致权限不生效环境一致性不同终端/Shell 的环境变量差异导致行为不一致性能优化精简 CLAUDE.md、配置 .claudeignore、定期 /compact预防优于治疗定期维护、备份配置、监控成本防患于未然