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

方案	适用场景	推荐指数	难度
方案一：重装	通用解决方案	⭐⭐⭐⭐⭐	低
方案二：检查 Node	nvm 问题	⭐⭐⭐⭐⭐	低
方案三：修复 NODE_PATH	路径问题	⭐⭐⭐	低
方案四：修复软链接	链接断裂	⭐⭐⭐⭐	中
方案五：nvm 迁移	版本切换	⭐⭐⭐⭐	中
方案六：npx/Volta	替代方案	⭐⭐⭐	低

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