【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

原因分类表

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. 各方案对比总结

5. 常见问题 FAQ

5.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-code

5.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 --version

5.6 如何查看全局已安装的包

npm list -g --depth=0 # 查看所有全局包

5.7 符号链接断裂如何检测

# 检查符号链接是否有效 readlink -f $(which claude) # 如果路径不存在，说明链接断裂

5.8 Windows 上报 Cannot find module

Windows 上路径分隔符是\，可能影响模块解析。确保使用正斜杠/或使用 PowerShell 的路径处理。

5.9 CI/CD 中模块缺失

确保 CI 配置中先安装 Claude Code：

- run: npm install -g @anthropic-ai/claude-code - run: claude --version

5.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. 总结

1. 根本原因：模块缺失最常见原因是 nvm 版本切换后全局包不共享（35%）和安装不完整（25%）
2. 最佳实践：卸载后清除缓存再重新安装npm install -g @anthropic-ai/claude-code，能解决 90% 的模块缺失问题
3. nvm 注意事项：nvm 的每个 Node 版本有独立的全局包目录，切换版本后需要重新安装或使用nvm reinstall-packages迁移
4. Node 版本要求：Claude Code 需要 Node.js 18+，node:前缀的内置模块在低版本中不可用
5. 最佳实践建议：使用 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