Para saber qué versión de Node.js espera un proyecto en tu Mac, inspecciona sus archivos de versión y configuración antes de comprobar la versión activa en Terminal. Empieza por .nvmrc y, a continuación, comprueba los ajustes de volta y engines en package.json. Estas pistas tienen significados diferentes: algunas fijan una versión para una herramienta, mientras que otras describen un rango de compatibilidad.

1. Abre la carpeta del proyecto en Terminal

En el Finder, localiza la carpeta del proyecto. Haz Control-clic sobre ella y selecciona Nuevo terminal en la carpeta si esa opción está disponible; de lo contrario, abre Terminal y navega hasta la carpeta con cd. Puedes arrastrar la carpeta desde el Finder a la ventana de Terminal después de escribir cd , y luego pulsar Intro. Esto evita escribir incorrectamente una ruta que contenga espacios.

Ejecuta estos comandos de solo lectura desde el directorio del proyecto:

ls -a
grep -nE '"(engines|volta)"|"node"' package.json .nvmrc

ls -a incluye archivos ocultos como .nvmrc. grep muestra las líneas coincidentes de los archivos existentes; si falta algún archivo, puede mostrar un error para ese archivo, lo cual no significa que el proyecto esté dañado. Para inspeccionar un archivo concreto con más detalle, utiliza sed -n '1,160p' package.json o sed -n '1,20p' .nvmrc cuando el archivo exista. Estos comandos muestran texto; no modifican el proyecto.

2. Lee .nvmrc como una instrucción para el gestor de versiones

Si encuentras .nvmrc, lee su contenido. Un valor como 20.16.0 indica que el proyecto especifica esa versión de Node.js para los usuarios de nvm. nvm también acepta selectores de versión como 20 o lts/*, por lo que es posible que el archivo no identifique una versión de parche fija. La documentación de nvm indica que sus comandos pueden encontrar .nvmrc en el directorio del proyecto o en un directorio superior, y nvm use sin ninguna versión utiliza el archivo cuando está disponible. README de nvm: .nvmrc

En macOS, comprueba si nvm está disponible y qué versión resuelve en este directorio:

command -v nvm
nvm use
node --version

command -v nvm debería imprimir nvm cuando nvm está cargado en la shell actual. Si el comando no está disponible, no asumas que .nvmrc no es válido; el archivo aún puede documentar la elección del proyecto incluso si no tienes nvm instalado o cargado. nvm use selecciona la versión del archivo si está instalada; si falta, nvm puede pedirte que la instales. Ejecuta una instalación únicamente si tienes la intención de añadir esa versión de Node a tu Mac.

3. Comprueba package.json para Volta y los rangos de compatibilidad

Busca un objeto volta de nivel superior. Por ejemplo:

"volta": {
  "node": "20.16.0"
}

Esta es una versión fijada de Node para proyectos gestionados con Volta. La documentación de Volta indica que volta pin almacena las versiones de herramientas seleccionadas en package.json, y que Volta dirige los comandos de Node a la versión del proyecto. Comprendiendo Volta Si utilizas Volta, node --version desde el directorio del proyecto puede mostrar qué versión ejecuta la cadena de herramientas; sin Volta, el objeto sigue siendo metadatos del proyecto, no un comando para Terminal de macOS.

Inspecciona también la propiedad engines, comúnmente escrita así:

"engines": {
  "node": ">=18 <23"
}

Esto indica un rango de compatibilidad, no necesariamente la versión que tienen instalada los desarrolladores. La documentación de npm describe que engines.node especifica con qué versiones de Node funciona un paquete; a menos que engine-strict esté habilitado, npm lo trata como una recomendación y puede que solo muestre una advertencia durante la instalación de dependencias. Documentación de package.json de npm Un rango amplio significa que el proyecto afirma ser compatible con todas las versiones permitidas; no establece una versión exacta esperada.

4. Compara los archivos y resuelve pistas contradictorias

Considera una versión exacta en .nvmrc o fijada en Volta como la señal más firme de una versión concreta gestionada por herramientas. Trata engines.node como una restricción de compatibilidad. Si los archivos no coinciden —por ejemplo, .nvmrc indica 18 pero engines.node requiere >=20—, no elijas uno en silencio. Los archivos pueden estar desactualizados, servir para diferentes herramientas o reflejar un cambio reciente. Revisa el README del proyecto y las instrucciones de configuración, y luego pregunta a los mantenedores o al equipo qué archivo esperan que sigan los colaboradores.

Los proyectos también pueden definir versiones en archivos utilizados por otros gestores de versiones o en la configuración de CI. Si .nvmrc y package.json no ofrecen una respuesta útil, busca archivos visibles del proyecto con ls -a e inspecciona la documentación de configuración y los flujos de trabajo de CI. Un archivo de CI puede mostrar la versión utilizada para las compilaciones automatizadas, pero puede diferir de la configuración local del desarrollador; confirma el contexto antes de considerarlo como el requisito del proyecto.

5. Verifica la versión de Node que tu Mac está usando realmente

Tras identificar las instrucciones del proyecto, compáralas con el entorno de ejecución activo:

node --version
command -v node

El primer comando informa de la versión activa de Node; el segundo muestra la ruta del ejecutable seleccionada a través del PATH de tu shell. Estos describen tu entorno actual de Terminal, no el requisito del proyecto por sí solos. Con nvm, ejecuta nvm use desde el directorio del proyecto antes de comprobar. Con Volta, ejecuta las comprobaciones desde ese directorio para que se apliquen los ajustes del proyecto. Si la versión indicada sigue difiriendo de la fijada, es posible que el gestor pertinente no esté instalado, cargado o controlando el ejecutable node en esta shell.

La respuesta práctica se obtiene al consultar ambas partes: la declaración de versión del repositorio te dice lo que solicita, mientras que node --version te dice lo que tu Mac está ejecutando actualmente. Si no coinciden, resuelve el gestor o la instrucción del proyecto antes de confiar en los resultados locales.

Fuentes