> ## Documentation Index
> Fetch the complete documentation index at: https://api.xcompute.us/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境准备：NVM、Node.js 22 和 npm

> 先完成 Windows、macOS、Linux 的 NVM 和 Node.js 22 安装，再统一用 npm 安装 Claude Code、Codex 和 OpenCode。

这一页是整个集成教程的基础篇。你只要先把 `NVM`、`Node.js 22` 和 `npm` 安装好，后面接入 `Claude Code`、`Codex`、`OpenCode` 就会简单很多。

<Frame>
  <img src="https://raw.githubusercontent.com/nvm-sh/logos/HEAD/nvm-logo-color.svg" alt="NVM 官方 Logo" />
</Frame>

<caption>*NVM 是最常见的 Node 版本管理工具之一*</caption>

<Info>
  `Node.js` 自带 `npm`。装好 `Node.js 22` 后，不需要再单独安装 npm。
</Info>

## 这篇教程适合谁

如果你属于下面任意一种情况，就建议先看这篇：

1. 你还没装过 `Node.js`
2. 你分不清 `Node.js`、`npm`、`nvm` 是什么
3. 你需要在一台电脑上安装多个 AI 编程工具
4. 你希望后面教程里的命令可以直接复制执行

## 你最终会得到什么

做完这篇以后，你会拥有：

1. 一个可以切换 Node 版本的环境
2. 一个稳定的 `Node.js 22` 运行时
3. 一个可用的 `npm`
4. 三个可直接运行的工具：`Claude Code`、`Codex`、`OpenCode`

## 为什么先装 NVM

推荐先装 `NVM`，原因很简单：

1. 你后面可能会同时碰到 `Node 20`、`Node 22`、`Node 24` 的项目。
2. `Claude Code`、`Codex`、`OpenCode` 这些 CLI 更新很快，切 Node 版本会比重装省事很多。
3. Windows 和 macOS / Linux 的安装方式不同，提前统一思路会少踩坑。

## 操作总览

整个过程就四步：

<Steps>
  <Step title="安装 NVM">
    先安装 Node 版本管理工具。
  </Step>

  <Step title="安装 Node.js 22">
    让机器拥有统一的运行环境。
  </Step>

  <Step title="验证 Node 和 npm">
    确认命令已经生效。
  </Step>

  <Step title="安装 AI 编程工具">
    统一安装 `Claude Code`、`Codex`、`OpenCode`。
  </Step>
</Steps>

## 第一步：安装 NVM

<Tabs>
  <Tab title="macOS / Linux">
    如果你是 `Mac` 或 `Linux` 用户，推荐直接使用官方安装脚本。

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
    ```

    安装完成后，重新打开终端。也可以手动加载：

    ```bash theme={null}
    source ~/.bashrc
    ```

    如果你使用的是 `zsh`，改成：

    ```bash theme={null}
    source ~/.zshrc
    ```

    然后验证：

    ```bash theme={null}
    command -v nvm
    ```

    如果终端输出 `nvm`，说明安装成功。
  </Tab>

  <Tab title="Windows">
    Windows 不用官方 POSIX 版 `nvm`，而是使用 `nvm-windows`。

    下载地址：

    * [https://github.com/coreybutler/nvm-windows/releases](https://github.com/coreybutler/nvm-windows/releases)

    你只需要：

    1. 打开下载页
    2. 下载最新的安装包
    3. 双击安装
    4. 安装完成后重开 PowerShell

    安装完成后，打开 PowerShell，先验证：

    ```powershell theme={null}
    nvm version
    ```

    如果能看到版本号，再继续下一步。
  </Tab>
</Tabs>

## 第二步：安装 Node.js 22

<Info>
  这里统一推荐 `Node.js 22`。原因是它足够新、兼容性也好，适合作为这批 CLI 工具的统一基础环境。
</Info>

<Warning>
  如果你的机器里之前已经装过系统级 Node.js，理论上也能继续用，但更容易出现版本冲突。非技术用户优先走 `NVM + Node 22` 最省事。
</Warning>

<Tabs>
  <Tab title="macOS / Linux">
    执行下面三条命令：

    ```bash theme={null}
    nvm install 22
    nvm use 22
    nvm alias default 22
    ```

    然后验证：

    ```bash theme={null}
    node -v
    npm -v
    ```

    正常情况下你会看到：

    1. `node -v` 返回 `v22.x.x`
    2. `npm -v` 返回一个 npm 版本号
  </Tab>

  <Tab title="Windows">
    执行下面命令：

    ```powershell theme={null}
    nvm install 22.22.2
    nvm use 22.22.2
    ```

    然后验证：

    ```powershell theme={null}
    node -v
    npm -v
    ```

    如果命令找不到，请先完全关闭 PowerShell 再重新打开一次。
  </Tab>
</Tabs>

## 第三步：统一安装常用 CLI

下面这三个是本次集成教程会重点讲到的工具：

1. `Claude Code`：Anthropic 官方编码 Agent
2. `Codex`：OpenAI 官方编码 Agent
3. `OpenCode`：开源编码 Agent

```bash theme={null}
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g opencode-ai
```

## 第四步：验证 CLI 是否可用

依次执行：

```bash theme={null}
claude --version
codex --help
opencode --version
```

<Tip>
  如果某个命令报错，优先检查当前终端是否已经切到 `Node 22`，再检查全局 npm 安装路径是否生效。
</Tip>

## 看到什么算成功

1. `claude --version` 能返回版本号
2. `codex --help` 能显示帮助信息
3. `opencode --version` 能返回版本号

只要这三项都正常，后面的接入教程基本就可以继续了。

## 常见问题

### 安装完 `nvm` 后提示 `command not found`

通常是 shell 配置还没重新加载。

* `bash`：`source ~/.bashrc`
* `zsh`：`source ~/.zshrc`
* Windows：重开一个 PowerShell 窗口

### 为什么不直接安装系统 Node？

可以，但后面切版本会很痛苦。你既然要同时跑多个 AI 编程工具，`NVM` 会更稳。

### 为什么推荐 `Node 22`？

因为它当前对这批 CLI 工具的兼容性最好，也比较适合做统一开发环境。

### 安装 npm 工具时提示权限不足怎么办？

1. 优先确认你是在 `nvm` 管理的 Node 环境里执行
2. 重新打开终端后再执行一次
3. 不要默认上来就加 `sudo npm install -g ...`

### Windows 用户需要装 Git 吗？

如果你后面要更顺畅地用 `Claude Code`、`Codex`、`OpenCode`，建议安装 Git。

## 下一步：进入具体接入

<Columns cols={2}>
  <Card title="Claude Code 接入" icon="terminal" href="/claude-code">
    用 Anthropic 官方 CLI 接入 Xcompute。
  </Card>

  <Card title="Codex 接入" icon="code" href="/codex">
    用 OpenAI 官方 Codex CLI 接入 Xcompute。
  </Card>

  <Card title="OpenCode 接入" icon="code" href="/opencode">
    用 OpenAI 兼容 provider 配置接入 Xcompute。
  </Card>
</Columns>