O que é um lockfile e por que você deveria commitá-lo?

Por Daniel Zoghalchali·Latchkey

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.

Perguntas frequentes

What is What is a lockfile and why should you commit It??

Manifest files like package.json declare version *ranges*; a lockfile records the exact versions those ranges resolved to. That distinction is the difference between a reproducible build and "it broke and nothing changed".

Manifest vs lockfile?

A manifest says "I want lodash ^4.17.0" - a range. A lockfile says "lodash resolved to exactly 4.17.21, with this integrity hash" - and does the same for every transitive dependency. The manifest captures intent; the lockfile captures the exact realized tree.

What happens without one?

If the lockfile is gitignored or missing, each install re-resolves the ranges against the latest matching versions. Two runs days apart can get different transitive dependencies, producing the classic "passes on my machine, fails in CI" with no code change. Caching also degrades because there is no stable key.

Using it correctly in CI?

Use the frozen/clean-install mode that installs strictly from the lockfile and fails on drift (npm ci, yarn --frozen-lockfile, pip install --require-hashes, cargo build --locked). That guarantees CI builds exactly what the lockfile specifies and flags any drift instead of silently resolving around it.

Guias relacionados

Dependency Caching Strategies for Faster CIRe-downloading dependencies every run is wasted time. Learn what to cache, how to key it on a lockfile, and Cache Key vs Restore Key: How CI Cache Lookups WorkA cache key is the exact entry to save and look up; restore keys are prefix fallbacks for a near-miss. Retries and Idempotency in CI: Retry Safely Without Side EffectsRetrying a failed step only helps if the step is idempotent - safe to run twice.