Archivos de bloqueo e instalaciones reproducibles

Los archivos de bloqueo fijan el grafo de dependencias exacto para que las laptops, CI y las compilaciones de producción instalen paquetes idénticos en todo momento.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Desarrollador: actualiza las dependencias intencionalmente
npm install
git add package.json package-lock.json
 
# CI: instalación limpia reproducible
npm ci

# .github/workflows/ci.yml (extracto)
- run: npm ci
- run: npm test

Cuándo usarlo:

• CI no debe resolver nuevas versiones en cada ejecución del pipeline.
• Las compilaciones de Docker de producción necesitan node_modules deterministas.
• Las auditorías de seguridad deben hacer referencia a las mismas versiones que tú distribuyes.

Ejemplo de trabajo

# Dockerfile - compilación de API de múltiples etapas
FROM node:24.18.0-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
FROM node:24.18.0-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:24.18.0-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
CMD ["node", "dist/server.js"]

# Verificación local: el archivo de bloqueo coincide con package.json
npm ci
npm test

Lo que esto demuestra:

• npm ci elimina node_modules e instala exactamente desde package-lock.json.
• La etapa deps de Docker usa --omit=dev para una imagen de producción más pequeña.
• La etapa de compilación ejecuta npm ci completo para que las devDependencies (TypeScript) estén disponibles para compilar.

Análisis profundo

Cómo funciona

• package-lock.json (npm) registra las versiones resueltas, los hashes de integridad y la estructura anidada.
• npm install puede actualizar el archivo de bloqueo cuando los rangos permiten versiones compatibles más nuevas.
• npm ci falla si package.json y el archivo de bloqueo no coinciden, protegiendo a CI de la desviación.
• pnpm usa pnpm-lock.yaml; Yarn usa yarn.lock - solo uno por repositorio.

Comandos del gestor

Notas de TypeScript

{
  "scripts": {
    "verify:lockfile": "npm ci && npm run typecheck && npm test"
  }
}

• Ejecuta verify:lockfile después de fusionar PRs de dependencias para detectar reconstrucciones nativas faltantes.
• Confirma los cambios del archivo de bloqueo en el mismo PR que las ediciones de package.json.

Errores comunes

• Ejecutar npm install en CI - Resuelve versiones nuevas y oculta la desviación del archivo de bloqueo hasta la producción. Solución: usa npm ci exclusivamente en los pipelines.
• Confirmaciones parciales del archivo de bloqueo - Actualizar package.json sin el archivo de bloqueo rompe a los compañeros de equipo y a CI. Solución: siempre confirma ambos archivos juntos.
• Gestores mixtos - package-lock.json más yarn.lock causa instalaciones impredecibles. Solución: elimina los archivos de bloqueo no utilizados; documenta el gestor elegido en el README.
• Conflictos de fusión del archivo de bloqueo - Las ediciones manuales corrompen las entradas de integridad. Solución: regenera con npm install después de resolver package.json.
• Problemas de enmascaramiento de caché global - Las cachés obsoletas de CI sirven tarballs antiguos. Solución: clave las cachés en el hash del archivo de bloqueo; invalida en el cambio del archivo de bloqueo.

Alternativas

Preguntas frecuentes

rm -rf node_modules
npm install
git add package-lock.json

npm audit --audit-level=high

Relacionado

• Scripts de package.json - npm ci luego npm test en CI
• Cadena de suministro: npm audit y Socket - auditar el grafo bloqueado
• Mejores prácticas de gestores de paquetes - política de un solo archivo de bloqueo

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.