安裝 Node.js

本指南涵蓋 Windows、macOS 和 Linux 上的 Node.js 安裝。 Node.js 是 HagiCode 本機工具的關鍵依賴項，包括 OpenSpec、前端工具和多個開發人員 CLI。

:::提示[版本要求] HagiCode 建議 Node.js 24+（最低支援的 Node.js >= 18.0）。在大多數情況下，安裝最新的 LTS 版本，然後驗證您的版本是否符合要求。 :::

安裝 Node.js

Windows

方法一：官方安裝程式（建議）

1. 參觀 Node.js 官方網站
2. 下載 LTS（長期支援） 版本 Windows 安裝程式（.msi 文件）
3. 雙擊運行安裝程序
4. 依照安裝精靈提示完成安裝：
   • 接受授權協議
   • 選擇安裝路徑（預設即可）
   • 確保選取“自動安裝必要的工具”
   • 點選「安裝」開始安裝
5. 安裝完成後，點選“完成”

方法二：使用winget

開啟 PowerShell 或命令提示字元並執行：

winget install OpenJS.NodeJS.LTS

安裝後，重新開啟終端以使變更生效。

macOS

方法一：官方安裝程式（建議）

1. 參觀 Node.js 官方網站
2. 下載 LTS（長期支援） 版本 macOS 安裝程式（.pkg 文件）
3. 雙擊運行安裝程序
4. 依照安裝精靈提示完成安裝：
   • 點擊“繼續”
   • 接受授權協議
   • 選擇安裝磁碟
   • 點選“安裝”並輸入管理員密碼
5. 安裝完成後，點選“關閉”

方法二：使用自製軟體

如果你有 自製 安裝完畢後，您可以透過終端機安裝 Node.js：

brew install node

:::提示 Homebrew 會自動將 Node.js 加入到您的 PATH 中。如果該命令不可用，請重新啟動終端或運行：

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

:::

Ubuntu/Debian

使用 NodeSource 儲存庫（推薦）

這是獲取最新 Node.js 版本的最佳方法：

# Use curl to download the installation script
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

使用 apt 套件管理器

如果不需要最新版本，可以使用預設的 Ubuntu 儲存庫：

sudo apt-get update
sudo apt-get install -y nodejs npm

:::注意 預設儲存庫中的 Node.js 版本可能較舊。安裝後，檢查版本以確保其滿足 Node.js >= 18.0 要求（建議使用 Node.js 24+）。 :::

CentOS/RHEL

使用 NodeSource 儲存庫（推薦）

# Use curl to download the installation script
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

使用 yum 套件管理器

sudo yum install -y nodejs npm

Fedora

使用 dnf 套件管理器

sudo dnf install -y nodejs npm

:::提示 Fedora 的軟體儲存庫通常包含較新的 Node.js 版本，可以直接透過 dnf 安裝。 :::

使用版本管理工具

如果需要在多個 Node.js 版本之間切換，可以使用版本管理工具。

nvm（節點版本管理器）

Installing nvm

Linux/macOS

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

# Or install using wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

安裝後，重新載入 shell 配置：

source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

窗戶

在 Windows 上，我們建議使用 nvm-windows:

1. 下載最新的 nvm-setup.exe 來自 nvm-windows 版本
2. 運行安裝程式
3. 重新開啟命令提示字元或 PowerShell

Using nvm

安裝nvm後，您可以使用它來安裝和管理Node.js版本：

# Install the latest LTS version (recommended)
nvm install --lts

# Install Node.js 24 (recommended version)
nvm install 24

# Install a specific Node.js version
nvm install 18.20.0

# List installed versions
nvm list

# Switch to a specified Node.js version
nvm use 24

# Set default version
nvm alias default 24

# Windows nvm-windows syntax is slightly different
nvm install 24
nvm use 24

fnm（快速節點管理器）

fnm 是一個使用 Rust 建構的更快、更簡單的 Node.js 版本管理工具。

Installing fnm

Linux/macOS

# Install using curl
curl -fsSL https://fnm.vercel.app/install | bash

# After installation, reload shell configuration
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

窗戶

使用 湯匙 或 溫蓋特:

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.fnm

Using fnm

# Install the latest LTS version (recommended)
fnm install --lts

# Install Node.js 24 (recommended version)
fnm install 24

# Install a specific Node.js version
fnm install 18.20.0

# List installed versions
fnm list

# Switch to a specified Node.js version
fnm use 24

# Set default version
fnm default 24

中國大陸用戶加速

