ljwx-harbor/CLAUDE-CODE-SETUP.md

Claude Code 版本无关安装方案

问题说明

通过 npm install -g @anthropic-ai/claude-code 安装时，会绑定到当前 npm 版本的全局目录。当切换 Node.js/npm 版本（特别是使用 nvm 时），Claude Code 就会失效。

🎯 解决方案对比

方案	优点	缺点	推荐指数
npx 包装器	零配置，自动使用最新版	首次运行稍慢	⭐⭐⭐⭐⭐
nvm 默认包	自动同步到所有版本	需要重新安装现有版本	⭐⭐⭐⭐
独立版本	完全隔离，最稳定	需要专用 Node.js 版本	⭐⭐⭐⭐
pnpm 全局	跨版本共享	需要安装 pnpm	⭐⭐⭐

---

方案 1：npx 包装器（推荐）⭐⭐⭐⭐⭐

优势

• ✅ 零配置：不需要全局安装
• ✅ 自动更新：每次运行使用最新版本
• ✅ 版本无关：切换 Node.js 版本无影响
• ✅ 已部署：现在就可以使用

使用方式

# 立即可用（已自动配置）
claude-code

# 或直接使用 npx
npx @anthropic-ai/claude-code

工作原理

包装器位置：~/bin/claude-code → /Users/brunogao/work/codes/tools/macos/bin/claude-code-wrapper.sh

每次运行时通过 npx 动态加载，无需全局安装。

生效方式

# 方式 1：重新加载 shell
source ~/.zshrc

# 方式 2：新建终端窗口
# 直接打开新终端即可

---

方案 2：nvm 默认包 ⭐⭐⭐⭐

优势

• ✅ 自动安装：切换/安装新版本时自动安装 Claude Code
• ✅ 原生性能：真实全局安装，无额外开销
• ✅ nvm 集成：充分利用 nvm 的包管理能力

部署步骤

# 一键配置
/Users/brunogao/work/codes/tools/macos/scripts/claude-code-nvm-setup.sh

手动配置（可选）

# 1. 编辑 nvm 默认包列表
echo "@anthropic-ai/claude-code" >> ~/.nvm/default-packages

# 2. 重新安装当前版本（可选）
nvm reinstall-packages current

# 3. 以后安装新版本时自动包含
nvm install 20  # 会自动安装 claude-code

验证

# 切换版本测试
nvm use 18
which claude-code  # 应该能找到

nvm use 20
which claude-code  # 应该能找到

---

方案 3：独立版本（最稳定）⭐⭐⭐⭐

优势

• ✅ 完全隔离：使用专用 LTS Node.js 版本
• ✅ 零干扰：不受系统 Node.js 切换影响
• ✅ 稳定性：锁定特定 Node.js 版本，避免兼容性问题

部署步骤

# 一键安装
/Users/brunogao/work/codes/tools/macos/scripts/claude-code-standalone-setup.sh

工作原理

1. 安装专用 Node.js 22.12.0 LTS
2. 在该版本下安装 Claude Code
3. 创建智能启动器自动切换到专用版本
4. 系统 Node.js 版本改变不影响 Claude Code

使用

# 自动使用独立版本
claude-code

# 或显式调用
claude-code-standalone

---

方案 4：pnpm 全局管理 ⭐⭐⭐

适用场景

• 已经在使用 pnpm
• 需要跨 Node.js 版本共享全局包

部署步骤

# 1. 安装 pnpm
npm install -g pnpm

# 2. 使用 pnpm 安装 Claude Code
pnpm add -g @anthropic-ai/claude-code

# 3. pnpm 的全局目录独立于 Node.js 版本

优势

• pnpm 全局包目录统一，不受 nvm 影响
• 更高效的磁盘空间利用

---

🚀 快速开始

立即使用（推荐）

# 方式 1：使用已配置的 npx 包装器
source ~/.zshrc
claude-code --version

# 方式 2：直接使用 npx
npx @anthropic-ai/claude-code --version

选择方案对照表

你的情况	推荐方案
不想全局安装，只想快速使用	方案 1：npx 包装器
经常切换 Node.js 版本	方案 2：nvm 默认包 或 方案 1
追求最大稳定性	方案 3：独立版本
已在使用 pnpm	方案 4：pnpm 全局
不确定选哪个	方案 1：npx 包装器（零配置）

---

验证安装

# 检查 Claude Code 是否可用
claude-code --version

# 切换 Node.js 版本测试
nvm use 18
claude-code --version  # 应该仍然可用

nvm use 20
claude-code --version  # 应该仍然可用

---

故障排除

问题 1：找不到 claude-code 命令

# 检查 PATH
echo $PATH | grep "$HOME/bin"

# 如果没有，重新加载配置
source ~/.zshrc

# 或重新创建链接
ln -sf /Users/brunogao/work/codes/tools/macos/bin/claude-code-wrapper.sh ~/bin/claude-code

问题 2：npx 运行很慢

# 切换到方案 2 或 3
# 使用真实的全局安装
/Users/brunogao/work/codes/tools/macos/scripts/claude-code-nvm-setup.sh

问题 3：nvm 切换后还是找不到

# 检查 default-packages 配置
cat ~/.nvm/default-packages

# 应该包含：
# @anthropic-ai/claude-code

---

卸载旧版本

# 卸载所有 Node.js 版本中的 Claude Code
nvm use 18 && npm uninstall -g @anthropic-ai/claude-code
nvm use 20 && npm uninstall -g @anthropic-ai/claude-code
nvm use 21 && npm uninstall -g @anthropic-ai/claude-code

# 然后使用推荐方案重新部署

---

总结

已为你配置方案 1（npx 包装器），现在就可以使用：

# 重新加载配置
source ~/.zshrc

# 立即使用
claude-code --version

如果需要更高性能或更好的集成，可以随时切换到方案 2 或 3。