¿Qué es un lockfile?

Qué registra un lockfile

Su manifiesto, como package.json o pyproject.toml, enumera los paquetes de los que depende y los rangos de versiones que acepta. El gestor de paquetes convierte esos rangos en versiones exactas para todo el árbol, incluidas las dependencias transitivas, y escribe el resultado en el lockfile. La documentación de npm dice que package-lock.json describe «el árbol exacto que se generó, de modo que las instalaciones posteriores puedan generar árboles idénticos».

Una sola entrada de package-lock.json tiene este aspecto:

"node_modules/raw-body": {
  "version": "3.0.0",
  "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.0.tgz",
  "integrity": "sha512-...",
  "dependencies": {
    "bytes": "3.1.2",
    "http-errors": "2.0.0",
    "iconv-lite": "0.6.3",
    "unpipe": "1.0.0"
  }
}

• version es la versión exacta elegida.
• resolved es el lugar del que se descargó: una URL de tarball de un registro o una URL de git con un commit.
• integrity es un hash Subresource Integrity del tarball, de modo que una descarga manipulada falla.
• dependencies son sus propias dependencias, que es como se enlaza el árbol, o grafo de dependencias.

Lockfiles por gestor de paquetes

Gestor de paquetes	Lockfile	Instalar sin modificarlo
npm	package-lock.json	npm ci
Yarn (Berry)	yarn.lock	yarn install --immutable
pnpm	pnpm-lock.yaml	pnpm install --frozen-lockfile
uv	uv.lock	uv sync --locked
Poetry	poetry.lock	poetry install
Cargo	Cargo.lock	cargo build --locked
Bundler	Gemfile.lock	bundle config set frozen true
Módulos de Go	Versiones en go.mod y sumas de comprobación en go.sum	Por defecto, los comandos de build no actualizan go.mod

Con pip a secas, el sustituto habitual es un requirements.txt con versiones exactas. Fija lo que enumera, pero todo lo que deja fuera se vuelve a resolver en cada instalación.

Use instalaciones congeladas en CI

Un lockfile solo ayuda si el build instala a partir de él. Un simple npm install puede actualizar package-lock.json cuando ya no coincide con package.json, de modo que el build resuelve en silencio un árbol nuevo. npm ci está pensado para entornos automatizados:

• Requiere un package-lock.json o un npm-shrinkwrap.json.
• Si el lockfile y package.json no coinciden, termina con un error en lugar de actualizar el lockfile.
• Primero elimina cualquier node_modules existente.
• Nunca escribe en package.json ni en el lockfile.

Los demás comandos de la tabla anterior hacen lo mismo en sus gestores de paquetes.

Aplicaciones y bibliotecas

Confirme el lockfile en el repositorio para las aplicaciones y para todo lo que despliegue. En las bibliotecas, solo bloquea su propio desarrollo y su CI: npm nunca publica package-lock.json y lo ignora en cualquier lugar que no sea el proyecto raíz. Las aplicaciones que instalan su biblioteca resuelven sus dependencias por su cuenta, dentro de los rangos de versiones de usted. La única excepción en npm es npm-shrinkwrap.json, que sí se publica y tiene prioridad, y que la mayoría de las bibliotecas no deberían usar.

Por qué un lockfile no es un registro de lo distribuido

Un lockfile es el plan de un gestor de paquetes en un proyecto. El build que generó su versión hizo algo más que seguir ese plan:

• Puede que no lo haya usado. Una instalación no congelada, un lockfile ausente o un segundo lockfile en un monorepo significan que el árbol se resolvió de forma distinta al archivo que usted está mirando.
• Cachés. Los paquetes restaurados desde una caché de CI se instalan sin descargarse, y una caché restaurada mediante una clave parcial puede ser anterior al lockfile actual. Consulte lo que oculta la caché de GitHub Actions.
• Herramientas de build. Las acciones de configuración, los compiladores, los linters y los generadores de código llegan por otros canales, con sus propios árboles de dependencias.
• Descargas y scripts de instalación. Un curl en un paso del build o el script de instalación de un paquete descargan código que ningún lockfile enumera.
• Imágenes base. Un build de contenedor descarga imágenes y paquetes del sistema operativo que quedan fuera de cualquier lockfile de lenguaje.

Los hashes de integridad no ayudan con nada de esto. Demuestran que los paquetes del lockfile no se manipularon; no dicen nada sobre lo que el build descargó fuera de él. Las herramientas de SCA que convierten un lockfile en una SBOM heredan los mismos puntos ciegos.

Registre el build, conserve el lockfile

Siga confirmando los lockfiles en el repositorio e instalando a partir de ellos con instalaciones congeladas. Hacen que los builds sean repetibles. Para el registro de lo que contiene una versión, CRACI registra el propio build: un proxy que entiende de paquetes en sus propios runners de GitHub Actions registra cada paquete que descarga cada job, incluidos los paquetes restaurados desde cachés de CI, y la SBOM de cada job indica su propia completitud. Ese registro ofrece una visión más completa de las dependencias en uso que un escaneo del lockfile. Consulte las SBOM durante el build, o reserve una demo para comparar ambos en uno de sus propios builds.

Lockfiles: preguntas frecuentes

¿Qué es un lockfile?

Un lockfile es un archivo que escribe un gestor de paquetes para registrar la versión exacta de cada dependencia que resolvió, directa o transitiva, junto con su procedencia y una suma de comprobación. Las instalaciones posteriores lo leen para reproducir el mismo árbol en lugar de volver a resolver los rangos de versiones.

¿Debo confirmar mi lockfile en el repositorio?

Sí, en las aplicaciones y en todo lo que despliegue. Sin un lockfile confirmado, cada instalación nueva vuelve a resolver los rangos de versiones y puede incorporar nuevas versiones transitivas. Confírmelo e instale a partir de él con una instalación congelada, como npm ci en CI.

¿Un lockfile fija las dependencias transitivas?

Sí. Es su función principal. El manifiesto solo enumera sus dependencias directas y los rangos permitidos; el lockfile registra la versión exacta elegida para cada paquete del árbol.

¿Los lockfiles se aplican a las bibliotecas que publico?

No para sus usuarios. npm, por ejemplo, nunca publica package-lock.json y lo ignora en cualquier lugar que no sea el proyecto raíz. Las aplicaciones que instalan su biblioteca resuelven sus dependencias por su cuenta, dentro de los rangos que permite su package.json.

¿Para qué sirve el campo integrity de package-lock.json?

Contiene un hash Subresource Integrity, normalmente sha512, del tarball del paquete. npm comprueba con él el paquete descargado, de modo que un tarball manipulado de una versión bloqueada no se instala. Protege los paquetes del lockfile, no lo que el build descarga fuera de él.

¿Un lockfile es lo mismo que una SBOM?

No. Un lockfile es una entrada: el plan que sigue un gestor de paquetes en un proyecto. Una SBOM es un inventario de una versión. Las herramientas de SCA suelen convertir un lockfile en una SBOM, lo cual funciona cuando el build instaló exactamente el lockfile y nada más.