安装 Node.js

本页说明如何在 Windows、macOS 和 Linux 上安装 Node.js。Desktop 与 Microsoft Store 版不再内置 Node.js，它们会直接使用你系统里的 node 与 npm，OpenSpec 和大多数 Agent CLI 也依赖它。

版本要求

需要 Node.js 24 或更高版本，最低要求也是 24。通常直接安装最新的 LTS 版本即可。npm 会随 Node.js 一起安装，不需要单独安装。

哪些安装方式需要它

• Microsoft Store / Desktop：需要，且必须在系统 PATH 中能找到 node 与 npm。

安装 Node.js

Windows

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

1. 访问 Node.js 官方网站
2. 下载 LTS（长期支持） 版本的 Windows 安装程序（.msi 文件），确认版本号不低于 24
3. 双击运行安装程序
4. 按照安装向导的提示完成安装：
   • 接受许可协议
   • 选择安装路径（默认即可）
   • 保持“Add to PATH”处于勾选状态
   • 点击 “Install” 开始安装
5. 安装完成后，点击 “Finish”

方法二：使用 winget

打开 PowerShell 或命令提示符，运行以下命令：

winget install OpenJS.NodeJS.LTS

安装完成后，重新打开终端以使更改生效。

macOS

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

1. 访问 Node.js 官方网站
2. 下载 LTS（长期支持） 版本的 macOS 安装程序（.pkg 文件），确认版本号不低于 24
3. 双击运行安装程序
4. 按照安装向导的提示完成安装：
   • 点击 “继续”
   • 接受许可协议
   • 选择安装磁盘
   • 点击 “安装” 并输入管理员密码
5. 安装完成后，点击 “关闭”

方法二：使用 Homebrew

如果您已经安装了 Homebrew，可以通过终端安装 Node.js：

brew install node

Homebrew 会自动将 Node.js 添加到您的 PATH 中。如果命令不可用，请重新启动终端或运行：

eval "$(/opt/homebrew/bin/brew shellenv)"

Ubuntu/Debian

使用 NodeSource 仓库（推荐）

发行版自带仓库里的 Node.js 通常低于 24，请使用 NodeSource 提供的 24.x 仓库：

# 使用 curl 下载安装脚本
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

不要直接使用 sudo apt-get install nodejs npm 安装发行版自带版本，它大概率不满足 24 的最低要求。

如果不想添加第三方软件源，也可以使用下文的 nvm 或 fnm。

CentOS/RHEL

使用 NodeSource 仓库（推荐）

# 使用 curl 下载安装脚本
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

发行版自带仓库里的 Node.js 通常低于 24，不建议直接使用。也可以改用下文的 nvm 或 fnm。

Fedora

使用 dnf 包管理器

sudo dnf install -y nodejs npm

安装后请运行 node --version 确认版本不低于 24。如果仓库里的版本较低，请改用 NodeSource 的 24.x 仓库，或使用下文的 nvm 或 fnm。

使用版本管理工具

如果您需要在多个 Node.js 版本之间切换，可以使用版本管理工具。

Desktop 用户请注意

在 macOS 和 Linux 上，nvm、fnm 等工具通常只在 shell 配置文件（如 .bashrc、.zshrc）里设置 PATH。从 Dock、应用菜单或桌面图标启动的 Desktop 不会读取这些配置，可能找不到 node。如果您使用版本管理工具，请从已经能运行 node 的终端里启动 Desktop，或改用上文的系统级安装方式。

nvm (Node Version Manager)

安装 nvm

Linux/macOS

请直接复制 nvm 官方仓库 README 中给出的最新安装命令，不要使用旧版本的安装脚本地址。

安装完成后，重新加载您的 shell 配置：

source ~/.bashrc
# 或对于 Zsh 用户
source ~/.zshrc

Windows

在 Windows 上，推荐使用 nvm-windows：

1. 从 nvm-windows releases 下载最新的 nvm-setup.exe
2. 运行安装程序
3. 重新打开命令提示符或 PowerShell

使用 nvm

安装 nvm 后，您可以使用它来安装和管理 Node.js 版本：

# 安装 Node.js 24
nvm install 24

# 切换到 Node.js 24
nvm use 24

# 设置默认版本
nvm alias default 24

# 列出已安装的版本
nvm list

nvm-windows 的 alias 命令不可用，使用 nvm install 24 与 nvm use 24 即可。

fnm (Fast Node Manager)

fnm 是一个更快、更简单的 Node.js 版本管理工具，使用 Rust 构建。

安装 fnm

Linux/macOS

# 使用 curl 安装
curl -fsSL https://fnm.vercel.app/install | bash

