Instalación de Node.js

Esta página explica cómo instalar Node.js en Windows, macOS y Linux. Desktop y la versión de Microsoft Store ya no incluyen Node.js: usan directamente los node y npm de su sistema, y OpenSpec y la mayoría de los Agent CLI también dependen de él.

Requisitos de versión

Se requiere Node.js 24 o superior, y el mínimo también es 24. Normalmente basta con instalar la última versión LTS. npm se instala junto con Node.js, por lo que no es necesario instalarlo por separado.

Qué métodos de instalación lo necesitan

• Microsoft Store / Desktop: sí, y node y npm deben encontrarse en el PATH del sistema.

Instalar Node.js

Windows

Método uno: instalador oficial (recomendado)

1. Visite el sitio web oficial de Node.js
2. Descargue el instalador de Windows (archivo .msi) de la versión LTS (soporte a largo plazo) y confirme que el número de versión no es inferior a 24
3. Haga doble clic para ejecutar el instalador
4. Siga las indicaciones del asistente de instalación para completar la instalación:
   • Acepte el acuerdo de licencia
   • Elija la ruta de instalación (la predeterminada es suficiente)
   • Mantenga marcada la opción “Add to PATH”
   • Haga clic en “Install” para iniciar la instalación
5. Cuando termine la instalación, haga clic en “Finish”

Método dos: usar winget

Abra PowerShell o el símbolo del sistema y ejecute el siguiente comando:

winget install OpenJS.NodeJS.LTS

Cuando termine la instalación, vuelva a abrir la terminal para que los cambios surtan efecto.

macOS

Método uno: instalador oficial (recomendado)

1. Visite el sitio web oficial de Node.js
2. Descargue el instalador de macOS (archivo .pkg) de la versión LTS (soporte a largo plazo) y confirme que el número de versión no es inferior a 24
3. Haga doble clic para ejecutar el instalador
4. Siga las indicaciones del asistente de instalación para completar la instalación:
   • Haga clic en “Continuar”
   • Acepte el acuerdo de licencia
   • Elija el disco de instalación
   • Haga clic en “Instalar” e introduzca la contraseña de administrador
5. Cuando termine la instalación, haga clic en “Cerrar”

Método dos: usar Homebrew

Si ya tiene instalado Homebrew, puede instalar Node.js desde la terminal:

brew install node

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

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

Ubuntu/Debian

Usar el repositorio NodeSource (recomendado)

El Node.js de los repositorios propios de la distribución suele ser anterior a la versión 24; use el repositorio 24.x que ofrece NodeSource:

# Descargar el script de instalación con curl
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

No instale directamente la versión de la distribución con sudo apt-get install nodejs npm: lo más probable es que no cumpla el requisito mínimo de la versión 24.

Si no quiere añadir un repositorio de software de terceros, también puede usar nvm o fnm, que se describen más abajo.

CentOS/RHEL

Usar el repositorio NodeSource (recomendado)

# Descargar el script de instalación con curl
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

El Node.js de los repositorios propios de la distribución suele ser anterior a la versión 24, por lo que no se recomienda usarlo directamente. También puede optar por nvm o fnm, que se describen más abajo.

Fedora

Usar el gestor de paquetes dnf

sudo dnf install -y nodejs npm

Después de instalar, ejecute node --version para confirmar que la versión no es inferior a 24. Si la versión del repositorio es anterior, use el repositorio 24.x de NodeSource o nvm o fnm, que se describen más abajo.

Usar un gestor de versiones

Si necesita cambiar entre varias versiones de Node.js, puede usar un gestor de versiones.

Aviso para usuarios de Desktop

En macOS y Linux, herramientas como nvm y fnm suelen definir el PATH solo en los archivos de configuración del shell (como .bashrc o .zshrc). Desktop, cuando se inicia desde el Dock, el menú de aplicaciones o un icono del escritorio, no lee esa configuración y es posible que no encuentre node. Si usa un gestor de versiones, inicie Desktop desde una terminal en la que node ya funcione, o use el método de instalación a nivel de sistema descrito más arriba.

nvm (Node Version Manager)

Instalar nvm

Linux/macOS

Copie directamente el comando de instalación más reciente que figura en el README del repositorio oficial de nvm; no use direcciones de scripts de instalación de versiones antiguas.

Cuando termine la instalación, vuelva a cargar la configuración de su shell:

source ~/.bashrc
# O, para usuarios de Zsh
source ~/.zshrc

Windows

En Windows se recomienda usar nvm-windows:

1. Descargue el último nvm-setup.exe desde las versiones de nvm-windows
2. Ejecute el instalador
3. Vuelva a abrir el símbolo del sistema o PowerShell

Usar nvm

Después de instalar nvm, puede usarlo para instalar y gestionar versiones de Node.js:

# Instalar Node.js 24
nvm install 24

# Cambiar a Node.js 24
nvm use 24

# Establecer la versión predeterminada
nvm alias default 24

# Listar las versiones instaladas
nvm list

El comando alias de nvm-windows no está disponible; basta con usar nvm install 24 y nvm use 24.

fnm (Fast Node Manager)

fnm es un gestor de versiones de Node.js más rápido y sencillo, creado con Rust.

Instalar fnm

Linux/macOS

# Instalar con curl
curl -fsSL https://fnm.vercel.app/install | bash

