Versionado semántico ¿Qué significan los números en tu package.json?

Cada proyecto en JavaScript tiene un package.jsonque muchos desarrolladores han escrito cientos de veces sin darle una segunda mirada al string de versión. Pero si preguntas a alguien qué npm install some-library realmente permite — es decir, qué versiones que npm hará felizmente incluir — a menudo obtendrás una respuesta de los hombros. ^1.2.3 Este no es un vacío trivial. Una comprensión errónea del rango de versiones es cómo un script rutinario en una máquina nueva rompe de repente una pipeline de CI que funcionaba bien durante meses. Comprender el contrato detrás de esos números es una de esas cosas de bajo esfuerzo y alto retorno que separa a los desarrolladores que resuelven problemas de versión en minutos de aquellos que los pasan en horas.

El contrato MAJOR.MINOR.PATCH npm install La versión semántica (semver) es un formato de tres números:

. Cada posición lleva una promesa específica sobre lo que cambió:

— cambios que rompen. Actualizar a una versión mayor puede requerir que actualices tu código. MAJOR.MINOR.PATCH— nuevas características, compatibles hacia atrás. Tu código existente debería seguir funcionando.

• MAJOR — correcciones de errores solo. Seguro para actualizar; sin cambios en la API.
• MINOR Eso es el
• PATCH contrato

que publican los paquetes. Saltar de debería añadir nuevas características sin romper el comportamiento existente. Saltar a es tu advertencia: lee el historial de cambios antes de actualizar. 2.3.1 a 2.4.0 En la práctica, los mantenedores a veces se equivocan y introducen un cambio que rompe en una actualización menor. El semver no se enforces por sí mismo — es una convención. Pero te da un marco para razonar sobre el riesgo, y es sobre lo que se construyen todos los operadores de rango. 3.0.0 ¿Qué se considera un cambio que rompe?

Un cambio que rompe es cualquier cosa que obligue a los consumidores a actualizar su código:

Eliminar o renombrar una función, clase o constante exportada

Cambiar la firma de una función — eliminar parámetros, añadir parámetros obligatorios o cambiar los tipos de retorno

• Cambiar el comportamiento observable de forma que el código que llama ahora se comporte mal
• Cambiar el formato de un archivo de configuración de forma incompatible
• Añadir un nuevo parámetro opcional? Eso es MINOR. Añadir una nueva exportación? MINOR. Corregir un bug que alguien estaba utilizando accidentalmente como una característica? Eso es una decisión, pero convencionalmente PATCH. Cuando no estés seguro, aumenta MINOR y documenta claramente.
• Los operadores de rango en package.json

Abre cualquier

y verás cadenas de versión como

. Estas no son puntos exactos — son package.json rangos "^4.17.21" o "~1.0.4"que indican a npm o yarn cuáles versiones son aceptables al resolver tu árbol de dependencias. Caret ^ — Compatible con versión El caret es el operador predeterminado cuando ejecutas

. Significa: "acepta cualquier versión que no cambie el dígito no cero más a la izquierda". En la práctica, para paquetes estables, eso significa misma versión mayor, cualquier versión menor o parche:

El comportamiento de cero mayor es intencional. Los paquetes en npm installindican una "API inestable" — cualquier versión menor podría romper cosas. El caret respeto esa señal y se vuelve mucho más conservador.

^1.2.3  →  >=1.2.3 <2.0.0   (any 1.x.x at or above 1.2.3)
^0.2.3  →  >=0.2.3 <0.3.0   (zero-major: pins to minor)
^0.0.3  →  >=0.0.3 <0.0.4   (zero-zero: pins to exact patch)

Tilde ~ — Actualizaciones solo a nivel de parche 0.x.x La tilde es más conservadora. Acepta nuevos parches pero no toca la versión menor:

Busca

cuando quieras correcciones de errores pero no estés seguro de que la biblioteca respete el semver para aumentos menores, o cuando tu código esté estrechamente acoplado a una superficie específica de API y una nueva versión con características históricamente traiga cambios sutiles de comportamiento.

~1.2.3  →  >=1.2.3 <1.3.0   (any 1.2.x at or above 1.2.3)
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0   (when only major given — same as ^1)

Operadores de comparación: >=, ~ Puedes escribir rangos arbitrarios usando operadores de comparación. Un espacio entre dos restricciones significa AND:

Estos aparecen con más frecuencia en <=, >

, donde una biblioteca dice algo como

>=1.2.0           # at least 1.2.0, no upper bound
>=1.2.0 <2.0.0   # same as ^1.2.0 (explicit AND)
>1.2.0 <=1.5.0   # between these values, exclusive/inclusive

