【Bug已解决】Claude Code freezes on startup / Hangs at initialization — Claude Code 启动冻结解决方案

【Bug已解决】Claude Code freezes on startup / Hangs at initialization — Claude Code 启动冻结解决方案

1. 问题描述

运行claude命令后，终端卡在初始化阶段，长时间无响应：

$ claude # 光标闪烁但没有任何输出 # 等待 30 秒以上仍无响应 # Ctrl+C 可以中断 # 或卡在加载步骤 $ claude Loading configuration... # 卡在这里不动 # 或卡在 MCP 初始化 $ claude Initializing MCP servers... # 卡住不继续

这个问题在以下场景中特别常见：

• MCP Server 启动失败导致等待
• 网络问题导致 API 连接超时
• settings.json 格式错误导致解析卡住
• 磁盘 I/O 慢（如网络挂载盘）
• Node.js 内存不足导致 GC 卡顿
• 多个 MCP Server 串行初始化慢

2. 原因分析

核心原理拆解

claude 启动 → 加载配置 → 初始化 MCP → 连接 API ↓ 某个步骤卡住（MCP/网络/配置/磁盘） ↓ 启动冻结

原因分类表

3. 解决方案

方案一：使用 --debug 诊断卡住位置（最推荐）

# 步骤 1：使用 debug 模式启动 claude --debug 2>&1 | head -50 # 查看卡在哪个步骤 # 步骤 2：如果卡在 MCP 初始化 claude --debug 2>&1 | grep -i mcp # 步骤 3：如果卡在 API 连接 claude --debug 2>&1 | grep -i "api\|connect\|fetch" # 步骤 4：根据卡住的位置针对性解决

方案二：禁用 MCP Server 启动

# 步骤 1：临时禁用所有 MCP claude --no-mcp # 步骤 2：如果 --no-mcp 后启动正常 # 说明是 MCP Server 导致的冻结 # 步骤 3：逐个排查 MCP Server claude mcp list # 逐个移除测试 claude mcp remove <server_name> claude # 测试启动 # 步骤 4：找到问题 MCP 后 # 修复或替换该 MCP Server

方案三：检查网络连接

# 步骤 1：测试 API 连通性 curl -I https://api.anthropic.com --max-time 10 # 步骤 2：如果 curl 也慢，检查 DNS 解析 nslookup api.anthropic.com dig api.anthropic.com +short # 步骤 3：测试不同 DNS 服务器 curl --resolve api.anthropic.com:443:$(dig +short api.anthropic.com @8.8.8.8) \ -I https://api.anthropic.com --max-time 10 # 步骤 4：检查系统时间偏差（TLS 握手依赖时间同步） date && curl -sI https://api.anthropic.com | head -1 # 如果系统时间偏差超过 5 分钟，TLS 握手会失败导致卡住

方案四：检查配置文件

# 步骤 1：验证 settings.json 格式 python3 -m json.tool ~/.claude/settings.json # 步骤 2：如果格式错误，修复 # 参考 C47 解决方案 # 步骤 3：临时移除配置测试 mv ~/.claude/settings.json ~/.claude/settings.json.bak claude # 如果启动正常，说明配置有问题 # 步骤 4：逐步恢复配置项

方案五：检查磁盘和会话文件

# 步骤 1：检查磁盘空间 df -h ~ # 步骤 2：检查会话文件大小 du -sh ~/.claude/sessions/ # 步骤 3：如果会话文件过大 find ~/.claude/sessions/ -type f -size +50M -delete # 步骤 4：如果磁盘满 # 清理空间 find ~/.claude/logs/ -type f -mtime +3 -delete

方案六：增加启动超时

# 步骤 1：设置更长的启动超时 export CLAUDE_STARTUP_TIMEOUT=60000 # 60 秒启动超时 # 步骤 2：永久设置 echo 'export CLAUDE_STARTUP_TIMEOUT=60000' >> ~/.zshrc source ~/.zshrc # 步骤 3：启动 claude

4. 各方案对比总结

5. 常见问题 FAQ

5.1 Claude Code 启动正常需要多久

通常 2-5 秒。如果超过 10 秒说明有问题。

5.2 MCP Server 为什么导致启动冻结

Claude Code 启动时会初始化所有 MCP Server。如果某个 Server 启动慢或卡住，整个启动被阻塞。

5.3 --no-mcp 是什么

跳过 MCP Server 初始化。如果--no-mcp后启动正常，说明是 MCP 问题。

5.4 如何找到导致冻结的 MCP Server

逐个移除 MCP Server 测试：

claude mcp list # 列出所有 claude mcp remove server1 # 移除一个 claude # 测试 # 逐个测试找到问题 Server

5.5 网络问题如何排查

curl -I https://api.anthropic.com --max-time 10 # 如果超时，说明网络有问题

5.6 会话文件过大导致启动慢

大会话文件（>50MB）加载需要时间。清理旧会话：

find ~/.claude/sessions/ -type f -size +50M -delete

5.7 settings.json 格式错误导致冻结

JSON 解析可能卡住或抛异常。用python3 -m json.tool验证格式。

5.8 Docker 中启动冻结

Docker 容器可能缺少依赖或网络不通。使用docker run -it查看输出。

5.9 企业服务器启动冻结

企业服务器网络限制可能导致 API 连接超时。检查网络规则和 DNS 配置，确保api.anthropic.com可解析且端口 443 出站未被拦截。

5.10 排查清单速查表

□ 1. claude --debug 查看卡住位置 □ 2. claude --no-mcp 测试是否 MCP 问题 □ 3. curl -I https://api.anthropic.com 测试网络 □ 4. python3 -m json.tool 验证 settings.json □ 5. mv settings.json 测试无配置启动 □ 6. df -h 检查磁盘空间 □ 7. du -sh ~/.claude/sessions/ 检查会话大小 □ 8. 清理 >50M 的会话文件 □ 9. 设置 CLAUDE_STARTUP_TIMEOUT □ 10. 逐个移除 MCP Server 排查

6. 总结

1. 根本原因：启动冻结最常见原因是 MCP Server 启动慢（40%）和网络连接超时（25%）
2. 最佳实践：使用claude --debug 2>&1 | head -50诊断卡在哪个步骤，针对性解决
3. MCP 排查：使用claude --no-mcp测试——如果启动正常，说明是 MCP Server 问题，逐个移除排查
4. 网络检查：用curl -I https://api.anthropic.com --max-time 10测试 API 连通性，排除网络问题
5. 最佳实践建议：定期清理~/.claude/sessions/中超过 50MB 的大会话文件，避免启动时加载缓慢

故障排查流程图

flowchart TD A[启动冻结] --> B[claude --debug 诊断] B --> C{卡在哪个步骤?} C -->|MCP 初始化| D[claude --no-mcp 测试] C -->|API 连接| E[curl 测试网络] C -->|配置加载| F[验证 settings.json] C -->|会话加载| G[检查会话文件] D --> H{--no-mcp 后正常?} H -->|是| I[逐个移除 MCP 排查] H -->|否| J[检查网络和配置] E --> K{curl 成功?} K -->|否| L[修复 DNS/网络] K -->|是| M[检查 API Key] F --> N{JSON 格式正确?} N -->|否| O[修复 JSON] N -->|是| P[移除配置测试] G --> Q{文件 > 50MB?} Q -->|是| R[清理大会话文件] Q -->|否| S[检查磁盘空间] I --> T[找到问题 MCP] L --> U[✅ 启动成功] M --> U O --> U P --> U R --> U S --> U T --> U