O que esse erro de npm quer dizer

ERESOLVE: o erro que fez todo mundo digitar --force

Do npm 7 em diante, peer dependency virou regra, não sugestão. Antes o npm só avisava; hoje ele para a instalação. Foi a mudança que mais gerou raiva na comunidade — e a maioria das respostas na internet manda você silenciar o erro em vez de entender.

Peer dependency é a biblioteca dizendo: “eu não instalo o React, mas preciso que exista um, e da versão que eu sei usar.” Quando duas bibliotecas discordam sobre essa versão, o npm não tem como escolher — e para.

As três saídas, da melhor para a pior

1. Atualizar a biblioteca atrasada. É o conserto de verdade. Na maioria das vezes existe uma versão nova dela que já aceita a versão nova do peer:

npm view react-datas versions --json | tail -20
npm i react-datas@latest

2. --legacy-peer-deps. Manda o npm se comportar como o npm 6: instala assim mesmo e torce. Funciona muito na prática — porque grande parte dos avisos de peer é conservadorismo do autor, não incompatibilidade real. Mas você fica sem rede de proteção.

3. --force. A pior. Ela não é uma versão mais forte da anterior: --force manda o npm ignorar vários tipos de conflito, sobrescrever pacote e aceitar incompatibilidade declarada. Quando alguém diz “usei --force e funcionou”, quase sempre --legacy-peer-deps resolveria com menos dano.

Se você usa pnpm ou yarn

O pnpm é ainda mais rígido e falha com ERR_PNPM_PEER_DEP_ISSUES. Em vez de flag global, ele deixa você declarar a exceção no package.json, o que é melhor: fica registrado, versionado e explicável.

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": { "react": "18" }
    }
  }
}

O erro que só acontece no CI

Roda na sua máquina, quebra no pipeline. Quase sempre é um destes dois, e os dois têm a mesma raiz: o lockfile não está em sincronia com o package.json.

# npm
npm ERR! `npm ci` can only install packages when your package.json
npm ERR! and package-lock.json are in sync

# pnpm
ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile"

Acontece quando alguém edita o package.json na mão — mudando uma versão, adicionando uma dependência — e commita sem rodar a instalação. Na máquina de quem editou funciona, porque lá o install comum conserta o lockfile na hora. No CI não: npm ci e --frozen-lockfile se recusam a alterar o lockfile de propósito, e isso é uma qualidade — é o que garante build reproduzível.

O conserto é rodar a instalação localmente e commitar o lockfile atualizado:

npm install          # atualiza o package-lock.json
git add package-lock.json && git commit -m "sync lockfile"

EACCES: o erro que o sudo piora

Permissão negada em instalação global. A resposta mais comum na internet é sudo npm install -g — e é justamente ela que estraga tudo: arquivos passam a pertencer ao root dentro de ~/.npm, e a próxima instalação sem sudo falha também. O problema se multiplica.

A causa real é o Node estar instalado num diretório que pede privilégio. A solução é não ter esse diretório: use um gerenciador de versão, que instala tudo dentro da sua pasta pessoal.

# conserta o estrago do sudo antigo
sudo chown -R $(whoami) ~/.npm ~/.config

# e resolve a causa
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

Detalhando o caminho do nvm: está no artigo de instalação e gerenciamento do Node.js com nvm.

Quando apagar node_modules é a resposta certa

Virou piada, mas existe uma família de erros em que apagar é mesmo o conserto — são os de estado corrompido, não de configuração:

• EINTEGRITY — o hash baixado não bate com o do lockfile. Cache corrompido, ou lockfile gerado contra outro registry.
• Cannot read properties of null (reading 'matches') — lockfile em estado inválido, clássico de merge mal resolvido.
• ENOTEMPTY / EBUSY — arquivo travado por outro processo, comum no Windows com antivírus ou com o editor aberto.

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Para o resto — ERESOLVE, E404, EACCES, lockfile fora de sincronia — apagar não muda nada, porque o problema não está no que foi baixado.

Quando o erro não é do npm

Duas famílias enganam porque aparecem no meio da saída do npm, mas a causa está em outro lugar:

gyp ERR! — algum pacote tem código nativo e precisa compilar. Falta compilador, Python ou ferramenta de build no sistema. O erro verdadeiro está algumas linhas acima do npm ERR!.

ELIFECYCLE com código diferente de zero — o npm rodou o seu script e o script falhou. A instalação foi bem; quem quebrou foi o build, o teste ou o lint. Procure o erro acima, não a linha do npm.