Установка Node.js

В этом руководстве рассматривается установка Node.js в Windows, macOS и Linux. Node.js — это ключевая зависимость для локальных инструментов HagiCode, включая OpenSpec, инструменты внешнего интерфейса и несколько интерфейсов командной строки для разработчиков.

Требования к версии

HagiCode рекомендует Node.js 24+ (минимальная поддерживаемая версия Node.js >= 18.0). В большинстве случаев установите последнюю версию LTS, а затем убедитесь, что ваша версия соответствует требованиям.

Установка Node.js

Windows

Способ первый: официальный установщик (рекомендуется)

1. Посетите Официальный сайт Node.js
2. Загрузите установщик Windows версии LTS (долгосрочная поддержка) (.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

После установки перезагрузите конфигурацию оболочки:

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

Окна

В Windows мы рекомендуем использовать NVM-окна:

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 — это более быстрый и простой инструмент управления версиями Node.js, созданный с помощью Rust.

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 Taobao Mirror (рекомендуется)

# 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

Taobao предоставляет зеркальные загрузки для установщиков Node.js:

• Адрес загрузки: https://npmmirror.com/mirrors/node/

Посетите указанный выше адрес и выберите версию, которую необходимо загрузить.

FastGit Acceleration

Если загрузка nvm или других инструментов с GitHub идет медленно, вы можете использовать зеркало 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

cnpm — это клиент npm, предоставленный командой Taobao, который по умолчанию использует зеркало Taobao:

# 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:
   • Найдите «Переменные среды» и откройте «Редактировать переменные среды системы».
   • Нажмите «Переменные среды».
   • Найдите «Путь» в «Системных переменных» и нажмите «Изменить».
   • Добавьте путь установки 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. Посетите Веб-сайт ХагиКод для получения последних точек входа в службу поддержки