Node.js 开发环境准备

在 Windows、macOS 和 Linux 上安装 NVM、Node.js 与 npm，为编程 Agent 准备运行环境。

适用对象：TokenFlash API 中转站用户，需要配置 Node.js 开发环境以运行 Claude Code、Codex、OpenCode 等 AI 编程工具。

最后更新：2026-07-13

难度：入门级

概述

为什么需要配置 Node.js 环境？

在 AI 编程时代，越来越多的开发工具依赖 Node.js 运行时环境：

工具	最低 Node.js 版本要求	说明
Claude Code	Node.js 22+	Anthropic 官方 CLI 编程工具
OpenAI Codex CLI	Node.js 22+	OpenAI 命令行编程助手
OpenCode	Node.js 22+	开源 AI 编程工具
Cursor	内置	自带运行时，无需额外配置

如果你使用 TokenFlash API 连接这些工具，第一步就是要确保本地 Node.js 环境已正确配置。

为什么选择 NVM？

NVM（Node Version Manager）是 Node.js 的版本管理工具：

版本隔离：不同项目可以使用不同的 Node.js 版本，互不干扰
一键切换：nvm use 22 即可切换到 Node.js 22
安全卸载：不需要时可以完全移除，不留残余
多版本共存：同时安装 Node.js 18、20、22 等多个版本

如果你之前通过官网安装包直接安装过 Node.js，建议先卸载后再使用 NVM 管理，以避免版本冲突。

整体路线图

┌──────────┐   ┌──────────┐   ┌────────┐   ┌──────────┐
│ 安装 NVM │ → │ 安装 Node│ → │ 配置npm│ → │ 安装工具 │
│          │   │ 22       │   │        │   │ CLI      │
└──────────┘   └──────────┘   └────────┘   └──────────┘

预计总耗时：15-30 分钟（取决于网络速度）。

NVM 安装与配置

Windows 平台

Windows 下的 Node.js 版本管理工具是 nvm-windows，与 macOS/Linux 的 nvm 是不同的项目。

方法一：使用 winget 安装（推荐）

以管理员身份打开 PowerShell，执行：

winget install CoreyButler.NVMforWindows

安装完成后，必须关闭并重新打开 PowerShell 窗口，使环境变量生效。

nvm version

如果不重启终端，可能会报 nvm : 无法将"nvm"项识别为 cmdlet 错误。

方法二：手动下载安装包

前往 nvm-windows Releases 下载最新版本的 nvm-setup.exe，双击安装即可。

方法三：使用 Chocolatey 安装

choco install nvm

Windows 环境变量确认：

安装后检查以下环境变量是否正确：

NVM_HOME = C:\Users\<用户名>\AppData\Roaming\nvm
NVM_SYMLINK = C:\Program Files\nodejs

PATH 中应包含 %NVM_HOME%、%NVM_SYMLINK% 和 %APPDATA%\npm。如果 PATH 中同时存在旧版 Node.js 路径，会导致版本切换不生效。

macOS 平台

方法一：使用 curl 安装脚本（官方推荐）

先检查 Xcode Command Line Tools：

xcode-select -p

如果输出类似 /Library/Developer/CommandLineTools，说明已安装。如果没有，先安装：

xcode-select --install

系统会弹出安装对话框，点击「安装」并等待完成。

安装 NVM：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

💡 如果 curl 下载失败，可以用浏览器打开 https://github.com/nvm-sh/nvm/releases 下载 install.sh，然后执行 bash ~/Downloads/install.sh。

安装脚本会自动配置 .zshrc。如果没有自动配置，手动添加：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

使配置生效：

source ~/.zshrc

验证安装：

nvm --version

方法二：使用 Homebrew 安装

brew install nvm
mkdir ~/.nvm

安装后同样需要手动配置 shell（参考上面的配置步骤）。

Linux 平台

确保已安装 curl：

# Debian/Ubuntu
sudo apt update && sudo apt install -y curl

# CentOS/RHEL/Fedora
sudo dnf install -y curl

# Arch Linux
sudo pacman -S curl

安装 NVM：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm --version

Windows Subsystem for Linux (WSL)

在 WSL 中安装方式与 Linux 完全一致。打开 WSL 终端后，按照 Linux 步骤操作即可。

WSL 中的 NVM 和 Node.js 与 Windows 系统是完全独立的。不要混用 Windows 的 nvm-windows 和 WSL 中的 nvm。

NVM 常用命令

命令	说明	示例
`nvm install <version>`	安装指定版本	`nvm install 22`
`nvm use <version>`	切换到指定版本	`nvm use 22`
`nvm ls` / `nvm list`	列出已安装版本	`nvm ls`
`nvm ls-remote`	列出远程可安装版本	`nvm ls-remote`
`nvm alias default <version>`	设置默认版本	`nvm alias default 22`
`nvm uninstall <version>`	卸载指定版本	`nvm uninstall 20`
`nvm current`	查看当前版本	`nvm current`
`nvm which <version>`	查看版本安装路径	`nvm which 22`

安装 Node.js 22

Node.js 22 是目前最新的 LTS 版本，将支持到 2027 年 4 月。

nvm install 22

安装完成后会自动切换到该版本。然后设置默认版本：

nvm alias default 22

验证版本：

node -v   # 应输出 v22.x.x
npm -v    # 应输出 10.x.x

Windows 特别注意