para declarar qué versiones de host son compatibles. peerDependenciesWildcards: * y x "react": ">=16.8.0 <19.0.0" Las formas de wildcard son principalmente para legibilidad en documentación; npm las trata como equivalentes al caret/tilde con una base cero:

— cualquier versión. No uses esto en producción.

— cualquier 1.x.x (igual que

• * o "" — cualquier 1.2.x (igual que
• 1.x o 1.x.x Versiones de lanzamiento previo ^1.0.0)
• 1.2.x Las versiones de lanzamiento previo se ven como ~1.2.0)

. Se consideran

menores 1.0.0-alpha.1, 2.0.0-beta.3, o 3.1.0-rc.1que la versión de lanzamiento con los mismos números — Críticamente, los operadores de rango no incluyen automáticamente versiones de lanzamiento previo 1.0.0-alpha.1 < 1.0.0.

. Un rango no incluirá aunque técnicamente cumpla con. Tienes que optar explícitamente: ^1.0.0 Esto es una seguridad intencional. Rara vez querrías que CI seleccionara silenciosamente una 1.1.0-beta.1versión de un paquete de dependencia porque técnicamente cumpla con un rango de versiones. Si estás probando versiones de lanzamiento previo, hazlo deliberadamente. >=1.0.0 <2.0.0Los archivos de bloqueo no son opcionales

npm install some-library@next
npm install some-library@2.0.0-beta.3

Cuando npm resuelve tu -alpha rango, selecciona la versión más alta compatible disponible

en ese momento

hoy y obtienes ^1.2.3 . Ejecútalo seis meses después y podrías obtener . Mismo. Ejecuta npm install , árbol de dependencias diferente, comportamiento potencialmente diferente. 1.5.0Eso es lo que resuelven los archivos de bloqueo. 1.9.2(npm) y package.json(yarn) registran la versión exacta instalada para cada dependencia — directa y transitiva. Cuando alguien más clona tu repositorio y ejecuta

, obtiene un árbol idéntico. package-lock.json Incluye tu archivo de bloqueo. Siempre. yarn.lock No incluirlo significa: npm ciDiferentes desarrolladores podrían ejecutar versiones diferentes de dependencias sin darse cuenta

El entorno de CI puede desviarse silenciosamente del entorno local Una actualización de una dependencia transitiva puede cambiar el comportamiento en producción sin cambios visibles en tu

• La excepción principal: las bibliotecas publicadas (no aplicaciones) convencionalmente dejan los archivos de bloqueo sin incluirlos para que los consumidores puedan resolver su propio árbol de dependencias. Si estás desarrollando una aplicación, no hay una buena razón para dejar el archivo de bloqueo fuera del control de fuentes.
• "latest" en package.json siempre es un error
• A veces verás esto en un git diff

No hagas esto.

se refiere a la versión actualmente etiquetada

en npm — cambia cada vez que el mantenedor publique una nueva versión. Una nueva package.json:

"dependencies": {
  "some-package": "latest"
}

en cualquier máquina nueva podría traer una versión mayor completamente diferente a la que probaste. "latest" Podría funcionar bien durante semanas, luego romperse silenciosamente cuando el paquete publique una nueva versión mayor. Peor aún, hace que latest sea inútil como especificación reproducible — no puedes razonar sobre qué versión estás ejecutando sin verificar manualmente npm. Fija una versión real y deja que el caret maneje actualizaciones seguras dentro de ese rango. npm install Verificar si una versión satisface un rango

Si no estás seguro de si una versión cumple con un rango dado — especialmente con paquetes de cero mayor o expresiones compuestas inusuales — el package.json en iotools.cloud te da una respuesta inmediata. Ingresa el rango (

) y la versión candidata, y te dice si la restricción se cumple.

Esto es útil al revisar solicitudes de PR para actualización de dependencias, depurando por qué Calculadora de versiones Semver y verificador de rangos se resolvió a una versión inesperada, o verificar un^1.2.3, ~0.5.0, >=2.0.0 <3.0.0rango antes de publicar una biblioteca.

Operador npm install Se resuelve a peerDependencies 1.2.0 o superior, sin cota

Guía rápida

Cualquier versión (evita)	Ejemplo	Cualquier 1.2.x parche
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	exacto
*	*	Exactamente 1.2.3
x	1.2.x	Versionado semántico: ¿Qué significan los números en tu package.json?
Versionado semántico: ¿Qué significan los números en tu package.json? 2	1.2.3	Versionado semántico: ¿Qué significan los números en tu package.json? 1

También te puede interesar