Como limpar o cache do npm no Mac com segurança

Separe cache, dependências instaladas e projeto

O cache do npm guarda downloads reutilizáveis para vários projetos e costuma ficar em ~/.npm no macOS, embora possa ser configurado em outro local. node_modules é a árvore instalada de um projeto. package.json e package-lock.json registram o estado do projeto; não são cache. npm-shrinkwrap.json também não é cache, mas o npm v12 não lê nem grava esse arquivo. Se ele for o único lockfile de um projeto legado, renomeie-o para package-lock.json, de formato idêntico, antes da reinstalação; nunca sobrescreva um package-lock.json existente.

Meça o cache ativo e verifique-o primeiro

Não presuma que um ~/.npm existente seja o cache ativo. npm config get cache mostra o caminho usado pela configuração atual; meça-o com du e anote o espaço livre. npm cache verify verifica o índice e os dados, valida a integridade e remove conteúdo desnecessário sem descartar todos os downloads válidos. Para manutenção normal ou um erro de instalação alheio ao cache, essa verificação costuma bastar.

1. Execute npm --version e npm config get cache; confirme que o caminho retornado é um cache, não uma pasta de projeto.
2. Meça esse caminho exato com du -sh e anote o espaço livre do macOS, sem alterar package.json nem os lockfiles.
3. Encerre processos npm install, npm ci, npm exec e de publicação; execute npm cache verify e preserve o resumo e os erros.
4. Execute npm cache clean --force somente se a verificação não bastar, a economia de espaço for relevante e todos os artefatos necessários continuarem acessíveis.
5. Execute novamente npm cache verify, meça o mesmo caminho e teste um projeto representativo com lockfile, build e testes inalterados.

Nunca passe um caminho não verificado para rm -rf. Também não combine a limpeza do cache com apagar ou regenerar um lockfile: você mudaria duas variáveis de uma vez e perderia a comparação necessária para diagnosticar o problema.

Use npm cache clean --force de forma intencional

Execute npm cache clean --force somente quando o cache medido for relevante, você precisar do espaço agora e puder baixar os artefatos outra vez. O comando limpa o cache configurado, não node_modules nem os lockfiles. Depois, npm install e npm ci podem demorar mais ou falhar sem conexão; registries privados, servidores Git, proxies e pacotes que deixaram de estar disponíveis elevam o custo de recuperação. Não defina force como configuração permanente do npm.

Valide o resultado sem mudar as dependências

Depois da limpeza, consulte novamente o caminho, meça o mesmo local e compare o espaço livre real do macOS. Teste um projeto representativo com package.json e o lockfile inalterados, além de seu build e seus testes. Se o erro original voltar, não repita a exclusão: ERESOLVE, credenciais, 404, proxies, certificados, engines do Node.js, builds nativos e scripts de ciclo de vida exigem outro diagnóstico. O AskClean reconhece ~/.npm por padrão; confirme caminhos personalizados com npm.

Limites de exclusão e custo de recuperação

Encontre e meça o cache de downloads que o npm realmente usa, verifique-o primeiro e limpe-o somente quando houver motivo, sem tocar em node_modules nem nos arquivos do projeto.

Perguntas frequentes