Como limpar o cache do Swift Package Manager com segurança

O SwiftPM tem mais de um cache

Um pacote de linha de comando guarda checkouts, repositórios, saída de build e estado do workspace na pasta .build, e o SwiftPM mantém também um cache de repositórios compartilhado entre projetos. O Xcode acrescenta outra camada: os checkouts e produtos de build dos pacotes de um app ficam no DerivedData do projeto. Limpe a camada mais restrita que explique o sintoma — uma limpeza no projeto se recupera mais rápido e não deixa outros repositórios mais lentos.

Escolha o comando pelo alcance

O comando swift package clean apaga os artefatos de build do pacote; é a primeira escolha para saída compilada desatualizada ou para liberar espaço num único repositório. O swift package reset redefine todo o cache e o diretório de build do pacote; é mais amplo e pode obrigar a preparar de novo as dependências e o estado do workspace. Já o swift package purge-cache esvazia o cache global de repositórios do SwiftPM, usado por todos os projetos: a próxima resolução pode exigir rede e demorar mais em vários repositórios.

1. Faça commit ou stash das alterações e confirme que o Package.swift e o Package.resolved estão onde o projeto espera.
2. Na raiz do pacote, execute swift package clean e tente de novo o build original.
3. Se o workspace local do pacote continuar inconsistente, execute swift package reset e depois resolva e compile de novo.
4. Execute swift package purge-cache só se o cache compartilhado estiver grande demais ou corrompido.
5. Confira o grafo de dependências e o build antes de limpar qualquer DerivedData do Xcode.

Os comandos disponíveis dependem da toolchain Swift instalada. Execute swift package --help para confirmar os subcomandos suportados nesse Mac.

Mantenha o Package.resolved

O Package.resolved registra as versões resolvidas das dependências. Apagá-lo pode fazer a próxima resolução escolher outras versões permitidas pelo Package.swift — e transformar a limpeza numa atualização. Apague-o só quando quiser, de propósito, uma nova resolução. Package.swift, Sources, Tests, plugins e dependências locais são código-fonte; nunca os remova como se fossem cache.

Trate o Xcode separadamente

Para um problema que só aparece no Xcode, use File > Packages > Reset Package Caches e depois File > Packages > Resolve Package Versions, se a sua versão do Xcode oferecer esses comandos; ou exclua apenas a pasta do DerivedData daquele projeto. Antes de uma limpeza global, meça as pastas .build e o cache compartilhado. O AskClean ajuda a descobrir qual categoria ao redor ocupa espaço, mas o alcance da limpeza do SwiftPM é definido pelos próprios comandos do Swift.

Comparação de decisões e riscos

Limpe o cache do Swift Package Manager (SPM) com segurança: quando usar swift package clean, reset ou purge-cache e como manter o Package.resolved intacto.

Perguntas frequentes