Gestión de Versiones de Node.js

fnm proporciona potentes características de gestión de versiones, permitiéndote cambiar fácilmente entre múltiples versiones de Node.js.

Operaciones Básicas

Ver Versiones Instaladas

fnm list

Ejemplo de salida:

* v20.10.0 default
  v18.19.0
  v16.20.2

• * indica la versión actualmente usada
• default indica la versión predeterminada

Ver Versión Actual

fnm current

Cambiar Versión

# Cambiar a versión específica
fnm use 20

# Cambiar a versión exacta específica
fnm use 20.10.0

# Si la versión no está instalada, auto instalar luego cambiar
fnm use 18 --install-if-missing

Versión Predeterminada

Establecer Versión Predeterminada

fnm default 20

La versión predeterminada es:

• La versión usada cuando se inicia una nueva sesión de terminal
• La versión usada cuando no hay archivo de versión

Ver Versión Predeterminada

fnm default

Alias de Versiones

Los alias te permiten establecer nombres fáciles de recordar para las versiones.

Crear Alias

# Establecer alias para versión
fnm alias 20 default
fnm alias 18 legacy
fnm alias 16 old

Usar Alias

# Cambiar versión mediante alias
fnm use default
fnm use legacy

Eliminar Alias

fnm unalias legacy

Cambio Automático de Versión

fnm puede cambiar automáticamente las versiones de Node.js según el directorio del proyecto.

Habilitar Cambio Automático

Añade --use-on-cd a la configuración del Shell:

eval "$(fnm env --use-on-cd)"

Crear Archivo de Versión

Crear un archivo .node-version o .nvmrc en el directorio raíz del proyecto:

# Usando .node-version (recomendado)
echo "20" > .node-version

# O usando .nvmrc (compatible con nvm)
echo "v18.17.0" > .nvmrc

Formato de Archivo de Versión

.node-version soporta los siguientes formatos:

20           # Versión mayor, usar última 20.x.x
20.10        # Versión menor, usar última 20.10.x
20.10.0      # Versión exacta
lts/iron     # Nombre de versión LTS

Estrategia de Análisis de Archivos de Versión

fnm soporta dos estrategias de análisis de archivos de versión:

# local (predeterminado) - Solo buscar en el directorio actual
fnm env --version-file-strategy=local

# recursive - Buscar recursivamente en directorios padre
fnm env --version-file-strategy=recursive

Soporte de package.json engines

fnm puede leer el campo engines.node de package.json:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Habilitado por defecto, puede deshabilitarse mediante variable de entorno:

export FNM_RESOLVE_ENGINES=false

Mejores Prácticas de Gestión de Versiones

1. Bloqueo de Versión a Nivel de Proyecto

Crear un archivo .node-version en cada proyecto:

cd my-project
echo "20" > .node-version
fnm install
fnm use

2. Colaboración en Equipo

Añadir .node-version a Git:

git add .node-version
git commit -m "chore: add .node-version"

3. Configuración de CI/CD

Usar fnm en entornos de CI/CD:

# GitHub Actions
- name: Instalar fnm
  run: curl -fsSL https://fnm.vercel.app/install | bash

- name: Instalar Node.js
  run: fnm install && fnm use

4. Desarrollo con Múltiples Versiones

# Instalar múltiples versiones
fnm install 20
fnm install 18
fnm install 16

# Establecer alias para cambio fácil
fnm alias 20 current
fnm alias 18 legacy
fnm alias 16 old

# Usar diferentes versiones en diferentes proyectos
cd project-new && fnm use current
cd project-old && fnm use legacy

Desinstalar Versiones

# Desinstalar versión específica
fnm uninstall 16.20.2

# Desinstalar mediante alias (eliminará versión y todos los alias relacionados)
fnm uninstall old

Problemas Comunes

El Comando node No Se Actualiza Después del Cambio de Versión

Asegúrate de que la configuración del Shell sea correcta:

# Verificar ruta de node
which node

# Debe apuntar al directorio de fnm
# ~/.fnm/node-versions/.../bin/node

El Cambio Automático No Funciona

1. Confirmar que --use-on-cd está añadido a la configuración del Shell
2. Confirmar que el archivo de versión existe
3. Recargar la configuración del Shell

Prioridad de Archivos de Versión

fnm busca versiones en el siguiente orden:

1. Versión especificada en línea de comandos
2. Archivo .node-version
3. Archivo .nvmrc
4. Campo engines.node de package.json
5. Versión predeterminada

Enlaces Relacionados

• Instalar Node.js - Guía de instalación
• Referencia de Comandos - Todos los detalles de comandos
• Gestión de Descargas - Características relacionadas con descargas