Node.js环境安装

Windows 平台安装 Node.js

三大 AI 编程工具的必备运行环境

💡 重要说明

Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：node -v

方法一：官方安装包（推荐）​

1. 访问 Node.js 官网：https://nodejs.org/zh-cn/download

2. 下载 LTS（长期支持）版本的 Windows Installer (.msi)

3. 运行安装包，采用默认配置完成安装

4. 安装程序会自动配置系统 PATH 环境变量

方法二：包管理器安装

使用 Winget

Windows 11 或 Windows 10 最新版：

winget install OpenJS.NodeJS.LTS

使用 Chocolatey

需先安装 Chocolatey：

choco install nodejs-lts

使用 Scoop

scoop install nodejs-lts

验证安装

打开命令提示符或 PowerShell，执行：

node --version
npm --version

如果显示版本号（如 v18.x.x 或更高），说明安装成功。

常见问题

提示"不是内部或外部命令"

重新打开终端窗口

检查 PATH 环境变量是否包含 Node.js 路径

重启电脑后再试

安装失败

以管理员身份运行安装程序

关闭杀毒软件后重试

检查系统盘空间是否充足

macOS 平台安装 Node.js

三大 AI 编程工具的必备运行环境

💡 重要说明

Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：node -v

方法一：Homebrew 包管理器（推荐）​

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node

# 验证安装
node --version
npm --version

方法二：官方安装包

1. 访问 Node.js 官网：https://nodejs.org

2. 下载 LTS 版本的 .pkg 安装包

3. 运行安装程序并按照提示完成安装

验证安装

打开终端，执行：

node --version
npm --version

如果显示版本号（如 v18.x.x 或更高），说明安装成功。

常见问题

Homebrew 安装慢

可以使用国内镜像：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"

权限问题

如果遇到权限问题，不要使用 sudo，而是修复 Homebrew 权限：

sudo chown -R $(whoami) /usr/local/bin /usr/local/lib

无法连接Unable to connect to Anthropic services

• 环境：MacOS（任意版本）/ Windows 10/11

• 前提：所在地区已在 Anthropic 支持列表 中，网络可正常访问外网

• 核心原因：Claude 首次启动的引导流程未完成，导致 API 连接拦截

通过修改 Claude 配置文件 .claude.json，新增 hasCompletedOnboarding: true 配置项，直接跳过首次启动引导，即可解决连接问题。Mac 和 Windows 仅文件路径不同，配置内容完全一致。

在~目录找到.claude.json，修改如下,在最后添加 "hasCompletedOnboarding": true

{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "f5afdd05117c901a4a5a0761d08230bfcbb76f9fd380ff7bc144cc12c52e55aa",
  "projects": {
    "/home/xxx": {
      "allowedTools": [],
      "history": [],
      "mcpContextUris": [],
      "mcpServers": {},
      "enabledMcpjsonServers": [],
      "disabledMcpjsonServers": [],
      "hasTrustDialogAccepted": false,
      "projectOnboardingSeenCount": 0,
      "hasClaudeMdExternalIncludesApproved": false,
      "hasClaudeMdExternalIncludesWarningShown": false
    }
  },  //这里要加逗号，注意英文的
  "hasCompletedOnboarding": true  // 新增字段放在这里，注意位置
}

Linux 平台安装 Node.js

三大 AI 编程工具的必备运行环境

💡 重要说明

Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：node -v

Ubuntu/Debian 发行版

使用 NodeSource 仓库（推荐）​

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

CentOS/RHEL 发行版

bash

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

Fedora 发行版

sudo dnf install -y nodejs npm
# 验证安装
node --version
npm --version

Arch Linux

sudo pacman -S nodejs npm
# 验证安装
node --version
npm --version

使用 nvm（推荐进阶用户）​

nvm 允许您管理多个 Node.js 版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 查看远程最新版本
nvm ls-remote

# 安装 Node.js LTS
nvm install --lts

# 设置默认版本
nvm use --lts
nvm alias default node

常见问题

权限问题

如果遇到权限问题，可以配置 npm 使用用户目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

版本过旧

如果系统自带的 Node.js 版本过旧，建议使用 NodeSource 仓库或 nvm 安装最新 LTS 版本。