В сборке Mac Catalyst появляется ошибка API, хотя тот же проект собирается для iOS.
Быстрое решение: сначала проверьте, обращается ли код к API, предназначенному только для iOS 27.1, и возникает ли ошибка исключительно при сборке Catalyst. Если да, изолируйте платформенный участок условной компиляцией по рекомендации Apple; если причина не подтверждена или проверка не прошла, не переводите производственную сборку на RC.
Кому пригодится: разработчикам, которые поддерживают общую кодовую базу iOS и Mac Catalyst и проверяют новые API.
Инженерам CI — чтобы воспроизвести проблему в отдельном окружении и решить, оставлять ли стабильный инструментальный набор.
Небольшим командам с удалённой сборкой macOS — чтобы проверить окружение и заранее определить безопасный откат.
Последняя проверка: 25 октября 2026 года. Сведения сверены с примечаниями Apple к Xcode 27.2 и записью о выпуске Xcode 27.2 RC. Если Apple обновит примечания или выпустит окончательную версию, перед изменением производственного конвейера проверьте актуальный статус ещё раз. Сам факт упоминания проблемы в примечаниях не означает, что она обязательно воспроизводится во всех сборках RC.
Сбой компиляции Mac Catalyst: границы известной проблемы
Apple описала случай, когда использование API, предназначенных только для iOS 27.1, в проекте Mac Catalyst может приводить к ошибке компиляции. В примечаниях также приведён обходной путь: отделить платформенный код условной компиляцией. Это подтверждённая причина для проверки, а не универсальное объяснение любой ошибки Catalyst.
Важны сразу три условия: проект использует соответствующий API; ошибка возникает именно для цели Mac Catalyst; диагностическое сообщение указывает на этот код или на несовместимость символа с платформой. Если хотя бы одно условие не подтверждается, не следует автоматически считать проблему дефектом Xcode. Начните с самой ранней ошибки компилятора и места, где она появилась.
Что считать совпадением с описанным случаем:
- проблемный символ вызывается в общем коде или в файле, включённом в сборку Catalyst;
- сборка iOS проходит, а Catalyst-сборка останавливается на этом символе или на связанной с ним декларации;
- после временного исключения вызова из Catalyst-ветки ошибка меняется или исчезает.
Последний пункт помогает локализовать причину, но сам по себе не доказывает, что проблему вызвал именно компилятор. Удаление вызова может скрыть и обычную ошибку проекта. Сверяйте результат с сообщением сборки, настройками цели и официальным описанием Apple.
Упоминание iOS 27.1 в примечаниях относится к API и поведению SDK, а не к обещанию, что всякий проект с такой версией минимальной системы будет собираться некорректно. Для вывода о конкретном проекте нужно проверять используемые символы, выбранный SDK и параметры именно Catalyst-цели. Примечания Apple к Xcode 27.2 описывают известный случай и обходной путь; они не заменяют диагностику вашей сборки.
Диагностика по платформе и сообщению компилятора
Сначала сравните результат двух целей, собранных из одной и той же ревизии проекта: iOS и Mac Catalyst. Не меняйте одновременно исходный код, SDK и параметры deployment target. Иначе при исчезновении ошибки вы не узнаете, какое изменение повлияло на результат.
Зафиксируйте первую ошибку, а не только итоговое сообщение вида «сборка завершилась неудачно». Запишите путь к файлу, имя символа, target, конфигурацию сборки и фрагмент команды компиляции. В цепочке сборки несколько последующих ошибок могут быть следствием одной исходной несовместимости.
Сравнение вариантов решения:
| Вариант | Когда подходит | Ограничение | Оценка для решения |
|---|---|---|---|
| Изолировать iOS-вызов условной компиляцией | Ошибка связана с API, доступным только в iOS-ветке, а для Catalyst предусмотрена допустимая альтернатива | Нужна проверка обеих платформ и поведения приложения | Высокая, если причина подтверждена |
| Исправить обычную ошибку проекта | Диагностика указывает на опечатку, неверный импорт, тип или настройку сборки, не связанные с известным случаем | Условная компиляция не должна использоваться для маскировки ошибки | Высокая, если проблема воспроизводится вне спорного API |
| Изменить deployment target | Значение действительно не соответствует поддерживаемой конфигурации проекта | Изменение само по себе не делает iOS API доступным в Catalyst | Низкая как универсальный обходной путь |
| Оставить RC вне производственного конвейера | Причина пока не установлена или проверка после изменения не прошла | Проверка новой версии инструментария откладывается | Высокая для сохранения воспроизводимой сборки |
Слова «высокая» и «низкая» здесь обозначают пригодность варианта для конкретного решения, а не измеренную производительность или вероятность успеха. Если ошибка появилась только в Catalyst, это сужает поиск, но не исключает неправильную настройку цели, различия в подключаемых файлах или другие ошибки проекта.
Для сравнения фиксируйте исходную ревизию и не меняйте её между сборками. Если iOS-цель тоже падает на том же файле и символе, ищите обычную проблему в коде или настройках. Если ошибка появляется только в Catalyst, проверьте платформенную доступность символа и то, включён ли соответствующий фрагмент в эту цель.
Deployment target и отсутствие API — разные причины
В примечаниях Apple отдельно указана проблема SDK, связанная с некоторыми значениями deployment target. Это отдельная диагностическая ветка. Нельзя считать, что изменение минимальной версии ОС исправит ситуацию, когда Catalyst-код обращается к API, недоступному для этой платформы. И нельзя делать обратный вывод: сообщение о несовместимом API не доказывает, что deployment target настроен правильно.
Сверьте настройки нужного target, а не только общую конфигурацию проекта. В Xcode разные цели могут иметь самостоятельные параметры, а конфигурации Debug и Release — отличающиеся значения. Проверьте выбранную платформу, SDK, настройки проекта и настройки самого target. Справочник Apple по параметрам сборки Xcode поможет установить, откуда берётся конкретное значение.
Для каждой ошибочной цели сохраните фактические значения параметров из лога сборки. Затем сравните их с ожидаемыми настройками проекта. Не правьте deployment target наугад и не переносите изменение в общие конфигурационные файлы, пока не выяснили, какая именно цель его использует. Особенно важно проверить, не затронет ли такое изменение настройки iOS-сборки, которые до этого работали.
Сам факт, что проект собирается с определённым deployment target, не подтверждает доступность каждого API на каждой платформе. Обратное тоже верно: ошибка при использовании API не доказывает, что значение deployment target обязательно нужно менять. Ветка диагностики должна соответствовать сообщению компилятора: несовместимый символ проверяйте отдельно от настроек минимальной версии системы.
Проверьте также, не выбирает ли CI другой SDK или конфигурацию, чем локальная сборка. Сопоставьте команду запуска, scheme и build configuration. Для проверки доступности инструментов и требований версии Xcode используйте официальную таблицу системных требований Xcode. Не предполагайте, что совпадение версии проекта означает совпадение фактического окружения.
Изоляция iOS-кода от сборки Catalyst
Swift позволяет исключить платформенный фрагмент директивой #if !targetEnvironment(macCatalyst). Для Objective-C используется проверка #if !TARGET_OS_MACCATALYST. Apple приводит эти подходы в описании известной проблемы; синтаксис Swift и его правила условной компиляции также описаны в руководстве Swift по директивам условной компиляции.
Swift-пример:
#if !targetEnvironment(macCatalyst)
func useIOSSpecificFeature() {
// Вызов API, предназначенного только для iOS
}
#endif
Objective-C-пример:
#if !TARGET_OS_MACCATALYST
- (void)useIOSSpecificFeature {
// Вызов API, предназначенного только для iOS
}
#endif
В примерах показано только исключение кода из Catalyst-ветки. Если приложение должно предоставлять аналогичную функцию на Mac, добавьте для Catalyst отдельную реализацию или явно определённое поведение без этой функции. Не оставляйте вызывающий код с ожиданием результата, который в одной из платформенных веток больше не создаётся.
Проверьте, где именно объявлен символ. Если условно скрыта только реализация, но объявление, тип или инициализатор по-прежнему ссылается на iOS-only API, Catalyst-сборка может продолжить падать. Условие нужно применять на том уровне, где компилятор встречает несовместимую декларацию или вызов. После изменения убедитесь, что остаются доступными типы и методы, которые используются общим кодом.
Осторожно относитесь к слишком широким условиям. Если исключить весь файл или крупный модуль проще, чем отдельный вызов, можно вместе с проблемным кодом убрать нужные для Catalyst декларации и зависимости. Предпочитайте минимальное платформенное разделение, которое объясняет диагностику и не меняет поведение не связанных с ошибкой участков.
После правки отдельно соберите iOS и Mac Catalyst. Успешная сборка только одной цели не является достаточной проверкой общей кодовой базы. Если у платформенных веток разное поведение, проверьте соответствующие сценарии приложения, а не только компиляцию. Для CI сохраните логи обеих сборок и ревизию, на которой они были получены.
План воспроизведения и критерии перехода
Используйте изолированное окружение, чтобы RC не менял уже работающий производственный инструментальный набор. До проверки зафиксируйте версию Xcode, выбранный SDK, целевой платформенный вариант, scheme и ревизию проекта. Официальная запись о выпуске Xcode 27.2 RC подтверждает выпуск кандидата, но не доказывает, что конкретный проект уже проверен с ним.
Порядок проверки:
- Зафиксируйте текущее состояние репозитория и команду, которой CI запускает сборку. Не совмещайте проверку с обновлением зависимостей или рефакторингом.
- Проверьте версию Xcode и доступность выбранных инструментов. Если сборка запускается через командную строку, сверьте активные developer tools с официальной инструкцией по установке инструментов командной строки.
- Соберите iOS-цель и сохраните первый полный диагностический вывод. Отметьте исходный файл и символ, на котором впервые останавливается компиляция.
- Соберите Mac Catalyst из той же ревизии и конфигурации. Сравните первую ошибку с iOS-логом, не ограничиваясь общим статусом задачи CI.
- Сверьте проблемный API с опубликованными примечаниями Apple и проверьте deployment target, SDK и параметры Catalyst-цели.
- Если применили условную компиляцию, повторите обе сборки и проверьте, что для каждой платформы существует ожидаемая реализация.
- Сохраните результаты, а затем решите, допустимо ли включать RC в отдельный тестовый контур. Для производственного перехода требуется самостоятельная проверка проекта и план возврата к прежнему инструментарию.
Минимальный отчёт о воспроизведении должен содержать версию Xcode, тип цели, проблемный файл, символ, относящиеся к задаче настройки и исходную ревизию. Не публикуйте секреты подписи, переменные доступа и содержимое закрытых конфигураций. Если ошибка не повторяется на минимальном примере, это не исключает влияние зависимостей или настроек проекта — фиксируйте, что именно отличается от реального CI.
Продолжать тестирование RC разумно, если проблема локализована, обходной путь не затрагивает неподтверждённые платформенные сценарии, обе цели проходят сборку, а результат проверен в отдельном контуре. Переход следует отложить, если причина не установлена, Catalyst-ветка лишается необходимого поведения, повторная сборка не проходит или тестирование требует менять производственные настройки без подтверждённого результата.
Не считайте статус исправленным только потому, что RC установлен или сборка однажды прошла. Перед дальнейшим решением повторно сверьте актуальные примечания Apple для RC или окончательного выпуска. Пока обновлённый статус не подтверждён, не приписывайте Apple исправление и не делайте вывод, что проблема исчезла для всех проектов.
Выбор среды для независимой проверки
Для первичного поиска причины достаточно сопоставить две цели в одинаковом контролируемом окружении. Если команде нужно проверять другую версию Xcode, воспроизводить CI или сохранять рабочую сборку отдельно, заранее проверьте, доступна ли нужная система и версия инструментария на выбранной удалённой машине. Описание удалённого рабочего стола Mac поможет оценить, подходит ли такой способ доступа для вашей проверки; список доступных узлов стоит сверить до планирования среды.
Удалённый Mac не исправляет несовместимый API автоматически. Его польза в этом сценарии — отдельное окружение для воспроизведения, в котором можно не затрагивать основной рабочий компьютер и сравнить результаты при зафиксированных настройках. Для команды также важны порядок доступа, передача диагностических логов и возможность сохранить повторяемую конфигурацию. Сначала определите требования проекта, затем проверяйте доступность системы и Xcode, а не наоборот.
Если ваша текущая сборка опирается только на локальную машину, у неё есть реальные ограничения: она может быть занята другими задачами, среду сложнее отделить от повседневной разработки, а воспроизведение ошибки зависит от того, насколько точно сохранены настройки. Эти проблемы можно уменьшить отдельной локальной машиной или собственным CI-узлом, но тогда на вас остаются покупка и обслуживание оборудования, обновления и поддержание воспроизводимой конфигурации. Для краткой проверки RC или временной изоляции проекта аренда Mac у VPSPush может оказаться практичнее покупки: перед выбором проверьте доступность нужных вам macOS и Xcode на странице планов VPSPush. Если же у вас постоянная тяжёлая нагрузка, обязательные физические интерфейсы или требования к полностью собственному оборудованию, сравните аренду с локальным Mac и своим CI-узлом по условиям именно вашего проекта.
Читайте также
Проверьте сборку Mac Catalyst на удалённом Mac
VPSPush предоставляет в аренду выделенный физический Mac mini M4 с удалённым рабочим столом — не виртуальную машину.
