Instalación de Node.js

Esta guía cubre la instalación de Node.js en Windows, macOS y Linux. Node.js es una dependencia clave para las herramientas locales de HagiCode, incluidas OpenSpec, herramientas frontend y varias CLI para desarrolladores.

Requisitos de versión

HagiCode recomienda Node.js 24+ (Node.js mínimo admitido >= 18.0). En la mayoría de los casos, instale la última versión LTS y luego verifique que su versión cumpla con el requisito.

Instalación de Node.js

Método uno: instalador oficial (recomendado)

Visita el Sitio web oficial de Node.js
Descargue la versión LTS (soporte a largo plazo) del instalador de Windows (.msi archivo)
Haga doble clic para ejecutar el instalador.
Siga las indicaciones del asistente de instalación para completar la instalación:
- Aceptar el acuerdo de licencia
- Elija la ruta de instalación (la opción predeterminada está bien)
- Asegúrese de que “Instalar automáticamente las herramientas necesarias” esté marcado
- Haga clic en “Instalar” para iniciar la instalación.
Una vez completada la instalación, haga clic en “Finalizar”

Método dos: usar Winget

Abra PowerShell o símbolo del sistema y ejecute:

winget install OpenJS.NodeJS.LTS

Después de la instalación, vuelva a abrir la terminal para que los cambios surtan efecto.

Método uno: instalador oficial (recomendado)

Visita el Sitio web oficial de Node.js
Descargue el instalador de macOS versión LTS (soporte a largo plazo) (.pkg archivo)
Haga doble clic para ejecutar el instalador.
Siga las indicaciones del asistente de instalación para completar la instalación:
- Haga clic en “Continuar”
- Aceptar el acuerdo de licencia
- Elija el disco de instalación
- Haga clic en “Instalar” e ingrese la contraseña de administrador
Una vez completada la instalación, haga clic en “Cerrar”

Método dos: usar Homebrew

si tienes cerveza casera instalado, puede instalar Node.js a través de la terminal:

brew install node

Homebrew agregará automáticamente Node.js a su RUTA. Si el comando no está disponible, reinicie la terminal o ejecute:

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

Usando el repositorio NodeSource (recomendado)

Esta es la mejor manera de obtener la última versión de 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

Usando el administrador de paquetes apto

Si no necesita la última versión, puede utilizar el repositorio predeterminado de Ubuntu:

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

La versión de Node.js en el repositorio predeterminado puede ser anterior. Después de la instalación, verifique la versión para asegurarse de que cumpla con los requisitos de Node.js >= 18.0 (se recomienda Node.js 24+).

Usando el repositorio NodeSource (recomendado)

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

Usando el Administrador de paquetes yum

sudo yum install -y nodejs npm

Usando el Administrador de paquetes dnf

sudo dnf install -y nodejs npm

El repositorio de software de Fedora generalmente contiene versiones más nuevas de Node.js y se puede instalar directamente a través de dnf.

Uso de herramientas de gestión de versiones

Si necesita cambiar entre varias versiones de Node.js, puede utilizar herramientas de administración de versiones.

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

Después de la instalación, vuelva a cargar la configuración de su shell:

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

ventanas

En Windows, recomendamos usar nvm-ventanas:

Descarga lo último nvm-setup.exe de Lanzamientos de nvm-windows
Ejecute el instalador
Vuelva a abrir el símbolo del sistema o PowerShell

Después de instalar nvm, puedes usarlo para instalar y administrar versiones de 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 (Administrador de nodos rápido)

fnm es una herramienta de administración de versiones de Node.js más rápida y sencilla creada con Rust.

Installing fnm
Using 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

ventanas

uso primicia o ala:

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.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

Aceleración para usuarios de China continental

Si se encuentra en China continental, la descarga de paquetes Node.js y npm puede ser lenta. Aquí hay algunas soluciones de aceleración.

Uso de fuentes de espejo domésticas

npm Taobao Espejo (recomendado)

# 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

Usando nrm para administrar fuentes espejo

nrm (administrador de registro de npm) lo ayuda a cambiar rápidamente las fuentes espejo de 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

Acelerar las descargas del instalador de Node.js

Taobao Node.js Mirror
FastGit Acceleration

Taobao proporciona descargas espejo para los instaladores de Node.js:

Dirección de descarga: https://npmmirror.com/mirrors/node/

Visite la dirección anterior y seleccione la versión que necesita descargar.

Si la descarga de nvm u otras herramientas de GitHub es lenta, puede usar el espejo FastGit:

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

El servicio FastGit puede cambiar; consulte la información oficial.

Espejos caseros domésticos

Si utiliza Homebrew en China continental, puede configurar espejos domésticos para aceleración:

# 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

Gestores de paquetes específicos de China continental

cnpm

cnpm es un cliente npm proporcionado por el equipo de Taobao que usa el espejo de Taobao de forma predeterminada:

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

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

cnpm es mayormente compatible con los comandos npm y puede usarse como reemplazo directo.

Verificación del efecto de aceleración del espejo

Después de configurar los espejos, verifique mediante:

# 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

Verificación de la instalación

Después de la instalación, verifique que Node.js y npm estén instalados correctamente:

# Check Node.js version
node --version

# Check npm version
npm --version

Asegúrese de que la versión de Node.js sea >= 18.0 (se recomienda Node.js 24+). Si la versión es demasiado baja, vuelva a instalarla utilizando los métodos anteriores o utilice herramientas de administración de versiones para instalar la versión correcta.

Salida de verificación de muestra

El resultado de la verificación exitosa debería verse así:

$ node --version
v24.3.0

$ npm --version
10.2.3

Solución de problemas

Problemas de Windows

Command Not Available
PowerShell Execution Policy

si node o npm Los comandos no están disponibles después de la instalación:

Reinicie el símbolo del sistema o PowerShell
Si aún no está disponible, agregue manualmente Node.js a PATH:
- Busque “Variables de entorno” y abra “Editar variables de entorno del sistema”.
- Haga clic en “Variables de entorno”
- Busque “Ruta” en “Variables del sistema” y haga clic en “Editar”
- Agregue la ruta de instalación de Node.js (predeterminada: C:\Program Files\nodejs\)
- Haga clic en “Aceptar” para guardar los cambios.

Si encuentra errores de política de ejecución al utilizar nvm:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas con macOS

Permission Errors
Command Not Available

Si encuentra errores de permisos al instalar paquetes npm globales:

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

Si los comandos no están disponibles después de la instalación, reinicie el terminal o agréguelos manualmente a PATH (generalmente en /usr/local/bin).

Problemas de Linux

Permission Errors
Version Too Old

Si encuentra errores de permisos al instalar paquetes npm globales, se recomienda utilizar las herramientas de administración de versiones de Node.js (como nvm o fnm) en lugar de los administradores de paquetes del sistema.

Comprobando el entorno

Si la verificación falla, verifique lo siguiente:

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

# Check if Node.js is in PATH
which node

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

# Check if Node.js is in PATH
which node

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

# Check version details
node -v

Próximos pasos

Una vez completada la instalación de Node.js, puede continuar con los siguientes pasos:

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.

¿Necesita más ayuda?

Si encuentra problemas que no se tratan aquí:

Visita el Documentación oficial de Node.js
Revisa el Descripción general del producto HagiCode para el contexto actual de productos y herramientas
Visita el Sitio web de HagiCode para conocer los últimos puntos de entrada de soporte