No macOS, identifique primeiro se o npm está relatando um conflito de merge do Git, uma divergência entre package.json e package-lock.json ou um erro de resolução de peer dependency. Verifique os arquivos do projeto, o estado do Git e as versões do npm no Terminal antes de alterar qualquer coisa. Se apenas o lockfile precisar ser reconciliado, a opção --package-lock-only do npm pode atualizá-lo sem reinstalar os pacotes em node_modules.

Comece na pasta do projeto e preserve o estado atual

Abra o Terminal, acesse o diretório do projeto e confirme que você está na raiz pretendida do projeto. No Finder, você pode localizar a pasta e usar o comando cd do Terminal; se o caminho contiver espaços, coloque-o entre aspas, por exemplo, cd "$HOME/Projects/My App". Execute:

pwd
git status --short
node --version
npm --version

O git status --short mostra se algum dos manifestos possui edições não commitadas. Se houver alterações que você precisa manter, salve-as ou faça commit antes de prosseguir; não sobrescreva arquivos enquanto ainda estiver decidindo quais mudanças de dependências devem ser mantidas. Registre as versões do Node.js e do npm para compará-las com a configuração documentada do projeto ou a configuração de integração contínua (CI). Os formatos de lockfile do npm mudaram entre as versões principais do npm, portanto, uma diferença de formato pode explicar alterações inesperadas sem significar que as dependências em si estejam corrompidas. Documentação do package-lock do npm

Determine qual tipo de conflito você tem

Se o package-lock.json contiver marcadores do Git como <<<<<<<, ======= ou >>>>>>>, trata-se de um conflito de merge no controle de versão. Inspecione todas as seções afetadas e compare as alterações de ambas as branches. Resolva primeiro as declarações de dependência no package.json: as orientações mais antigas do npm sobre conflitos de lockfile instruem explicitamente a resolver manualmente os conflitos do manifesto antes de regenerar o lockfile. Não mantenha simplesmente um dos lados do lockfile por hábito; cada branch pode ter adicionado ou modificado dependências. Orientações de conflito do package-lock do npm

Se não houver marcadores do Git, compare os nomes e intervalos (ranges) de dependências no package.json com o lockfile. O package.json especifica intervalos aceitáveis, enquanto o lockfile registra uma árvore de dependências resolvida. A documentação atual do npm afirma que um npm install normal usa as versões fixadas no lockfile quando elas satisfazem os intervalos do manifesto e atualiza o lockfile quando não satisfazem. Como o npm install usa um lockfile

Se o comando falhar com uma mensagem de peer dependency, concentre-se nos pacotes indicados nesse erro e em seus requisitos de pares. Pode ser uma incompatibilidade válida entre os intervalos de pacotes declarados, e não uma instalação corrompida. Não use --force ou --legacy-peer-deps como um atalho de diagnóstico: alterar o comportamento de resolução de dependências pode gerar uma árvore diferente da configuração pretendida para o projeto.

Inspecione a alteração antes de pedir ao npm para reconciliar

Revise o histórico do projeto e o diff atual:

git diff -- package.json package-lock.json
git log -5 --oneline -- package.json package-lock.json

Procure pelo commit ou pela branch que alterou a declaração de dependência, a versão do lockfile ou a configuração do npm. Verifique também se o projeto possui um .npmrc; o npm documenta que opções que moldam a árvore, como legacy-peer-deps ou install-links, podem afetar a consistência entre um lockfile e uma instalação limpa posterior. Use as mesmas configurações específicas do projeto já adotadas pelo repositório em vez de adicionar novas flags aleatoriamente. Documentação do npm ci

O valor de lockfileVersion ajuda a identificar o formato do arquivo, mas evite tratá-lo como um diagnóstico por si só. O npm documenta as versões de formato 1, 2 e 3 e observa que versões mais recentes do npm podem atualizar lockfiles mais antigos. Uma versão alterada pode refletir o comportamento de compatibilidade do npm; inspecione o diff real de dependências antes de aceitar uma reescrita ampla. Formato de lockfile e arquivos mais antigos

Reconcilie o lockfile sem reinstalar as dependências

Depois de resolver quaisquer marcadores de conflito e deixar o package.json correto, peça ao npm para atualizar apenas o lockfile:

npm install --package-lock-only

O npm documenta essa opção como uma forma de atualizar o package-lock.json sem verificar a pasta node_modules ou baixar dependências. É uma etapa de reconciliação focada; ela não garante que o conjunto resultante de dependências seja exatamente o que você pretendia, portanto, examine o diff em seguida. Opções do npm install

git diff --check
git diff -- package.json package-lock.json
git status --short

O git diff --check ajuda a identificar erros de espaços em branco, enquanto o próprio diff mostra o que o npm alterou. Confirme se o manifesto não recebeu edições indesejadas, inspecione alterações de versão inesperadas ou uma reescrita ampla do lockfile e verifique se os marcadores de conflito desapareceram. Se as alterações propostas não fizerem sentido, restaure os arquivos a partir do seu estado salvo ou do controle de versão e reavalie a causa, em vez de excluir a pasta node_modules ou regenerar tudo.

Saiba quando uma instalação limpa é apropriada

Use o npm ci apenas após o manifesto e o lockfile estarem intencionalmente alinhados e você desejar reproduzir a árvore de dependências travada no lockfile. Ele requer um lockfile, falha em vez de atualizar em caso de incompatibilidade e remove um diretório node_modules existente antes de instalar. Isso o torna útil para confirmar um estado resolvido, mas não é um comando inofensivo de inspeção. Comportamento do npm ci

Se o comando npm install --package-lock-only não conseguir resolver o conflito, registre o erro exato, revise os intervalos dos pacotes mencionados e as configurações de npm do projeto e compare com a branch ou ambiente de CI que gerou o lockfile. A questão decisiva é quais declarações de dependência o projeto deve manter; uma limpeza de instalação não responderá a isso por você. Uma vez que essa decisão esteja refletida no package.json, regenere apenas o lockfile, inspecione a alteração proposta e, em seguida, decida se uma instalação limpa é necessária.

Fontes