在 Windows 上需要确认环境变量配置正确。检查 NVM_HOME 和 NVM_SYMLINK 是否存在于系统环境变量中。如果 PATH 中同时存在旧版 Node.js 路径，会导致版本切换不生效。

Windows 上 nvm use 需要在管理员权限的终端中运行，因为它需要创建符号链接。

npm 配置

配置 npm 镜像源

由于 npm 官方仓库在国内访问较慢，建议配置国内镜像源。

# 查看当前镜像源
npm config get registry

# 切换到淘宝镜像（推荐国内用户）
npm config set registry https://registry.npmmirror.com

# 切换回官方源
npm config set registry https://registry.npmjs.org

镜像源	地址	说明
官方源	https://registry.npmjs.org	最权威
淘宝镜像	https://registry.npmmirror.com	国内最快
华为镜像	https://mirrors.huaweicloud.com/repository/npm	备选

npm 常用命令

npm install -g <package-name>          # 全局安装
npm install                            # 安装项目依赖
npm install <package> --save           # 安装并保存依赖
npm install <package> --save-dev       # 安装并保存开发依赖
npm uninstall -g <package>             # 卸载全局包
npm list -g --depth=0                  # 查看全局已安装包
npm view <package-name> versions       # 查看某个包的所有版本
npm cache clean --force                # 清除缓存

配置全局安装路径

如果你使用 NVM，全局包默认安装在 NVM 的版本目录下，一般不需要额外配置。

如果需要自定义：

npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

npm 配置文件（.npmrc）

# 查看用户级配置
npm config list

# 查看配置文件位置
npm config get userconfig

常见的 .npmrc 配置示例：

registry=https://registry.npmmirror.com
engine-strict=true
save-exact=true

安装 AI 编程工具

Node.js 环境就绪后，统一安装常用 AI 编程 CLI：

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g opencode-ai

验证安装：

claude --version
codex --version
opencode --version

环境验证

一键验证脚本

macOS / Linux：

echo "NVM: $(nvm --version 2>/dev/null || echo '未安装')"
echo "Node: $(node -v 2>/dev/null || echo '未安装')"
echo "npm: $(npm -v 2>/dev/null || echo '未安装')"
echo "镜像源: $(npm config get registry 2>/dev/null || echo '未知')"
echo "node路径: $(which node 2>/dev/null || echo '未找到')"

Windows PowerShell：

Write-Host "NVM: $(nvm version 2>$null)"
Write-Host "Node: $(node -v 2>$null)"
Write-Host "npm: $(npm -v 2>$null)"
Write-Host "镜像源: $(npm config get registry 2>$null)"

预期输出

🔍 ===== Node.js 环境验证 =====

📦 NVM 版本:
0.40.3

🟢 Node.js 版本:
v22.14.0
✅ Node.js 版本满足要求 (>= 22)

📦 npm 版本:
10.9.2

📂 路径信息:
  node: /home/user/.nvm/versions/node/v22.14.0/bin/node
  npm:  /home/user/.nvm/versions/node/v22.14.0/bin/npm
  npm 全局: /home/user/.nvm/versions/node/v22.14.0

🌐 npm 镜像源: https://registry.npmmirror.com

🔍 ===== 验证完成 =====

常见问题

nvm 命令找不到

# macOS/Linux：检查配置文件
cat ~/.zshrc | grep NVM
cat ~/.bashrc | grep NVM

# 重新加载
source ~/.zshrc   # 或 source ~/.bashrc

# Windows：重启 PowerShell

如果仍然找不到，检查配置文件末尾是否包含：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Node 版本切换不生效

Windows：必须以管理员身份运行终端
macOS/Linux：检查 which node 是否指向 ~/.nvm/versions/...，如果指向 /usr/local/bin/node，说明有其他 Node 安装冲突
检查是否有 Homebrew 安装的 Node.js：brew list node 2>/dev/null && echo "有冲突"，如有则卸载：brew uninstall node
检查 PATH 中是否有其他 Node.js 路径优先级更高

Windows 下检查所有 Node.js 路径：

echo $env:PATH -split ';' | Select-String -Pattern "node"

npm 权限不足（EACCES）

优先确认你是在 NVM 管理的 Node 环境里执行：

which node   # 应输出 ~/.nvm/versions/node/...

NVM 将 Node 安装在用户目录下，一般不需要 sudo。

npm install 卡住或超时

切换到国内镜像源：npm config set registry https://registry.npmmirror.com
清除缓存重试：npm cache clean --force && npm install
增加超时：npm config set fetch-timeout 120000

Windows 下 nvm install 下载失败

nvm node_mirror https://npmmirror.com/mirrors/node/
nvm npm_mirror https://npmmirror.com/mirrors/npm/

Windows PowerShell 执行策略问题

以管理员身份执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Node 版本找不到

nvm: No available version of node found for xxx

# 更新 NVM 远程版本列表
nvm ls-remote | tail -20

# 重新安装
nvm install 22 --latest-npm

代理设置

# npm 代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

# 取消代理
npm config delete proxy
npm config delete https-proxy

# NVM 下载镜像（Node.js 二进制文件）
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

Windows PowerShell 设置代理：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

下一步：进入具体接入

code

OpenCode 接入 TokenFlash（推荐）

使用 OpenAI 兼容 provider 配置 TokenFlash。

terminal

Claude Code 接入

用 Anthropic 官方 CLI 接入 TokenFlash。