Xcode reclama «No such module», embora o framework esteja no lugar: o que fazer?

«No such module»: o pesadelo familiar de todo desenvolvedor Swift

Você adiciona um framework via SPM, CocoaPods ou manualmente, vê ele no Project Navigator, tudo parece perfeito — mas o Xcode insiste em escrever: No such module 'Alamofire' (ou qualquer outro módulo). Familiar? Se sim — você não está sozinho. A pergunta original no Stack Overflow reuniu dezenas de milhares de visualizações, e os comentários se transformaram em uma verdadeira coletânea de dor dos desenvolvedores iOS.

Neste artigo, vamos analisar 10 causas reais pelas quais o erro No such module ocorre e mostrar como corrigi-las. No final, você encontrará uma checklist que economizará horas de nervos.

Por que o Xcode não vê o módulo? Top 10 causas

1. Derived Data — o principal culpado

O Xcode armazena em cache informações sobre o projeto na pasta Derived Data. Se o cache estiver desatualizado ou corrompido, o compilador «esquece» os módulos conectados. Isso é a primeira coisa a verificar.

Como corrigir:

\n
• Feche o Xcode
\n
• Abra o terminal e execute:\n

  rm -rf ~/Library/Developer/Xcode/DerivedData

  \n
\n
• Ou manualmente: Xcode → Preferences → Locations → Derived Data → clicar na seta → excluir a pasta
\n
• Reinicie o Xcode e faça Cmd + B
\n

2. Configuração incorreta de Build Phases

Mesmo que o framework esteja fisicamente no projeto, o Xcode pode não saber que precisa vinculá-lo. Verifique Link Binary With Libraries:

\n
• Selecione o target → Build Phases
\n
• Expanda Link Binary With Libraries
\n
• Certifique-se de que seu framework está lá
\n
• Se não estiver — clique em + e adicione-o
\n

3. Swift Package Manager: branch ou versão errada

SPM é uma ferramenta conveniente, mas é sensível a versões. Se você especificou from: "1.0.0" e no repositório a versão é 2.0.0, o Xcode pode não encontrar um módulo compatível.

// Exemplo Package.swift\ndependencies: [\n    .package(url: "https://github.com/Alamofire/Alamofire.git", from: "5.6.0")\n]

O que fazer:

\n
• Vá em File → Packages → Update to Latest Package Versions
\n
• Se o problema persistir — remova o framework e adicione novamente
\n
• Verifique Package Dependencies no projeto — o módulo deve estar verde
\n

4. Conflito de arquiteturas (Architectures)

Frameworks antigos podem ser compilados apenas para arm64, enquanto seu projeto inclui o simulador (x86_64). Com o surgimento do Apple Silicon, isso se tornou uma causa frequente.

Solução: Adicione em Build Settings → Excluded Architectures para a compilação Debug:

\n
• Para o simulador: arm64
\n
• Para o dispositivo: $(ARCHS_STANDARD)
\n

5. Caminho de busca incorreto (Framework Search Paths)

Se você adiciona o framework manualmente, o Xcode precisa saber onde encontrá-lo. Verifique Framework Search Paths:

\n
• Build Settings → Framework Search Paths
\n
• Certifique-se de que o caminho leva à pasta com .framework ou .xcframework
\n
• Para SPM geralmente não é necessário especificar nada, mas para frameworks manuais — é obrigatório
\n

6. Framework não adicionado a todos os targets

O projeto pode ter vários targets (aplicativo principal, widgets, extensões). Se você adicionou o módulo apenas a um, os outros targets não o verão.

Verificação: Selecione o framework no Project Navigator → inspetor à direita → Target Membership — marque todos os targets necessários.

7. Problemas com CocoaPods (se estiver usando)

CocoaPods é clássico, mas às vezes após pod install o framework não é