【Bug已解决】Error: Cannot find module / MODULE_NOT_FOUND — Claude Code 模块缺失解决方案1. 问题描述在启动 Claude Code 或使用过程中终端弹出以下 Node.js 模块加载错误Error: Cannot find module anthropic-ai/claude-code Require stack: - /usr/local/bin/claude或者Error: Cannot find module node:fs at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)有时报错为依赖模块缺失Error: Cannot find module anthropic-ai/sdk at createrequire (/usr/local/lib/node_modules/anthropic-ai/claude-code/dist/index.js:12:24)这个问题在以下场景中特别常见Node.js 版本切换后全局模块路径变化npm install 安装不完整手动删除了 node_modules 中的部分文件使用 nvm 切换 Node 版本后未重新安装全局包Claude Code 更新过程中断导致依赖不完整# 典型复现过程 $ claude Error: Cannot find module anthropic-ai/claude-code # Claude Code 完全无法启动2. 原因分析核心原理拆解Claude Code 启动 → Node.js 加载模块 ↓ 模块文件不存在/路径不正确/版本不兼容 ↓ Require 失败 ↓ 报错 Cannot find module原因分类表原因分类具体表现占比nvm 切换版本全局包不共享切换后丢失约 35%安装不完整npm install 中断或部分失败约 25%手动删除误删 node_modules 文件约 20%Node 版本不兼容node:fs 等内置模块需要 Node 16约 10%路径错误NODE_PATH 未设置或错误约 5%符号链接断裂软链接指向不存在的路径约 5%3. 解决方案方案一重新安装 Claude Code最推荐# 步骤 1卸载当前版本 npm uninstall -g anthropic-ai/claude-code # 步骤 2清除缓存 npm cache clean --force # 步骤 3重新安装 npm install -g anthropic-ai/claude-code # 步骤 4验证 claude --version方案二检查 Node.js 版本和路径# 步骤 1检查 Node.js 版本 node --version # 需要 Node.js 18 # 步骤 2检查全局模块路径 npm root -g # 确认路径正确 # 步骤 3如果使用 nvm nvm current nvm use 22 # 切换版本后需要重新安装全局包 npm install -g anthropic-ai/claude-code # 步骤 4验证 which claude claude --version方案三修复 NODE_PATH# 步骤 1检查 NODE_PATH echo $NODE_PATH # 如果为空设置它 # 步骤 2设置 NODE_PATH 指向全局模块 export NODE_PATH$(npm root -g) echo export NODE_PATH$(npm root -g) ~/.zshrc source ~/.zshrc # 步骤 3验证 node -e require(anthropic-ai/claude-code) # 不报错说明路径正确方案四检查符号链接# 步骤 1检查 claude 命令的符号链接 ls -la $(which claude) # 查看指向的实际路径 # 步骤 2如果符号链接断裂 # 重新创建 ln -sf $(npm root -g)/anthropic-ai/claude-code/dist/index.js $(npm config get prefix)/bin/claude # 步骤 3或重新安装以自动修复 npm install -g anthropic-ai/claude-code方案五处理 nvm 版本切换问题# 步骤 1确认 nvm 使用的版本 nvm current # 步骤 2为当前版本安装 Claude Code nvm use 22 npm install -g anthropic-ai/claude-code # 步骤 3设置 nvm 默认版本 nvm alias default 22 # 步骤 4创建全局包迁移 # 如果需要在多个 Node 版本中使用 claude nvm reinstall-packages 18 # 将 18 的全局包安装到当前版本方案六使用 npx 临时运行# 步骤 1如果不想全局安装使用 npx npx anthropic-ai/claude-code # 步骤 2或使用 Volta自动管理全局包 volta install anthropic-ai/claude-code # Volta 会在不同 Node 版本间共享全局包4. 各方案对比总结方案适用场景推荐指数难度方案一重装通用解决方案⭐⭐⭐⭐⭐低方案二检查 Nodenvm 问题⭐⭐⭐⭐⭐低方案三修复 NODE_PATH路径问题⭐⭐⭐低方案四修复软链接链接断裂⭐⭐⭐⭐中方案五nvm 迁移版本切换⭐⭐⭐⭐中方案六npx/Volta替代方案⭐⭐⭐低5. 常见问题 FAQ5.1 为什么 nvm 切换版本后全局包消失nvm 为每个 Node.js 版本维护独立的全局模块目录。切换版本后之前版本安装的全局包在新版本中不存在。使用nvm reinstall-packages 旧版本迁移。5.2 Cannot find module node:fs 是什么意思node:前缀的模块是 Node.js 内置模块。如果报错找不到说明 Node.js 版本太低需要 16。升级 Node.js 版本。5.3 npm install -g 报错但 --version 正常可能安装不完整。清除缓存后重装npm cache clean --force npm uninstall -g anthropic-ai/claude-code npm install -g anthropic-ai/claude-code5.4 which claude 找不到命令npm 全局 bin 目录不在 PATH 中。参考 C12 篇配置用户级 npm 目录或修复 PATH。5.5 Docker 中报 Cannot find module确保 Dockerfile 中正确安装RUN npm install -g anthropic-ai/claude-code # 验证 RUN claude --version5.6 如何查看全局已安装的包npm list -g --depth0 # 查看所有全局包5.7 符号链接断裂如何检测# 检查符号链接是否有效 readlink -f $(which claude) # 如果路径不存在说明链接断裂5.8 Windows 上报 Cannot find moduleWindows 上路径分隔符是\可能影响模块解析。确保使用正斜杠/或使用 PowerShell 的路径处理。5.9 CI/CD 中模块缺失确保 CI 配置中先安装 Claude Code- run: npm install -g anthropic-ai/claude-code - run: claude --version5.10 排查清单速查表□ 1. 运行 node --version 确认 Node 18 □ 2. 运行 npm root -g 确认全局模块路径 □ 3. 运行 which claude 确认命令存在 □ 4. 运行 ls -la $(which claude) 检查符号链接 □ 5. npm uninstall -g npm install -g 重装 □ 6. nvm 用户: nvm use nvm reinstall-packages □ 7. 检查 NODE_PATH 环境变量 □ 8. npm cache clean --force 清除缓存 □ 9. 考虑使用 Volta 避免版本切换问题 □ 10. CI/CD 中先安装再验证6. 总结根本原因模块缺失最常见原因是 nvm 版本切换后全局包不共享35%和安装不完整25%最佳实践卸载后清除缓存再重新安装npm install -g anthropic-ai/claude-code能解决 90% 的模块缺失问题nvm 注意事项nvm 的每个 Node 版本有独立的全局包目录切换版本后需要重新安装或使用nvm reinstall-packages迁移Node 版本要求Claude Code 需要 Node.js 18node:前缀的内置模块在低版本中不可用最佳实践建议使用 Volta 代替 nvm 管理 Node.js——Volta 的全局包在不同 Node 版本间共享避免切换版本后模块丢失故障排查流程图flowchart TD A[Cannot find module] -- B[node --version 检查版本] B -- C{Node 18?} C --|否| D[升级 Node.js] C --|是| E[which claude 检查命令] D -- F[npm install -g anthropic-ai/claude-code] E -- G{命令存在?} G --|否| F G --|是| H[检查符号链接] H -- I{链接有效?} I --|否| F I --|是| J[检查 nvm 版本] F -- K[验证: claude --version] J -- L{nvm 切换了版本?} L --|是| M[nvm use reinstall-packages] L --|否| N[设置 NODE_PATH] M -- F N -- K K -- O{启动成功?} O --|是| P[✅ 问题解决] O --|否| Q[npm cache clean 重装] Q -- F