安裝 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 產品概覽 了解目前產品與相關工具鏈說明