Corrigir 'npm ERR! ERESOLVE unable to resolve dependency tree'

O temido erro npm ERR! ERESOLVE unable to resolve dependency tree
interrompe inúmeros desenvolvedores diariamente. Este erro de instalação do npm aparece quando o npm não consegue encontrar versões compatíveis de pacotes que funcionem juntos, criando um conflito de dependências que bloqueia a instalação. Veja como entender e corrigir rapidamente.
Pontos-Chave
- Erros ERESOLVE ocorrem quando o npm não consegue satisfazer todos os requisitos de versão de pacotes simultaneamente
- npm 7+ aplica verificação de dependências mais rigorosa em comparação ao npm 6
- Alinhamento de versões é a correção mais confiável, enquanto flags como —legacy-peer-deps oferecem soluções rápidas
- Atualizações regulares de dependências e verificações de compatibilidade previnem conflitos futuros
O Que Significa o Erro npm ERESOLVE?
O erro ERESOLVE ocorre quando o algoritmo de resolução de dependências do npm não consegue satisfazer todos os requisitos de versão simultaneamente. A partir do npm 7, o gerenciador de pacotes tornou-se mais rigoroso quanto a peer dependencies (dependências de pares) e conflitos de versão—o que costumava ser avisos no npm 6 agora gera erros.
Quando você vê este erro, o npm está essencialmente dizendo: “O Pacote A precisa da versão 1.0 de uma dependência, mas o Pacote B precisa da versão 2.0, e não posso instalar ambas.”
Por Que Conflitos na Árvore de Dependências do npm Acontecem
Incompatibilidade de Versões
A causa mais comum envolve requisitos de versão incompatíveis entre pacotes. Por exemplo, em um projeto Angular:
npm ERR! Found: @angular/core@11.0.3
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/common@"^9.1.0 || ^10.0.0" from @agm/core@3.0.0
Aqui, seu projeto tem Angular 11, mas o pacote @agm/core
só suporta Angular 9 ou 10.
Peer Dependencies
Peer dependencies são pacotes que não são instalados diretamente, mas espera-se que existam no seu projeto. Quando diferentes pacotes requerem versões diferentes da mesma peer dependency, surgem conflitos de pacotes Node.js. Isso é especialmente comum com:
- Bibliotecas React e React Native que requerem versões específicas do React
- Pacotes Angular que precisam de versões correspondentes do core
- Plugins Next.js que esperam configurações específicas do ESLint
Mudanças de Versão do npm
A transição do npm 6 para o npm 7+ introduziu verificação de dependências mais rigorosa. O que anteriormente instalava com avisos agora falha completamente, forçando desenvolvedores a resolver os conflitos subjacentes.
Discover how at OpenReplay.com.
Como Corrigir o Erro de Árvore de Dependências do npm
Solução 1: Atualizar ou Alinhar Versões de Pacotes (Recomendado)
Primeiro, identifique os pacotes conflitantes:
npm ls
Depois, atualize os pacotes problemáticos para versões compatíveis:
npm update package-name
# ou instale uma versão específica
npm install package-name@version
Para o exemplo do Angular acima, você poderia:
- Atualizar
@agm/core
para uma versão que suporte Angular 11 - Fazer downgrade do Angular para a versão 10
Solução 2: Instalação Limpa
Às vezes, limpar tudo ajuda:
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
Isso força o npm a recalcular toda a árvore de dependências do zero.
Solução 3: Usar a Flag —legacy-peer-deps
Quando você precisa de uma solução rápida, a flag --legacy-peer-deps
instrui o npm a usar o antigo algoritmo de resolução do npm 6:
npm install --legacy-peer-deps
Para tornar isso permanente no seu projeto:
npm config set legacy-peer-deps true
Importante: Embora isso resolva o problema imediato, ignora as verificações de segurança do npm. Seus pacotes podem não funcionar corretamente juntos.
Solução 4: Usar a Flag —force
A flag --force
ignora todos os conflitos de dependências:
npm install --force
Aviso: Esta é a opção mais arriscada. Use-a apenas quando você entender as consequências e não tiver outra escolha.
Exemplos do Mundo Real
Conflito ESLint no Next.js
npm ERR! peer eslint@"^7.23.0 || ^8.0.0" from eslint-config-next@14.0.4
Correção: Atualize para o eslint-config-next mais recente:
npm install eslint-config-next@latest --save-dev
Incompatibilidade de Versão no React Native
npm ERR! peer react@"18.0.0" from react-native@0.70.0
Correção: Certifique-se de que as versões do React e React Native são compatíveis verificando a tabela de compatibilidade do React Native.
Melhores Práticas para Prevenir Erros de Instalação do npm
- Mantenha as dependências atualizadas regularmente - Não deixe os pacotes ficarem muito desatualizados
- Verifique a compatibilidade antes de atualizar - Use
npm outdated
para ver atualizações disponíveis - Use versões exatas em produção - Considere usar versões exatas (
1.2.3
em vez de^1.2.3
) para dependências críticas - Documente requisitos de versão - Anote quaisquer combinações específicas de versões que funcionam no seu README
Quando Usar Cada Solução
- Alinhamento de versões: Sempre tente isso primeiro—é a correção adequada
- Instalação limpa: Quando o package-lock.json pode estar corrompido
- —legacy-peer-deps: Para projetos antigos ou quando você entende os riscos
- —force: Último recurso apenas para ambientes de desenvolvimento
Conclusão
O erro npm ERESOLVE é frustrante, mas solucionável. Embora flags como --legacy-peer-deps
e --force
ofereçam correções rápidas, a solução mais estável continua sendo atualizar pacotes para versões compatíveis. Entender por que esses conflitos de pacotes Node.js ocorrem ajuda você a escolher a correção certa para sua situação e prevenir futuros problemas na árvore de dependências do npm.
Perguntas Frequentes
A flag --force ignora todos os conflitos e avisos durante a instalação, enquanto --legacy-peer-deps especificamente usa a resolução de peer dependency menos rigorosa do npm 6. Legacy peer deps é mais segura, pois afeta apenas o tratamento de peer dependencies, enquanto force ignora todas as verificações de segurança.
Sim, execute npm config set legacy-peer-deps true globalmente. No entanto, isso não é recomendado, pois se aplica a todos os projetos na sua máquina. Em vez disso, adicione um arquivo .npmrc com legacy-peer-deps=true a projetos específicos que precisem dele.
Isso normalmente acontece quando você atualiza o npm da versão 6 para 7 ou superior, atualiza um pacote que introduz novas peer dependencies, ou quando uma dependência atualiza seus próprios requisitos. Verifique sua versão do npm com npm -v e mudanças recentes em pacotes.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.