Infra8 min de leitura
Não subestime o lock file: npm ci, conflitos e segurança
O que o package-lock.json, o yarn.lock e o pnpm-lock.yaml fazem de verdade, por que commitar, npm ci x npm install, hash de integridade e como resolver conflito.

Se você usa npm, Yarn ou pnpm, já viu um package-lock.json, um yarn.lock ou um pnpm-lock.yaml no projeto. Muita gente ignora, apaga quando dá conflito ou nem commita.
Isso é um erro sério, e neste post eu mostro por quê com exemplos que rodei de verdade, não só com teoria.
Publiquei a primeira versão deste post no Medium em setembro de 2025. Esta é a versão revisada, com testes, o npm ci (que ficou de fora do original), o jeito certo de resolver conflito e uma correção sobre o que o hash de integridade protege e o que ele não protege.
TL;DR#
- O
package.jsonaceita faixas de versão (^2.0.0quer dizer "qualquer 2.x"). O lock file guarda a versão exata que foi instalada, de cada dependência e das dependências delas. - Sem o lock, o mesmo
package.jsoninstala versões diferentes em dias diferentes. No meu teste, deu2.1.1com o lock e2.1.3sem ele. - Commite o lock file e nunca apague ele pra "resolver" problema.
- No CI, use
npm ci(oupnpm install --frozen-lockfile, ouyarn install --immutable). Ele instala exatamente o que está no lock e falha se o lock estiver desatualizado. - O hash de integridade garante que o pacote é o mesmo que foi travado, byte a byte. Ele não diz se o pacote é seguro, mas impede que uma versão nova, talvez maliciosa, entre sem ninguém ver.
- Conflito no lock: resolva o
package.jsone rodenpm installde novo. O npm refaz o lock sozinho. - Um projeto, um gerenciador. Misturar npm e Yarn gera dois locks que discordam.
O que o lock file faz#
No package.json, você raramente escreve uma versão exata. O padrão do npm install é salvar uma faixa:
{
"dependencies": {
"ms": "^2.0.0"
}
}O ^2.0.0 quer dizer "qualquer versão 2.x a partir da 2.0.0". Hoje isso pode ser a 2.1.1. Amanhã, se sair uma 2.1.4, é ela. E isso vale pra cada dependência das suas dependências também.
O lock file resolve isso: ele guarda a versão exata que foi instalada, de onde ela veio e um hash do arquivo. Esse é o trecho do ms no package-lock.json do meu teste:
"node_modules/ms": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
"integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg..."
}O teste: o mesmo package.json, duas versões#
Montei um projeto com o ms travado na 2.1.1 e o package.json aceitando ^2.0.0. Depois instalei duas vezes: uma com o lock, outra copiando só o package.json pra uma pasta nova.
$ npm ci && node -p "require('ms/package.json').version"
2.1.1
# same package.json, no lock file
$ npm install && node -p "require('ms/package.json').version"
2.1.3É exatamente o "na minha máquina funciona": quem instalou há seis meses tem uma versão, quem clonou hoje tem outra, e o bug só aparece pra uma das duas pessoas. Com o lock commitado, as duas instalam a mesma coisa.
npm install ou npm ci?#
Os dois instalam dependências, mas com objetivos diferentes:
npm installrespeita o lock enquanto ele combina com opackage.json, mas pode atualizar o lock: se você adicionou um pacote ou mudou uma faixa, ele resolve de novo e reescreve o arquivo. É o comando do dia a dia, quando você quer mudar dependência.npm ciapaga anode_modulese instala exatamente o que está no lock. Nunca altera o lock. Se opackage.jsone o lock não combinam, ele para com erro:
npm error code EUSAGE
npm error `npm ci` can only install packages when your package.json and package-lock.json
or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install`
before continuing.Esse erro é uma ajuda: alguém mudou o package.json e esqueceu de commitar o lock. Melhor o CI quebrar do que subir pra produção com versões que ninguém testou.
Regra prática: npm install na sua máquina quando você quer mudar dependência; npm ci no CI, no Docker e sempre que você só quer instalar o que o projeto já define.
Os outros gerenciadores têm o equivalente:
| Gerenciador | Lock file | Instalar sem mexer no lock |
|---|---|---|
| npm | package-lock.json | npm ci |
| pnpm | pnpm-lock.yaml | pnpm install --frozen-lockfile |
| Yarn (2 ou mais novo) | yarn.lock | yarn install --immutable |
| Yarn 1 | yarn.lock | yarn install --frozen-lockfile |
No pnpm e no Yarn moderno, esse modo já é o padrão quando eles detectam que estão rodando num CI.
O hash de integridade#
Cada pacote no lock tem um campo integrity, um hash SHA-512 do arquivo baixado. Na instalação, o npm calcula o hash do que chegou e compara. Pra ver isso funcionando, troquei o hash do ms no lock por um falso:
$ npm ci
npm error code EINTEGRITY
npm error sha512-AAAA...== integrity checksum failed when using sha512:
wanted sha512-AAAA...== but got sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg...O npm se recusou a instalar. O original deste post dizia que esse hash "impede que bibliotecas maliciosas sejam instaladas", e isso precisa de um ajuste. O hash garante que o pacote é exatamente o mesmo que foi travado. Se a versão travada já fosse maliciosa, o hash bateria do mesmo jeito.
A proteção de verdade está em outro lugar: com o lock e o npm ci, uma versão nova não entra sem alguém pedir. Em 8 de setembro de 2025, uma semana depois do original deste post, a conta de um mantenedor foi invadida e versões maliciosas de pacotes muito usados, como o chalk@5.6.1 e o debug@4.4.2, ficaram no npm por cerca de duas horas. Projeto com faixa ^ e sem lock, instalando naquela janela, podia puxar a versão infectada. Projeto com o lock travado numa versão anterior e instalando com npm ci continuava com a versão de antes.
Boas práticas#
1. Commite o lock file#
Ele é parte do projeto, como o package.json. Sem ele no Git, cada pessoa e cada build resolve as faixas de novo e pode chegar em versões diferentes. A única exceção comum é quem publica uma biblioteca no npm: o lock dela não vai junto pro projeto de quem instala. Mesmo assim, vale commitar, pra que o seu próprio CI seja reprodutível.
2. Não apague o lock pra resolver problema#
Apagar o lock e rodar npm install não "limpa" nada: atualiza todas as dependências de uma vez, até as que não tinham nada a ver com o problema. Se algo quebrou, você trocou um bug por vinte mudanças que ninguém revisou. Entenda o erro primeiro. Se precisa atualizar um pacote, atualize esse pacote.
3. Conflito no lock: deixe o gerenciador resolver#
Duas branches adicionaram dependências diferentes, e o merge deu conflito no package.json e no lock. Resolver o lock à mão, linha por linha, é pedir pra errar. O jeito certo:
- resolva o conflito do
package.jsonà mão (é curto e legível); - rode
npm install.
O npm entende os marcadores de conflito no package-lock.json e refaz o arquivo juntando os dois lados (testado no npm 11). No meu teste, uma branch adicionou o left-pad e a outra o is-number. Depois de juntar as duas no package.json e rodar npm install, o lock ficou sem nenhum marcador de conflito e com os dois pacotes:
$ git merge feat-a
CONFLICT (content): Merge conflict in package-lock.json
CONFLICT (content): Merge conflict in package.json
# fix package.json by hand, then:
$ npm install
added 1 package, and audited 4 packages in 395msDepois, confira o diff do lock antes de commitar. Ele deve mostrar só os pacotes das duas branches.
4. Um projeto, um gerenciador#
Se o projeto tem package-lock.json, use npm. Se tem pnpm-lock.yaml, use pnpm. Rodar yarn num projeto npm cria um yarn.lock que não sabe nada do package-lock.json, e os dois passam a discordar sobre as versões.
Pra deixar isso explícito, declare o gerenciador no package.json. O pnpm e o Yarn leem esse campo:
{
"packageManager": "pnpm@10.0.0"
}5. Atualize de propósito#
Quer atualizar? Use o comando do gerenciador, e de preferência um pacote por vez:
npm outdated # what is behind
npm update ms # update within the package.json range
npm install ms@latest # jump to the latest version (may change the range)O lock muda junto, e o diff mostra exatamente o que mudou. Ferramentas como o Dependabot e o Renovate fazem isso por você, abrindo um PR por atualização.
Resumo#
- O
package.jsondiz quais versões servem; o lock diz qual versão foi instalada. - Commite o lock e não apague ele pra "resolver" problema.
npm cino CI e no Docker,npm installquando você quer mudar dependência.- O hash garante que o pacote não mudou; o lock garante que versão nova não entra sem PR.
- Conflito no lock: resolva o
package.jsone rodenpm install. - Um gerenciador por projeto.
O lock file não é um incômodo: é ele que garante que o código testado é o código que vai pra produção.
Referências#
Leia também

Infra11 min de leitura
Datadog do zero: como integrar e como ler o painel

Infra15 min de leitura
Como economizar tokens no Claude Code com rtk e graphify

Infra13 min de leitura
Arquivo apagado não some: antes de vender seu HD ou SSD