Todos os artigos

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.

Também em English, Español, Français

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.

O clássico “na minha máquina funciona”: mesmo package.json, versões diferentes

TL;DR#

  • O package.json aceita faixas de versão (^2.0.0 quer 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.json instala versões diferentes em dias diferentes. No meu teste, deu 2.1.1 com o lock e 2.1.3 sem ele.
  • Commite o lock file e nunca apague ele pra "resolver" problema.
  • No CI, use npm ci (ou pnpm install --frozen-lockfile, ou yarn 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.json e rode npm install de 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
A faixa do package.json aceita várias versões. O lock escolhe uma e não muda mais

É 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 install respeita o lock enquanto ele combina com o package.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 ci apaga a node_modules e instala exatamente o que está no lock. Nunca altera o lock. Se o package.json e 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:

GerenciadorLock fileInstalar sem mexer no lock
npmpackage-lock.jsonnpm ci
pnpmpnpm-lock.yamlpnpm install --frozen-lockfile
Yarn (2 ou mais novo)yarn.lockyarn install --immutable
Yarn 1yarn.lockyarn 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.

O lock não sabe se um pacote é seguro. Ele só não deixa uma versão nova entrar sem ninguém pedir

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:

  1. resolva o conflito do package.json à mão (é curto e legível);
  2. 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 395ms

Depois, 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.json diz quais versões servem; o lock diz qual versão foi instalada.
  • Commite o lock e não apague ele pra "resolver" problema.
  • npm ci no CI e no Docker, npm install quando 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.json e rode npm 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#

Atualizado em

  • Infra
  • npm
  • pnpm
  • yarn
  • lock file
  • ci
  • segurança

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.