Tutoriais de VPS
npm ERESOLVE no VPS: peers, npm ci e lockfile (2026)
Leia o conflito, escolha versões compatíveis e revise o lock. Instale do zero e valide a aplicação antes de publicar.

Implantar Node.js, Next.js ou projeto de agente pode parar quando npm install apresenta ERESOLVE unable to resolve dependency tree. O npm não consegue formar uma árvore aceitável; confira compatibilidade entre peerDependencies do plugin e a biblioteca principal.
Leia versão encontrada e faixa exigida e faça a menor mudança. Preserve package-lock.json e evite --force como padrão. Instalação bem-sucedida não comprova compatibilidade em execução.
Os exemplos usam npm 11, com revisão original em 16 de outubro de 2026. Consulte sua versão e corrija em branch de desenvolvimento, builder ou novo release, fora das dependências em serviço.
| Log | Investigar | Evitar inicialmente |
|---|---|---|
ERESOLVE, Could not resolve dependency, peer | Faixas, origem e resolução | Trocar espelho/cache repetidamente |
EAI_AGAIN, ETIMEDOUT | DNS, rede, proxy, registry | Alterar peers |
EBADENGINE ou engines | Versões Node/npm | Presumir conflito peer |
EACCES | Usuário/permissões | Instalar tudo com sudo |
Killed, heap | Memória/limites | Atualizar dependências como correção de memória |
Falhas podem aparecer em sequência; siga a etapa real. Se instalar funciona e build morre, veja OOM Next.js.
O exemplo escolhe React 17 e React DOM exige React 18:
Found: [email protected]
Could not resolve dependency:
peer react@"^18.2.0" from [email protected]
Extraia:
- Versão principal escolhida:
[email protected]. - Faixa:
[email protected]precisa dereact@^18.2.0. - Solicitante: confira se
react-domé direto ou transitivo.
Baixar outra cópia não resolve automaticamente. peerDependencies declara compatibilidade plugin/biblioteca. Desde v7 npm instala peers por padrão e pode rejeitar restrições impossíveis; veja peerDependencies. React 17/18 reproduz restrições históricas, não recomenda versões para 2026. Escolha por suporte, manutenção de segurança e testes.
Na raiz correta, colete verificações de leitura no local, CI, build Docker e VPS:
pwd
git status --short
node --version
npm --version
npm pkg get engines packageManager
npm config get registry
npm config get legacy-peer-deps
npm config get strict-peer-deps
npm config get omit
- Compare commit,
package.jsone lockfile. - Confira Node/npm frente ao projeto, equipe e imagem.
- Identifique fluxo npm/pnpm/Yarn original.
- Compare
legacy-peer-deps=truelocal e servidor. - Veja
NODE_ENV=productione configurações npm do ambiente CI.
packageManager não obriga todo sistema a trocar ferramentas. Leia logs antes de atualizar npm globalmente. Projeto/usuário/global, CLI e ambiente influenciam; usuários SSH e deploy podem diferir. Veja .npmrc. Compartilhe só ajustes necessários sem credenciais, não arquivos inteiros com tokens.
Use a versão do erro, ainda no exemplo histórico:
npm view [email protected] peerDependencies engines --json
npm view [email protected] engines --json
npm view react-dom peerDependencies sem versão pode descrever latest, não a versão antiga. npm view lê metadata; veja npm view. Para privados, use o registry do projeto, sem enviar nomes a serviços alheios.
Se há instalação, rastreie origem:
npm explain react
npm ls react react-dom --all
npm explain explica pacotes instalados. Sem instalação completa ou node_modules, pode ser parcial: consulte erro, package.json raiz, workspaces e lock. Veja npm explain. npm ls pode retornar não zero por invalid/missing: preserve evidência. Veja npm ls.
| Opção | Quando | Validar |
|---|---|---|
| Atualizar plugin, manter biblioteca | Há versão mantida compatível | API, configuração e função |
| Alterar biblioteca e complementos | Migração aceitável | Requisitos, build e negócio |
| Substituir plugin abandonado | Sem versão compatível | Função, dados e configuração |
| Exceção temporária existente | Histórico, testes e saída documentados | CI, riscos e remoção |
Não reduza framework por um peer: aplicação/outros plugins podem precisar de APIs novas. Busque uma combinação suportada em comum.
Este package.json cria conflito em projeto isolado de demonstração; não substitua o real:
{
"name": "vps-eresolve-proof",
"version": "1.0.0",
"private": true,
"dependencies": {
"react": "17.0.2",
"react-dom": "18.2.0"
}
}
No diretório de exemplo, execute:
npm install --package-lock-only --ignore-scripts
Somente ali, troque dependencies.react para 18.2.0, preserve react-dom em 18.2.0 e execute:
npm install --package-lock-only --ignore-scripts
npm ci --ignore-scripts
npm ls react react-dom --depth=0
O artigo original relata teste temporário separado com Node.js 24.21.0 / npm 11.19.0: ERESOLVE antes; lock e npm ci corretos depois; ambos diretos em 18.2.0; npm ci não reescreveu o lock.
O teste histórico desativou scripts de ciclo de vida e comprova só a árvore demonstrada. Projeto real precisa de scripts, build e funções; --ignore-scripts não é deploy completo. Veja npm install.
Corrija package.json e lock em ambiente revisável. Implante declarações, lock e ajustes validados com instalação limpa.
npm ci exige lock e falha na divergência; não repara nem escreve package.json ou lock, e remove primeiro node_modules. Veja npm ci.
- Execute fora do diretório ativo para evitar substituição de dependências em serviço.
- Corrija divergência no build sem improvisar npm install em produção.
- Árvore peer incompatível também pode falhar no npm ci.
Revise o diff real:
git diff -- package.json package-lock.json
Versione o lock. Mudanças alheias grandes exigem conferir versão/configuração npm e remoção acidental. Veja package-lock.json. Em workspaces, mantenha lock compartilhado na raiz acordada, não outro inutilizado em subdiretório.
| Opção | Efeito | Comprova compatibilidade? |
|---|---|---|
--legacy-peer-deps | Ignora peers ao formar árvore | Não |
--force | Relaxa várias proteções, inclusive peers raiz | Não; impacto mais amplo |
--omit=peer | Não instala peers no disco, mas projeta árvore válida | Não contorna conflito |
Veja npm Config. Corrija versões; um flag sugerido no erro não vira política global.
Exceção legacy precisa de motivo, combinação, testes e retirada. Flags que formam árvore normalmente exigem consistência em CI. Guarde política não secreta revisada em .npmrc, sem tokens. Remover flag mantendo lock antigo não comprova modo estrito: valide resolução e instalação limpa.
Escolhe versões novamente, podendo evitar conflito e introduzir atualizações alheias. Preserve original e revise diff no desenvolvimento.
Não. overrides altera seleção, não compatibilidade API ou faixas arbitrárias. Confira escopo/limites diretos em overrides e valide aplicação.
Não num conflito explícito. Investigue integridade/metadata só com evidência; veja npm cache.
omit controla disco, não descarta toda resolução. Build pode precisar de TypeScript/bundler; diferencie construção e execução.
Cadeia completa, faixas compatíveis, diff mínimo e instalação limpa sem bypass; depois build, tipos e funções existentes. Exceção mantida precisa de impacto e plano de retirada.
- Registre Node/npm, commit e resolução reais.
- Instalação limpa sem invalid/missing inexplicados.
- Build, checks e negócio existentes passam; demonstração não substitui validação real.
- Declarações, lock e configuração não secreta revisados, explicando mudanças alheias.
- Prepare novo release/CI, valide saúde antes de mudar e preserve artefato/lock anterior.
- Reverta código, dependências e configuração juntos, não só package.json deixando node_modules novos.
O objetivo é uma aplicação compatível reproduzível, além de desaparecer ERESOLVE.