Todos los artículos

Infra8 min de lectura

No subestimes el lock file: npm ci, conflictos y seguridad

Qué hacen de verdad el package-lock.json, el yarn.lock y el pnpm-lock.yaml, por qué hacer commit, npm ci vs npm install, el hash de integridad y cómo resolver conflictos.

También en Português, English, Français

Si usas npm, Yarn o pnpm, ya viste un package-lock.json, un yarn.lock o un pnpm-lock.yaml en el proyecto. Mucha gente lo ignora, lo borra cuando hay conflicto o ni siquiera le hace commit.

Eso es un error serio, y en este post te muestro por qué con ejemplos que ejecuté de verdad, no solo con teoría.

Publiqué la primera versión de este post en Medium en septiembre de 2025, en portugués. Esta es la versión revisada, con pruebas, el npm ci (que quedó fuera del original), la forma correcta de resolver conflictos y una corrección sobre lo que el hash de integridad protege y lo que no.

El clásico “en mi máquina funciona”: mismo package.json, versiones distintas

TL;DR#

  • El package.json acepta rangos de versión (^2.0.0 quiere decir "cualquier 2.x"). El lock file guarda la versión exacta que se instaló, de cada dependencia y de las dependencias de ellas.
  • Sin el lock, el mismo package.json instala versiones distintas en días distintos. En mi prueba, salió 2.1.1 con el lock y 2.1.3 sin él.
  • Haz commit del lock file y nunca lo borres para "resolver" un problema.
  • En el CI, usa npm ci (o pnpm install --frozen-lockfile, o yarn install --immutable). Instala exactamente lo que está en el lock y falla si el lock está desactualizado.
  • El hash de integridad garantiza que el paquete es el mismo que se fijó, byte a byte. No dice si el paquete es seguro, pero impide que una versión nueva, quizá maliciosa, entre sin que nadie lo vea.
  • Conflicto en el lock: resuelve el package.json y vuelve a ejecutar npm install. npm rehace el lock solo.
  • Un proyecto, un gestor. Mezclar npm y Yarn genera dos locks que no están de acuerdo.

Qué hace el lock file#

En el package.json, rara vez escribes una versión exacta. Por defecto, npm install guarda un rango:

{
  "dependencies": {
    "ms": "^2.0.0"
  }
}

El ^2.0.0 quiere decir "cualquier versión 2.x a partir de la 2.0.0". Hoy eso puede ser la 2.1.1. Mañana, si sale una 2.1.4, es esa. Y eso vale también para cada dependencia de tus dependencias.

El lock file resuelve esto: guarda la versión exacta que se instaló, de dónde vino y un hash del archivo. Este es el fragmento de ms en el package-lock.json de mi prueba:

"node_modules/ms": {
  "version": "2.1.1",
  "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
  "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg..."
}

La prueba: el mismo package.json, dos versiones#

Armé un proyecto con ms fijado en la 2.1.1 y el package.json aceptando ^2.0.0. Después instalé dos veces: una con el lock, otra copiando solo el package.json a una carpeta nueva.

$ npm ci && node -p "require('ms/package.json').version"
2.1.1
 
# same package.json, no lock file
$ npm install && node -p "require('ms/package.json').version"
2.1.3
El rango del package.json acepta varias versiones. El lock elige una y ya no cambia

Es exactamente el "en mi máquina funciona": quien instaló hace seis meses tiene una versión, quien clonó hoy tiene otra, y el bug solo aparece para una de las dos personas. Con el lock en el repositorio, las dos instalan lo mismo.

¿npm install o npm ci?#

Los dos instalan dependencias, pero con objetivos distintos:

  • npm install respeta el lock mientras coincida con el package.json, pero puede actualizar el lock: si agregaste un paquete o cambiaste un rango, vuelve a resolver y reescribe el archivo. Es el comando del día a día, cuando quieres cambiar dependencias.
  • npm ci borra la node_modules e instala exactamente lo que está en el lock. Nunca modifica el lock. Si el package.json y el lock no coinciden, se detiene con un error:
