Xcode ругается «No such module», хотя фреймворк на месте: что делать?

«No such module»: знакомый кошмар каждого Swift-разработчика

Вы добавляете фреймворк через SPM, CocoaPods или вручную, видите его в Project Navigator, всё выглядит идеально — но Xcode упрямо пишет: No such module 'Alamofire' (или любой другой модуль). Знакомо? Если да — вы не одиноки. Оригинальный вопрос на Stack Overflow собрал десятки тысяч просмотров, а комментарии к нему превратились в настоящий сборник боли iOS-разработчиков.

В этой статье мы разберём 10 реальных причин, почему возникает ошибка No such module, и покажем, как их исправить. В конце вас ждёт чек-лист, который сэкономит часы нервов.

Почему Xcode не видит модуль? Топ-10 причин

1. Derived Data — главный виновник

Xcode кэширует информацию о проекте в папке Derived Data. Если кэш устарел или повреждён, компилятор «забывает» про подключённые модули. Это первое, что нужно проверить.

Как исправить:

• Закройте Xcode
• Откройте терминал и выполните:

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

• Или вручную: Xcode → Preferences → Locations → Derived Data → нажать на стрелку → удалить папку
• Перезапустите Xcode и сделайте Cmd + B

2. Неправильная конфигурация Build Phases

Даже если фреймворк физически есть в проекте, Xcode может не знать, что его нужно линковать. Проверьте Link Binary With Libraries:

• Выберите цель (target) → Build Phases
• Разверните Link Binary With Libraries
• Убедитесь, что ваш фреймворк там есть
• Если нет — нажмите + и добавьте его

3. Swift Package Manager: не та ветка или версия

SPM — удобный инструмент, но он чувствителен к версиям. Если вы указали from: "1.0.0", а в репозитории версия 2.0.0, Xcode может не найти совместимый модуль.

// Пример Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git", from: "5.6.0")
]

Что делать:

• Перейдите в File → Packages → Update to Latest Package Versions
• Если проблема осталась — удалите фреймворк и добавьте заново
• Проверьте Package Dependencies в проекте — модуль должен быть зелёным

4. Конфликт архитектур (Architectures)

Старые фреймворки могут быть собраны только для arm64, а ваш проект включает симулятор (x86_64). С появлением Apple Silicon это стало частой причиной.

Решение: Добавьте в Build Settings → Excluded Architectures для Debug-сборки:

• Для симулятора: arm64
• Для устройства: $(ARCHS_STANDARD)

5. Неправильный путь поиска (Framework Search Paths)

Если вы добавляете фреймворк вручную, Xcode должен знать, где его искать. Проверьте Framework Search Paths:

• Build Settings → Framework Search Paths
• Убедитесь, что путь ведёт к папке с .framework или .xcframework
• Для SPM обычно ничего указывать не нужно, но для ручных фреймворков — обязательно

6. Фреймворк не добавлен во все цели

В проекте может быть несколько таргетов (основное приложение, виджеты, расширения). Если вы добавили модуль только в один, другие таргеты не увидят его.

Проверка: Выберите фреймворк в Project Navigator → инспектор справа → Target Membership — отметьте все нужные цели.

7. Проблемы с CocoaPods (если используете)

CocoaPods — классика, но иногда после pod install фреймворк не подхватывается.

• Закройте Xcode
• Выполните в терминале:

  pod deintegrate
  pod install

• Откройте .xcworkspace, а не .xcodeproj

8. Разные версии Swift

Если фреймворк собран на Swift 5.0, а ваш проект на Swift 5.9 — возможны несовместимости. Проверьте Build Settings → Swift Language Version — лучше всего ставить Swift 5 для совместимости.

9. Очистка кэша модулей (Module Cache)

Xcode кэширует скомпилированные модули отдельно от Derived Data. Иногда помогает:

rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/Caches/com.apple.dt.Xcode

10. Блокировка файлов и права доступа

Редкая, но коварная причина — фреймворк скачался с неправильными правами. Проверьте:

• Находятся ли файлы фреймворка на диске
• Нет ли у них пометки «заблокирован» (Get Info → Locked)
• Не перемещали ли вы папку проекта после установки зависимостей

Как найти истинную причину? Быстрая диагностика

Если вы перепробовали всё, а ошибка No such module остаётся — не паникуйте. Вот алгоритм, который поможет локализовать проблему за 5 минут:

1. Создайте новый пустой проект и попробуйте импортировать тот же модуль. Если ошибка исчезла — проблема в конфигурации вашего проекта, а не в модуле.
2. Соберите проект с флагом -v (Xcode → Product → Scheme → Edit Scheme → Build → Pass build settings in environment → добавить VERBOSE=1). В логах будет видно, пытается ли Xcode линковать модуль.
3. Проверьте логи SPM: File → Packages → Resolve Package Versions — если есть красные ошибки, вы увидите причину.

Пример: пошаговое решение для Alamofire

Допустим, вы добавили Alamofire через SPM, но получаете