Instalación y gestión de versiones
Las versiones consistentes de Node en laptops, CI y producción evitan fallos de "funciona en mi máquina"; fija la versión LTS activa y aplícala en el momento de la instalación.
//
Busca en todas las páginas de la documentación
Las versiones consistentes de Node en laptops, CI y producción evitan fallos de "funciona en mi máquina"; fija la versión LTS activa y aplícala en el momento de la instalación.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
// package.json
{
"engines": {
"node": ">=24.18.0 <25",
"npm": ">=10.0.0"
},
"engineStrict": true
}# .nvmrc
24.18.0Cuándo usarlo:
# Instala fnm (macOS/Linux) - gestor de versiones rápido y multiplataforma
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24.18.0
fnm use 24.18.0
node --version # v24.18.0// extracto de package.json
{
"name": "billing-api",
"type": "module",
"engines": { "node": ">=24.18.0 <25" },
"scripts": {
"preinstall": "node scripts/check-node-version.mjs"
}
}// scripts/check-node-version.mjs
const required = 24;
const major = Number(process.versions.node.split('.')[0]);
if (major !== required) {
console.error(`Node ${required}.x requerido, se obtuvo ${process.version}`);
process.exit(1);
}Lo que esto demuestra:
.nvmrc / .node-version se integran con fnm, nvm y asdfengines documenta el rango soportado para humanos y herramientaspreinstall falla rápidamente antes de que npm install descargue paquetes<25 excluye las versiones "Current" (impares) que no son adecuadas para producciónengines es solo una recomendación a menos que engine-strict=true en .npmrc o que añadas scripts de cumplimiento.node:24.18.0-bookworm-slim, no node:latest.volta de package.json y cambia automáticamente al hacer cd.| Herramienta | Velocidad | Modelo de fijación | Mejor para |
|---|---|---|---|
| fnm | Rápido (Rust) | .nvmrc, hook de shell | Desarrollo diario en macOS/Linux |
| nvm | Moderado | .nvmrc, ampliamente conocido | Documentación y tutoriales heredados |
| Volta | Rápido | Bloque volta en package.json | Equipos que quieren cero use manual |
| asdf | Basado en plugins | .tool-versions | Repositorios políglotas (Node + Ruby + Go) |
// Lee la versión del runtime al inicio y la expone en /health
export function runtimeInfo(): { node: string; platform: string } {
return {
node: process.version,
platform: `${process.platform}-${process.arch}`,
};
}node:latest en Docker: cada compilación puede obtener una versión principal diferente. Solución: fija node:24.18.0-bookworm-slim con un digest.engines sin cumplimiento: npm advierte pero instala de todos modos por defecto. Solución: engine-strict=true en .npmrc o una puerta de CI.npx, pnpm dlx o devDependencies locales al proyecto.| Alternativa | Cuándo usar | Cuándo no usar |
|---|---|---|
| Volta | Cambio automático por proyecto | Necesitas soporte para Windows con mínima fricción de configuración |
| asdf | Una herramienta para muchos lenguajes | Equipos solo de Node que quieren la ruta más simple |
| Solo contenedor (sin gestor local) | Devcontainers / flujos de trabajo solo con Docker | Iteración local rápida sin la sobrecarga del contenedor |
Gestor de paquetes del sistema (apt, brew) | Instalaciones rápidas de una sola vez | Paridad de producción o cambio de múltiples versiones |
Node.js 24.18.0 (Active LTS) para nuevas implementaciones. Node 22.23.1 (Maintenance LTS) es aceptable durante la migración, pero planifica la actualización antes de que finalice el mantenimiento.
Ambos cambian las versiones de Node a través de hooks de shell. fnm es más rápido (escrito en Rust) y soporta el mismo formato de archivo .nvmrc.
Sí. Haz commit de .nvmrc o .node-version para que cada desarrollador y trabajo de CI resuelva la misma versión.
Añade una sección volta a package.json:
"volta": { "node": "24.18.0", "npm": "10.9.0" }Volta cambia automáticamente cuando entras en el directorio del proyecto.
Cuando engine-strict=true en .npmrc, npm se niega a instalar si el Node/npm en ejecución no satisface engines.
Sí. corepack enable activa la versión del gestor de paquetes declarada en el campo packageManager:
"packageManager": "pnpm@9.15.0"Haz que CI coincida con .nvmrc:
- uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'fnm, nvm-windows y Volta soportan Windows. Documenta una herramienta canónica en el README del equipo.
No para producción. Las versiones impares son "Current" y de corta duración. Usa Active LTS (números pares) para los servicios.
npm list -g --depth=0Prefiere las devDependencies locales al proyecto sobre las globales para la reproducibilidad.
Alpine usa musl libc; algunos complementos nativos necesitan pasos de compilación adicionales. bookworm-slim (Debian) es más seguro para módulos nativos.
Actualiza primero las máquinas de desarrollo y CI, ejecuta la suite de pruebas, verifica las advertencias de API obsoletas con NODE_OPTIONS=--pending-deprecation, luego despliega en producción.
Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.
Revisado por Chris St. John·Última actualización: 19 jul 2026