# 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 版本无影响
- ✅ **已部署**：现在就可以使用

### 使用方式

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

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

### 工作原理

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

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

### 生效方式

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

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

---

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

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

### 部署步骤

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

### 手动配置（可选）

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

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

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

### 验证

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

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

---

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

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

### 部署步骤

```bash
# 一键安装
/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

### 使用

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

# 或显式调用
claude-code-standalone
```

---

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

### 适用场景
- 已经在使用 pnpm
- 需要跨 Node.js 版本共享全局包

### 部署步骤

```bash
# 1. 安装 pnpm
npm install -g pnpm

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

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

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

---

## 🚀 快速开始

### 立即使用（推荐）

```bash
# 方式 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 包装器**（零配置） |

---

## 验证安装

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

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

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

---

## 故障排除

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

```bash
# 检查 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 运行很慢

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

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

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

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

---

## 卸载旧版本

```bash
# 卸载所有 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 包装器）**，现在就可以使用：

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

# 立即使用
claude-code --version
```

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