【Bug已解决】Memory leak / High memory usage / Process killed — Claude Code 内存泄漏解决方案1. 问题描述长时间运行 Claude Code 后系统内存占用持续增长最终进程被系统杀死# macOS 活动监视器显示 claude 进程占用 2GB 内存 $ ps aux | grep claude | grep -v grep user 12345 95.0 45.2 2500234 2045678 ?? S 10:00AM 2:30.34 claude # 或终端报 OOM 错误 --- Last few GCs --- [12345:0x12345678] 123456 ms: Mark-sweep 2048.5 (2123.2) MB, 456.3 / 0.0 ms [12345:0x12345678] 123789 ms: Mark-sweep 2049.0 (2124.0) MB, 789.1 / 0.0 ms --- JS stacktrace --- FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory这个问题在以下场景中特别常见长时间运行 Claude Code数小时不退出大型项目的上下文持续增长MCP Server 内存泄漏大量会话历史积累频繁执行 /compact 但内存不释放Node.js 默认堆内存限制约 1.5GB2. 原因分析核心原理拆解Claude Code 运行 → 对话历史/MCP/缓存持续积累 ↓ Node.js V8 堆内存持续增长 ↓ 达到 V8 堆内存上限约 1.5GB ↓ OOM: JavaScript heap out of memory原因分类表原因分类具体表现占比对话历史积累上下文和会话数据不释放约 35%MCP Server 泄漏MCP 子进程内存泄漏约 25%日志/缓存积累内存中缓存大量数据约 20%V8 堆限制默认 1.5GB 不够约 10%/compact 无效压缩后内存未释放约 10%3. 解决方案方案一增加 Node.js 堆内存最推荐# 步骤 1增加 V8 堆内存限制 export NODE_OPTIONS--max-old-space-size4096 # 将堆内存限制提高到 4GB # 步骤 2永久设置 echo export NODE_OPTIONS--max-old-space-size4096 ~/.zshrc source ~/.zshrc # 步骤 3启动 Claude Code claude # 步骤 4验证内存设置 node -e console.log(v8.getHeapStatistics().heap_size_limit / 1024 / 1024 MB)方案二定期重启 Claude Code# 步骤 1每 2-3 小时退出并重新启动 /exit claude --continue # 恢复会话 # 步骤 2或在长时间使用后 /compact /exit claude --continue # 步骤 3设置提醒 # 在终端中设置 alias 提醒 echo alias claude-timerecho 开始计时; sleep 7200 echo 该重启 Claude Code 了! ~/.zshrc方案三使用 /clear 定期清理# 步骤 1每 30-60 分钟使用 /compact /compact # 压缩上下文释放部分内存 # 步骤 2每 2 小时使用 /clear /clear # 完全清空上下文释放大量内存 # 步骤 3将关键信息保存到文件后再 /clear 将重要的架构决策保存到 docs/decisions.md /clear 参考 docs/decisions.md 继续方案四减少 MCP 工具数量# 步骤 1检查 MCP 服务器 claude mcp list # 步骤 2移除不必要的 MCP 服务器 claude mcp remove server_name # 步骤 3MCP Server 是子进程每个都消耗内存 # 减少 MCP Server 数量可以显著降低内存使用 # 步骤 4定期重启 MCP /mcp restart方案五清理会话历史# 步骤 1检查会话目录大小 du -sh ~/.claude/sessions/ # 步骤 2清理旧会话 find ~/.claude/sessions/ -type f -mtime 7 -delete # 步骤 3清理日志 find ~/.claude/logs/ -type f -mtime 3 -delete # 步骤 4验证内存释放 ps aux | grep claude | grep -v grep方案六Docker 中限制内存# 步骤 1Docker 运行时设置内存限制 docker run --memory4g --memory-swap4g \ -e NODE_OPTIONS--max-old-space-size3072 \ node:22 claude # 步骤 2如果 OOM 被 Docker 杀死 # 增加内存限制 docker run --memory8g \ -e NODE_OPTIONS--max-old-space-size6144 \ node:22 claude4. 各方案对比总结方案适用场景推荐指数难度方案一增加堆内存OOM 崩溃⭐⭐⭐⭐⭐低方案二定期重启长时间使用⭐⭐⭐⭐⭐低方案三/clear 清理内存增长⭐⭐⭐⭐⭐低方案四减少 MCPMCP 泄漏⭐⭐⭐⭐低方案五清理历史磁盘内存⭐⭐⭐⭐低方案六Docker 限制Docker 环境⭐⭐⭐⭐中5. 常见问题 FAQ5.1 Node.js 默认堆内存是多少Node.js 默认 V8 堆内存限制约为 1.5GB64 位系统。可以通过--max-old-space-size调整。5.2 增加堆内存到多少合适4GB适合大部分场景8GB大型项目长时间运行不要超过系统物理内存的 70%5.3 /compact 后内存为什么不释放/compact压缩了对话历史的逻辑大小但 V8 的垃圾回收可能没有立即释放物理内存。完全释放需要/clear或重启进程。5.4 MCP Server 内存泄漏如何检测# 查看 MCP 子进程内存 ps aux | grep mcp | grep -v grep # 如果 MCP 进程内存持续增长 # 重启 MCP Server /mcp restart5.5 Docker 中 claude 被 OOM-killDocker 的内存限制低于 Node.js 堆内存设置。确保--memory大于--max-old-space-sizedocker run --memory4g -e NODE_OPTIONS--max-old-space-size3072 ...5.6 如何监控 Claude Code 内存使用# 实时监控 top -pid $(pgrep -f claude | head -1) # 或 ps aux | grep claude | grep -v grep | awk {print $6/1024 MB}5.7 长时间运行的最佳实践每 30 分钟/compact每 2 小时/clear保存关键信息后每 4 小时退出并claude --continue重启设置NODE_OPTIONS--max-old-space-size40965.8 CI/CD 中的内存问题CI 环境内存有限。使用--print模式避免交互式会话积累NODE_OPTIONS--max-old-space-size2048 claude --print analyze code --max-turns 105.9 macOS 上 claude 进程占用 2GBmacOS 上 Node.js 进程内存包含 V8 堆 C 层 缓冲区。实际 V8 堆可能只有 1GB但总进程内存更高。增加--max-old-space-size并定期重启。5.10 排查清单速查表□ 1. 设置 NODE_OPTIONS--max-old-space-size4096 □ 2. 每 30 分钟 /compact 压缩上下文 □ 3. 每 2 小时 /clear 释放内存 □ 4. 每 4 小时退出并 claude --continue 重启 □ 5. 检查 MCP 子进程内存: ps aux | grep mcp □ 6. 减少 MCP Server 数量 □ 7. 清理旧会话和日志文件 □ 8. Docker: --memory 大于 max-old-space-size □ 9. CI/CD 使用 --print 和 --max-turns □ 10. top 或 ps aux 监控内存使用6. 总结根本原因内存泄漏最常见原因是对话历史持续积累35%和 MCP Server 内存泄漏25%Node.js 默认 1.5GB 堆内存不够最佳实践设置NODE_OPTIONS--max-old-space-size4096将 V8 堆内存提高到 4GB并每 2 小时/clear释放内存定期重启长时间运行时每 4 小时退出并claude --continue重启进程让操作系统完全回收内存MCP 管理每个 MCP Server 是独立的子进程减少不必要的 MCP Server 并定期/mcp restart回收内存最佳实践建议将关键上下文写入文件后定期/clear这比/compact更有效地释放内存——/compact压缩逻辑大小但不保证物理内存立即释放故障排查流程图flowchart TD A[内存泄漏/OOM] -- B[设置 NODE_OPTIONS4096] B -- C[重启 Claude Code] C -- D{OOM 消失?} D --|是| E[✅ 问题解决] D --|否| F[检查 MCP 内存] F -- G{MCP 内存高?} G --|是| H[/mcp restart] G --|否| I[/clear 清空上下文] H -- J{内存释放?} I -- J J --|是| E J --|否| K[退出并重启 claude] K -- L[claude --continue 恢复] L -- M{内存稳定?} M --|是| E M --|否| N[减少 MCP Server 数量] N -- O[清理会话和日志] O -- P[设置定期重启计划] P -- E