O que é um lockfile e por que você deveria commitá-lo?
Um lockfile registra a versão resolvida exata (e o hash) de cada dependência, direta e transitiva. Commite-o e todos - inclusive o CI - constroem contra a árvore de dependências idêntica.
Arquivos de manifesto como package.json declaram *faixas* de versão; um lockfile registra as versões exatas nas quais essas faixas foram resolvidas. Essa distinção é a diferença entre um build reprodutível e "quebrou e nada mudou".
Manifesto vs lockfile
Um manifesto diz "quero lodash ^4.17.0" - uma faixa. Um lockfile diz "lodash resolveu para exatamente 4.17.21, com este hash de integridade" - e faz o mesmo para cada dependência transitiva. O manifesto captura a intenção; o lockfile captura a árvore realizada exata.
Por que commitá-lo
- Reprodutibilidade: toda máquina instala as versões idênticas.
- Estabilidade: um novo patch release de uma dep transitiva não pode quebrar o CI silenciosamente.
- Segurança: hashes de integridade deixam o instalador verificar que os pacotes não foram adulterados.
- Cacheabilidade: um lockfile estável é a cache key natural e confiável.
O que acontece sem um
Se o lockfile está gitignorado ou faltando, cada instalação re-resolve as faixas contra as últimas versões correspondentes. Duas execuções com dias de diferença podem obter dependências transitivas diferentes, produzindo o clássico "passa na minha máquina, falha no CI" sem alteração de código. O cache também degrada porque não há uma key estável.
Usando-o corretamente no CI
Use o modo de instalação congelada/limpa que instala estritamente a partir do lockfile e falha no drift (npm ci, yarn --frozen-lockfile, pip install --require-hashes, cargo build --locked). Isso garante que o CI constrói exatamente o que o lockfile especifica e sinaliza qualquer drift em vez de resolver em volta silenciosamente.
Principais conclusões
- Um lockfile fixa versões exatas e hashes para toda a árvore de dependências.
- O manifesto é intenção (faixas); o lockfile é o resultado realizado.
- Commite-o por reprodutibilidade, estabilidade, segurança e cacheabilidade.
- Use modos de instalação congelada no CI para que o drift falhe de forma barulhenta.