Lockfiles & Instalações Reproduzíveis

Lockfiles fixam o grafo exato de dependências para que laptops, CI e builds de produção instalem pacotes idênticos a cada vez.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Desenvolvedor: atualiza dependências intencionalmente
npm install
git add package.json package-lock.json
 
# CI: instalação limpa e reproduzível
npm ci

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

Quando usar isso:

• A CI não deve resolver novas versões a cada execução do pipeline.
• Builds Docker de produção precisam de node_modules determinísticos.
• Auditorias de segurança devem referenciar as mesmas versões que você envia.

Exemplo de Trabalho

# Dockerfile - build de API multi-estágio
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"]

# Verificação local: lockfile corresponde a package.json
npm ci
npm test

O que isso demonstra:

• npm ci exclui node_modules e instala exatamente a partir de package-lock.json.
• O estágio deps do Docker usa --omit=dev para uma imagem de produção menor.
• O estágio build executa npm ci completo para que devDependencies (TypeScript) estejam disponíveis para compilação.

Mergulho Profundo

Como Funciona

• package-lock.json (npm) registra versões resolvidas, hashes de integridade e estrutura aninhada.
• npm install pode atualizar o lockfile quando os intervalos permitem versões compatíveis mais recentes.
• npm ci falha se package.json e o lockfile discordarem, protegendo a CI contra desvios.
• pnpm usa pnpm-lock.yaml; Yarn usa yarn.lock - apenas um por repositório.

Comandos do Gerenciador

Notas de TypeScript

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

• Execute verify:lockfile após mesclar PRs de dependência para capturar rebuilds nativos ausentes.
• Confirme as alterações do lockfile no mesmo PR das edições de package.json.

Armadilhas

• Executar npm install na CI - Resolve novas versões e oculta o desvio do lockfile até a produção. Correção: use npm ci exclusivamente em pipelines.
• Commits parciais do lockfile - Atualizar package.json sem o lockfile quebra colegas de equipe e a CI. Correção: sempre confirme ambos os arquivos juntos.
• Gerenciadores mistos - package-lock.json mais yarn.lock causam instalações imprevisíveis. Correção: exclua lockfiles não utilizados; documente o gerenciador escolhido no README.
• Conflitos de mesclagem de lockfile - Edições manuais corrompem as entradas de integridade. Correção: regenere com npm install após resolver package.json.
• Problemas de mascaramento de cache global - Caches de CI desatualizados servem tarballs antigos. Correção: chaveie caches pelo hash do lockfile; invalide em caso de alteração do lockfile.

Alternativas

FAQs

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

npm audit --audit-level=high

Relacionados

• Scripts package.json - npm ci e depois npm test na CI
• Cadeia de Suprimentos: npm audit & Socket - auditar o grafo fixado
• Melhores Práticas de Gerenciadores de Pacotes - política de um único lockfile

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.