如果您在中國大陸，下載 Node.js 和 npm 套件可能會很慢。以下是一些加速解決方案。

使用國內鏡像來源

npm 淘寶鏡像（建議）

# Temporarily use Taobao mirror
npm install --registry=https://registry.npmmirror.com

# Permanently set Taobao mirror
npm config set registry https://registry.npmmirror.com

# Verify mirror is set successfully
npm config get registry

使用nrm管理鏡像來源

nrm（npm登錄管理員）可協助您快速切換npm鏡像來源：

# Install nrm
npm install -g nrm

# List available mirror sources
nrm ls

# Switch to Taobao mirror
nrm use taobao

# Test mirror source speed
nrm test

加速 Node.js 安裝程式下載

Taobao Node.js Mirror

淘寶提供Node.js安裝程式的鏡像下載：

• 下載網址：https://npmmirror.com/mirrors/node/

造訪上述地址，選擇您需要下載的版本。

FastGit Acceleration

如果從 GitHub 下載 nvm 或其他工具很慢，可以使用 FastGit 映像：

# Use FastGit to accelerate nvm installation
curl -o- https://fastgit.org/nvm-sh/nvm/raw/master/install.sh | bash

:::注意 FastGit服務可能會有變動，請以官方資訊為準。 :::

國產自製鏡子

如果您在中國大陸使用Homebrew，可以配置國內鏡像進行加速：

# Install Homebrew using domestic mirror
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

# Or use USTC mirror
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

中國大陸特定套件管理器

中國製造商協會

cnpm是淘寶團隊提供的npm客戶端，預設使用淘寶鏡像：

# Install cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com

# Use cnpm to install packages
cnpm install <package-name>

:::提示 cnpm 與 npm 指令大部分相容，可以直接替換。 :::

驗證鏡像加速效果

設定鏡像後，透過以下方式驗證：

# Test download speed
time npm install express --registry=https://registry.npmmirror.com

# Compare with official source speed
time npm install express --registry=https://registry.npmjs.org

驗證安裝

安裝後，驗證 Node.js 和 npm 是否已正確安裝：

# Check Node.js version
node --version

# Check npm version
npm --version

:::注意 確保 Node.js 版本 >= 18.0（建議使用 Node.js 24+）。如果版本過低，請使用上述方法重新安裝或使用版本管理工具安裝正確的版本。 :::

驗證輸出樣本

成功的驗證輸出應如下所示：

$ node --version
v24.3.0

$ npm --version
10.2.3

故障排除

Windows 問題

Command Not Available

如果 node 或 npm 安裝後指令不可用：

1. 重新啟動命令提示字元或 PowerShell
2. 如果仍然不可用，請手動將 Node.js 新增至 PATH：
   • 搜尋“環境變數”並開啟“編輯系統環境變數”
   • 點擊“環境變數”
   • 在“系統變數”中找到“Path”，然後點擊“編輯”
   • 新增Node.js安裝路徑（預設： C:\Program Files\nodejs\)
   • 按一下「確定」儲存更改

PowerShell Execution Policy

如果使用nvm時遇到執行策略錯誤：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS 問題

Permission Errors

如果在安裝全域npm套件時遇到權限錯誤：

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Command Not Available

如果安裝後命令不可用，請重新啟動終端或手動新增至PATH（通常在 /usr/local/bin).

Linux問題

Permission Errors

如果在安裝全域 npm 套件時遇到權限錯誤，建議使用 Node.js 版本管理工具（如 nvm 或 fnm）而不是系統套件管理器。

Version Too Old

如果透過系統套件管理器安裝的 Node.js 版本太舊：

1. 使用 NodeSource 儲存庫（推薦，請參閱上文）
2. 或使用版本管理工具（nvm/fnm）

檢查環境

如果驗證失敗，請檢查以下內容：

Windows

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

macOS

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

Linux

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

# Check version details
node -v

下一步

Node.js 安裝完成後，可以繼續執行下列步驟：

Install OpenSpec Install the OpenSpec specification-driven development tool to manage proposals, specs, and changes.

Install AI Agent CLI Use one registry for the official install entries for Claude Code, Codex, Gemini, GitHub Copilot, CodeBuddy, OpenCode, Kimi, QoderCLI, and Kiro.

Return to Installation Guide Return to the main installation guide to continue configuring other dependencies.

需要更多幫助嗎？

如果您遇到此處未涵蓋的問題：

1. 參觀 Node.js 官方文檔
2. 回顧 HagiCode產品概述 針對目前產品和工具環境
3. 參觀 HagiCode網站 取得最新的支援入口點