# Cuando termine la instalación, vuelva a cargar la configuración del shell
source ~/.bashrc
# O, para usuarios de Zsh
source ~/.zshrc

Windows

Use scoop o winget:

# Con scoop
scoop install fnm

# O con winget
winget install Schniz.fnm

Usar fnm

# Instalar Node.js 24
fnm install 24

# Cambiar a Node.js 24
fnm use 24

# Establecer la versión predeterminada
fnm default 24

# Listar las versiones instaladas
fnm list

Aceleración para usuarios de China continental

Si se encuentra en China continental, la descarga de Node.js y de los paquetes de npm puede ser lenta; en ese caso puede usar espejos nacionales.

Espejo de npm

# Usar el espejo solo para esta instalación
npm install --registry=https://registry.npmmirror.com

# Establecer el espejo de forma permanente
npm config set registry https://registry.npmmirror.com

# Comprobar que el espejo se ha configurado correctamente
npm config get registry

Espejo de los instaladores de Node.js

Los instaladores de Node.js también tienen una dirección de descarga en espejo: https://npmmirror.com/mirrors/node/. Después de acceder, elija una versión que no sea inferior a la 24 para descargarla.

Espejo de Homebrew

Si usa Homebrew en China continental, puede configurar el espejo de USTC para los bottles:

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

Verificar la instalación

Cuando termine la instalación, compruebe en una terminal recién abierta que Node.js y npm están disponibles:

# Comprobar la versión de Node.js; se requiere v24.0.0 o superior
node --version

# Comprobar la versión de npm
npm --version

La salida correcta debería ser similar a esta:

$ node --version
v24.3.0

$ npm --version
11.4.2

Si node --version muestra una versión inferior a la 24, vuelva a instalarlo con los métodos anteriores o cambie a la 24 o superior con un gestor de versiones.

Configurar el directorio global de npm

Desktop instala los paquetes gestionados, como los Agent CLI, en el directorio global de npm de su equipo. Si el directorio global está en una ubicación que requiere privilegios de administrador, durante la instalación puede aparecer un error de permisos EACCES. Se recomienda mover el directorio global al directorio del usuario en lugar de modificar los permisos de un directorio del sistema:

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

Después, añada ~/.npm-global/bin (en Windows, el propio directorio global de npm) al PATH del sistema y reinicie la terminal y Desktop. Con nvm o fnm, el directorio global ya está dentro del directorio del usuario y este paso no es necesario.

Solución de problemas

Problemas en Windows

Comando no disponible

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

1. Reinicie el símbolo del sistema o PowerShell
2. Si sigue sin estar disponible, añada Node.js al PATH manualmente:
   • Busque “Variables de entorno” y abra “Editar las variables de entorno del sistema”
   • Haga clic en “Variables de entorno”
   • En “Variables del sistema”, busque “Path” y haga clic en “Editar”
   • Añada la ruta de instalación de Node.js (por defecto: C:\Program Files\nodejs\)
   • Haga clic en “Aceptar” para guardar los cambios
3. Cierre Desktop por completo y vuelva a iniciarlo

Política de ejecución de PowerShell

Si aparecen errores de política de ejecución al usar nvm o scripts de npm:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas en macOS

Errores de permisos

Si aparecen errores de permisos al instalar paquetes globales de npm, consulte Configurar el directorio global de npm, más arriba, o cambie a nvm / fnm.

Comando no disponible

Si el comando no está disponible después de la instalación, reinicie la terminal y confirme que el directorio donde está Node.js (normalmente /usr/local/bin o /opt/homebrew/bin) está en el PATH.

Problemas en Linux

Errores de permisos

Si aparecen errores de permisos al instalar paquetes globales de npm, consulte Configurar el directorio global de npm, más arriba, o use nvm / fnm en lugar de instalar paquetes globales con sudo.

Versión demasiado antigua

Si la versión de Node.js instalada con el gestor de paquetes del sistema es anterior a la 24:

1. Use el repositorio 24.x de NodeSource (consulte más arriba)
2. O use un gestor de versiones (nvm / fnm)

Comprobar el entorno

Si la verificación falla, compruebe lo siguiente:

Windows

# Comprobar si Node.js está en el PATH
where node

# Comprobar la ruta de instalación
Get-Command node

macOS

# Comprobar si Node.js está en el PATH
which node

# Comprobar la ruta de instalación
ls -l $(which node)

Linux

# Comprobar si Node.js está en el PATH
which node

# Comprobar la ruta de instalación
ls -l $(which node)

Próximos pasos

Cuando termine la instalación de Node.js, puede continuar con los siguientes pasos:

Volver a la guía de instalaciónComplete requisitos previos como Git y elija el método de instalación que más le convenga.

Introducción a OpenSpecVaya al sitio de documentación independiente de OpenSpec para conocer su instalación, sus conceptos clave y el flujo de trabajo basado en especificaciones.

Instalar AI Agent CLIConsulte los puntos de entrada de instalación oficiales de los Agent CLI admitidos actualmente y distinga entre la instalación con un clic y la instalación / autenticación manual.

¿Necesita más ayuda?

Si encuentra problemas que no se tratan aquí:

1. Visite la documentación oficial de Node.js
2. Consulte Cómo usa Desktop su entorno de Node
3. Consulte la descripción general del producto HagiCode para conocer el producto actual y la cadena de herramientas relacionada