npm error code EUSAGE
npm error `npm ci` can only install packages when your package.json and package-lock.json
or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install`
before continuing.

Ese error es una ayuda: alguien cambió el package.json y olvidó hacer commit del lock. Mejor que el CI se rompa a que llegue a producción con versiones que nadie probó.

Regla práctica: npm install en tu máquina cuando quieres cambiar dependencias; npm ci en el CI, en Docker y siempre que solo quieras instalar lo que el proyecto ya define.

Los otros gestores tienen el equivalente:

GestorLock fileInstalar sin tocar el lock
npmpackage-lock.jsonnpm ci
pnpmpnpm-lock.yamlpnpm install --frozen-lockfile
Yarn (2 o más reciente)yarn.lockyarn install --immutable
Yarn 1yarn.lockyarn install --frozen-lockfile

En pnpm y en el Yarn moderno, ese modo ya es el predeterminado cuando detectan que están corriendo en un CI.

El hash de integridad#

Cada paquete en el lock tiene un campo integrity, un hash SHA-512 del archivo descargado. Al instalar, npm calcula el hash de lo que llegó y lo compara. Para verlo funcionando, cambié el hash de ms en el lock por uno falso:

$ npm ci
npm error code EINTEGRITY
npm error sha512-AAAA...== integrity checksum failed when using sha512:
wanted sha512-AAAA...== but got sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg...

npm se negó a instalar. El original de este post decía que ese hash "impide que se instalen bibliotecas maliciosas", y eso necesita un ajuste. El hash garantiza que el paquete es exactamente el mismo que se fijó. Si la versión fijada ya fuera maliciosa, el hash coincidiría igual.

La protección de verdad está en otro lugar: con el lock y el npm ci, una versión nueva no entra sin que alguien la pida. El 8 de septiembre de 2025, una semana después del original de este post, invadieron la cuenta de un mantenedor y versiones maliciosas de paquetes muy usados, como chalk@5.6.1 y debug@4.4.2, estuvieron en npm durante unas dos horas. Un proyecto con rango ^ y sin lock, instalando en esa ventana, podía traer la versión infectada. Un proyecto con el lock fijado en una versión anterior e instalando con npm ci seguía con la versión de antes.

El lock no sabe si un paquete es seguro. Solo no deja entrar una versión nueva sin que nadie la pida

Buenas prácticas#

1. Haz commit del lock file#

Es parte del proyecto, como el package.json. Sin él en Git, cada persona y cada build vuelve a resolver los rangos y puede llegar a versiones distintas. La única excepción común es quien publica una biblioteca en npm: su lock no viaja al proyecto de quien la instala. Aun así, vale la pena hacer commit, para que tu propio CI sea reproducible.

2. No borres el lock para resolver un problema#

Borrar el lock y ejecutar npm install no "limpia" nada: actualiza todas las dependencias de una vez, incluso las que no tenían nada que ver con el problema. Si algo se rompió, cambiaste un bug por veinte cambios que nadie revisó. Primero entiende el error. Si necesitas actualizar un paquete, actualiza ese paquete.

3. Conflicto en el lock: deja que el gestor lo resuelva#

Dos ramas agregaron dependencias distintas, y el merge dio conflicto en el package.json y en el lock. Resolver el lock a mano, línea por línea, es buscarse errores. La forma correcta:

  1. resuelve a mano el conflicto del package.json (es corto y legible);
  2. ejecuta npm install.

npm entiende los marcadores de conflicto en el package-lock.json y rehace el archivo juntando los dos lados (probado en npm 11). En mi prueba, una rama agregó left-pad y la otra is-number. Después de juntar las dos en el package.json y ejecutar npm install, el lock quedó sin ningún marcador de conflicto y con los dos paquetes:

$ git merge feat-a
CONFLICT (content): Merge conflict in package-lock.json
CONFLICT (content): Merge conflict in package.json
 
# fix package.json by hand, then:
$ npm install
added 1 package, and audited 4 packages in 395ms

Después, revisa el diff del lock antes de hacer commit. Debería mostrar solo los paquetes de las dos ramas.

4. Un proyecto, un gestor#

Si el proyecto tiene package-lock.json, usa npm. Si tiene pnpm-lock.yaml, usa pnpm. Ejecutar yarn en un proyecto npm crea un yarn.lock que no sabe nada del package-lock.json, y los dos empiezan a discrepar sobre las versiones.

Para dejarlo explícito, declara el gestor en el package.json. pnpm y Yarn leen ese campo:

{
  "packageManager": "pnpm@10.0.0"
}

5. Actualiza a propósito#

¿Quieres actualizar? Usa el comando del gestor, y de preferencia un paquete a la vez:

npm outdated            # what is behind
npm update ms           # update within the package.json range
npm install ms@latest   # jump to the latest version (may change the range)

El lock cambia junto, y el diff muestra exactamente lo que cambió. Herramientas como Dependabot y Renovate lo hacen por ti, abriendo un PR por actualización.

Resumen#

  • El package.json dice qué versiones sirven; el lock dice qué versión se instaló.
  • Haz commit del lock y no lo borres para "resolver" un problema.
  • npm ci en el CI y en Docker, npm install cuando quieres cambiar dependencias.
  • El hash garantiza que el paquete no cambió; el lock garantiza que una versión nueva no entra sin PR.
  • Conflicto en el lock: resuelve el package.json y ejecuta npm install.
  • Un gestor por proyecto.

El lock file no es una molestia: es lo que garantiza que el código probado es el código que va a producción.

Referencias#

  • Infra
  • npm
  • pnpm
  • yarn
  • lock file
  • ci
  • seguridad

Escrito por

Ingeniera de software y diseñadora. Escribo sobre lo que encuentro construyendo apps, APIs y productos.