# 安装完成后，重新加载 shell 配置
source ~/.bashrc
# 或对于 Zsh 用户
source ~/.zshrc

Windows

使用 scoop 或 winget：

# 使用 scoop
scoop install fnm

# 或使用 winget
winget install Schniz.fnm

使用 fnm

# 安装 Node.js 24
fnm install 24

# 切换到 Node.js 24
fnm use 24

# 设置默认版本
fnm default 24

# 列出已安装的版本
fnm list

中国大陆用户加速

如果您在中国大陆地区，下载 Node.js 和 npm 包可能会遇到速度慢的问题，可以使用国内镜像。

npm 镜像

# 临时使用镜像安装
npm install --registry=https://registry.npmmirror.com

# 永久设置镜像
npm config set registry https://registry.npmmirror.com

# 验证镜像是否设置成功
npm config get registry

Node.js 安装包镜像

Node.js 安装包也有镜像下载地址：https://npmmirror.com/mirrors/node/。访问后选择不低于 24 的版本进行下载。

Homebrew 镜像

如果您在中国大陆使用 Homebrew，可以为 bottle 配置中科大镜像：

export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

验证安装

安装完成后，请在新打开的终端里验证 Node.js 和 npm 是否可用：

# 检查 Node.js 版本，需要 v24.0.0 或更高
node --version

# 检查 npm 版本
npm --version

成功的输出应该类似：

$ node --version
v24.3.0

$ npm --version
11.4.2

如果 node --version 显示的版本低于 24，请按上述方法重新安装，或用版本管理工具切换到 24 及以上。

配置 npm 全局目录

Desktop 会把 Agent CLI 等托管包安装到您本机 npm 的全局目录。如果全局目录位于需要管理员权限的位置，安装时可能出现 EACCES 权限错误。推荐把全局目录改到用户目录，而不是修改系统目录的权限：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

然后把 ~/.npm-global/bin（Windows 为 npm 全局目录本身）加入系统 PATH，并重新启动终端和 Desktop。使用 nvm 或 fnm 时，全局目录已在用户目录下，无需此步骤。

故障排除

Windows 问题

命令不可用

如果在安装后 node 或 npm 命令不可用：

1. 重新启动命令提示符或 PowerShell
2. 如果仍然不可用，手动将 Node.js 添加到 PATH：
   • 搜索 “环境变量” 并打开 “编辑系统环境变量”
   • 点击 “环境变量”
   • 在 “系统变量” 中找到 “Path”，点击 “编辑”
   • 添加 Node.js 的安装路径（默认：C:\Program Files\nodejs\）
   • 点击 “确定” 保存更改
3. 完全退出并重新启动 Desktop

PowerShell 执行策略

如果在使用 nvm 或 npm 脚本时遇到执行策略错误：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS 问题

权限错误

如果在安装全局 npm 包时遇到权限错误，请参考上文的 配置 npm 全局目录，或改用 nvm / fnm。

命令不可用

如果安装后命令不可用，请重新启动终端，并确认 Node.js 所在目录（通常是 /usr/local/bin 或 /opt/homebrew/bin）已在 PATH 中。

Linux 问题

权限错误

如果在安装全局 npm 包时遇到权限错误，请参考上文的 配置 npm 全局目录，或使用 nvm / fnm，而不是用 sudo 安装全局包。

版本过旧

如果通过系统包管理器安装的 Node.js 版本低于 24：

1. 使用 NodeSource 的 24.x 仓库（见上文）
2. 或使用版本管理工具（nvm / fnm）

检查环境

如果验证失败，检查以下内容：

Windows

# 检查 Node.js 是否在 PATH 中
where node

# 检查安装路径
Get-Command node

macOS

# 检查 Node.js 是否在 PATH 中
which node

# 检查安装路径
ls -l $(which node)

Linux

# 检查 Node.js 是否在 PATH 中
which node

# 检查安装路径
ls -l $(which node)

下一步

Node.js 安装完成后，您可以继续以下步骤：

返回安装指南继续完成 Git 等前置条件，并选择适合你的安装方式。

OpenSpec 介绍前往 OpenSpec 独立文档站，了解安装方式、核心概念与规范驱动工作流。

安装 AI Agent CLI查看当前支持的 Agent CLI 官方安装入口，区分一键安装与手动安装 / 认证。

需要更多帮助？

如果您遇到此处未涵盖的问题：

1. 访问 Node.js 官方文档
2. 查看 Desktop 如何使用你的 Node 环境
3. 查看 HagiCode 产品概览 了解当前产品与相关工具链说明