O que é um lockfile?

O que um lockfile regista

O seu manifesto, como package.json ou pyproject.toml, lista os pacotes de que depende e os intervalos de versões que aceita. O gestor de pacotes transforma esses intervalos em versões exatas para toda a árvore, incluindo as dependências transitivas, e escreve o resultado no lockfile. A documentação do npm diz que o package-lock.json descreve "the exact tree that was generated, such that subsequent installs are able to generate identical trees".

Uma única entrada em package-lock.json tem este aspeto:

"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 é a versão exata escolhida.
• resolved é o local de onde foi obtida: um URL de tarball do registo, ou um URL de git com um commit.
• integrity é um hash Subresource Integrity do tarball, para que uma transferência adulterada falhe.
• dependencies são as suas próprias dependências, e é assim que a árvore, ou grafo de dependências, é montada.

Lockfiles por gestor de pacotes

Gestor de pacotes	Lockfile	Instalar sem o alterar
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
Go modules	Versões em go.mod e checksums em go.sum	Por defeito, os comandos de build não atualizam o go.mod

Apenas com o pip, o substituto habitual é um requirements.txt com versões exatas. Fixa o que lista, mas tudo o que deixa de fora é resolvido de novo em cada instalação.

Use instalações congeladas na CI

Um lockfile só ajuda se o build instalar a partir dele. Um simples npm install pode atualizar o package-lock.json quando este já não corresponde ao package.json, pelo que o build resolve discretamente uma nova árvore. O npm ci foi feito para ambientes automatizados:

• Exige um package-lock.json ou npm-shrinkwrap.json.
• Se o lockfile e o package.json divergirem, termina com um erro em vez de atualizar o lock.
• Remove primeiro qualquer node_modules existente.
• Nunca escreve no package.json nem no lockfile.

Os outros comandos da tabela acima fazem o mesmo para os respetivos gestores de pacotes.

Aplicações e bibliotecas

Faça commit do lockfile para aplicações e para tudo o que implementar. Nas bibliotecas, bloqueia apenas o seu próprio desenvolvimento e a sua CI: o npm nunca publica o package-lock.json e ignora-o em tudo o que não seja o projeto raiz. As aplicações que instalam a sua biblioteca resolvem elas próprias as dependências desta, dentro dos seus intervalos de versões. A única exceção do npm é o npm-shrinkwrap.json, que é publicado e tem precedência, e que a maioria das bibliotecas não deve usar.

Porque é que um lockfile não é um registo do que foi distribuído

Um lockfile é o plano de um gestor de pacotes num projeto. O build que produziu a sua versão fez mais do que seguir esse plano:

• Pode não o ter usado. Uma instalação não congelada, um lockfile em falta ou um segundo lockfile num monorepo significa que a árvore foi resolvida de forma diferente do ficheiro que está a ver.
• Caches. Os pacotes restaurados de uma cache de CI são instalados sem serem obtidos, e uma cache restaurada por uma chave parcial pode ser anterior ao lockfile atual. Consulte o que a cache do GitHub Actions esconde.
• Ferramentas de build. As setup actions, os compiladores, os linters e os geradores de código chegam por outros canais, com as suas próprias árvores de dependências.
• Transferências e scripts de instalação. Um curl num passo de build ou o script de instalação de um pacote obtém código que nenhum lockfile lista.
• Imagens base. Um build de contentor obtém imagens e pacotes do sistema operativo que estão fora de todos os lockfiles de linguagem.

Os hashes de integridade não ajudam em nada disto. Provam que os pacotes do lockfile não foram adulterados; nada dizem sobre o que o build obteve fora dele. As ferramentas de SCA que transformam um lockfile numa SBOM herdam os mesmos pontos cegos.

Registe o build, mantenha o lockfile

Continue a fazer commit dos lockfiles e a instalar a partir deles com instalações congeladas. Tornam os builds repetíveis. Para o registo do que uma versão contém, o CRACI regista o próprio build: um proxy que reconhece pacotes nos seus runners de GitHub Actions regista cada pacote que cada job obtém, incluindo pacotes restaurados de caches de CI, e a SBOM de cada job indica a sua própria completude. Esse registo dá uma visão mais completa das dependências em uso do que uma análise do lockfile. Consulte as SBOM durante o build ou marque uma demo para comparar os dois num dos seus próprios builds.

Lockfiles: perguntas frequentes

O que é um lockfile?

Um lockfile é um ficheiro que um gestor de pacotes escreve para registar a versão exata de cada dependência que resolveu, direta e transitiva, juntamente com a sua origem e um checksum. As instalações seguintes leem-no para reproduzir a mesma árvore em vez de voltarem a resolver os intervalos de versões.

Devo fazer commit do meu lockfile?

Sim, para aplicações e para tudo o que implementar. Sem um lockfile no repositório, cada nova instalação volta a resolver os intervalos de versões e pode trazer novas versões transitivas. Faça commit dele e instale a partir dele com uma instalação congelada, como npm ci na CI.

Um lockfile fixa as dependências transitivas?

Sim. É essa a sua principal função. O manifesto lista apenas as suas dependências diretas e os respetivos intervalos permitidos; o lockfile regista a versão exata escolhida para cada pacote da árvore.

Os lockfiles aplicam-se às bibliotecas que publico?

Não para os seus utilizadores. O npm, por exemplo, nunca publica o package-lock.json e ignora-o em tudo o que não seja o projeto raiz. As aplicações que instalam a sua biblioteca resolvem elas próprias as dependências desta, dentro dos intervalos que o seu package.json permite.

O que faz o campo integrity no package-lock.json?

Guarda um hash Subresource Integrity, normalmente sha512, do tarball do pacote. O npm verifica o pacote transferido face a esse hash, pelo que um tarball adulterado de uma versão bloqueada não se instala. Protege os pacotes do lockfile, não aquilo que o build obtém fora dele.

Um lockfile é o mesmo que uma SBOM?

Não. Um lockfile é uma entrada: o plano que um gestor de pacotes segue para um projeto. Uma SBOM é um inventário de uma versão. As ferramentas de SCA transformam muitas vezes um lockfile numa SBOM, o que funciona quando o build instalou exatamente o lockfile e nada mais.