xcconfig: многосредная конфигурация: руководство по удалённой iOS-сборке 2026

📋 Содержание

В документации Apple файл xcconfig описан как текстовый способ хранения и комбинирования настроек сборки. Если локальный Release работает, а удалённый Archive обращается к тестовому API, быстрее всего разделить публичные различия по xcconfig, включить их в репозиторий, а секреты и signing credentials передавать извне. После этого нужно проверить не только файл, но и связку Scheme, Build Configuration, Target и готового Archive.

Эта статья для вас, если вы поддерживаете среды разработки, тестирования и production и хотите убрать ручные различия в Xcode Build Settings. Она также пригодится перед переносом проекта на удалённый Mac, когда неизвестно, восстановятся ли локальные файлы и абсолютные пути. Материал рассчитан на небольшие команды, которые запускают Archive скриптом или через CI и хотят остановить сборку, если тестовый адрес или секрет попал в production-пакет.

Локальный Release и удалённый Archive

Типичный сбой выглядит убедительно: приложение запускается из Xcode, локальный Release собирается, но удалённый Archive содержит production Bundle ID и тестовый сервер. Причина обычно не в самом xcconfig, а в смешении нескольких уровней проекта.

Разделите их обязанности:

Scheme определяет действия Run, Test, Profile, Analyze и Archive, а также конфигурацию, используемую каждым действием.
Build Configuration описывает именованный набор настроек, например Debug, Staging или Release.
Target определяет создаваемый продукт: основное приложение, Widget, Notification Service Extension или другой компонент.
xcconfig хранит значения Build Settings в текстовом виде и позволяет соединять общую базу с частными переопределениями.
Info.plist получает значения через подстановку Build Settings, но не заменяет конфигурацию сборки.
runtime configuration может выбирать сервер уже во время работы приложения. Это отдельный механизм, а не функция безопасности xcconfig.
подпись и публикация используют сертификаты, provisioning profile, Keychain и учётные данные. Они не становятся защищёнными автоматически только потому, что лежат рядом с xcconfig.

Apple указывает, что настройки сборки могут приходить из нескольких источников и иметь разные приоритеты. Поэтому наличие строки в файле ещё не доказывает, что она победила в итоговом расчёте. Для спорных параметров используйте официальный справочник Build Settings, а не поиск по папке проекта.

Откройте настройки проекта и Target, выберите конкретную Build Configuration и найдите фактическое значение. Если Xcode показывает источник или уровень переопределения, зафиксируйте его. Затем повторите проверку через сборку с явно указанными Scheme и конфигурацией. Файл, который просто присутствует в репозитории, доказательством не является.

Общая база вместо копий по средам

Для небольшого приложения не нужно копировать весь набор значений Xcode в отдельные файлы. Начните с общей базы, а затем добавьте только те различия, которые действительно меняют результат.

Рабочая модель состоит из трёх слоёв:

общий слой — настройки, одинаковые для всех сред: общие флаги компиляции, минимальная версия платформы и другие значения, которые должны совпадать;
слой среды — адреса development, staging и production, имя продукта, публичные feature flags и другие значения, которые можно хранить в исходном коде;
внешний слой — API keys, пароли, токены, временные пути к signing-файлам и параметры конкретного раннера.

Общие и средовые xcconfig можно включить в контроль версий. Внешний слой должен поступать из защищённого хранилища CI, переменных удалённой машины или временного файла с ограниченным доступом. Сам xcconfig не добавляет шифрование и не контролирует права доступа.

Не копируйте без разбора системные значения из Build Settings. Это расширяет область переопределений и усложняет обновление проекта. Если Xcode уже задаёт параметр корректно, оставьте его на штатном уровне. В xcconfig добавляйте только то, что вы сознательно хотите сделать частью контракта сборки.

Для каждой среды закрепите понятное имя:

Debug — локальная разработка;
Staging — проверка интеграций и тестового API;
Release — production-поставка.

Названия сами по себе не обеспечивают безопасность. Важно, чтобы действие Archive в Scheme явно ссылалось на Release, а тестовые значения не приходили из более высокого приоритета или внешнего параметра командной строки.

Как отделить API key от адреса сервера?

Адрес сервера часто является публичной частью конфигурации и может храниться в xcconfig, если это не секретная инфраструктурная информация. API key, токен доступа и пароль в файл включать не следует. Передавайте их во время сборки через секретное хранилище, временный файл или контролируемую переменную окружения, а затем проверяйте, не попали ли они в логи, Info.plist, исходники и итоговый пакет.

Секрет, встроенный в клиентское приложение, нельзя считать скрытым от пользователя. Если ключ попадает в бинарный файл или доступен клиентскому коду, его следует рассматривать как раскрытый и ограничивать на серверной стороне.

Один Target для простой структуры

Для приложения с обычными Debug и Release начните с извлечения общей базы, а не с создания множества Target. Основной Target остаётся один, а среда определяется связкой Build Configuration и Scheme.

Порядок настройки:

Зафиксируйте текущие значения для Debug и Release в Xcode.
Запишите только параметры, которые действительно различаются: адрес API, display name, Bundle ID, флаги функций и настройки экспорта.
Создайте общую конфигурацию и вынесите туда повторяющиеся значения.
Создайте файлы среды для Debug, Staging и Release, если тестовый контур нужен постоянно.
Назначьте каждый файл соответствующей Build Configuration на уровне проекта.
Проверьте, не переопределяет ли Target те же ключи.
Настройте Scheme так, чтобы Run использовал Debug или Staging, а Archive — Release.
Выполните локальный Build для разработки и отдельно создайте Release Archive.
Очистите производные данные, выполните сборку из чистого состояния и сравните итоговые значения с ожидаемыми.

Не переносите в xcconfig весь вывод Build Settings автоматически. Ваша цель — сделать различия видимыми и управляемыми, а не создать второй непрозрачный слой настроек.

Когда достаточно одного Target?

Если продукт, entitlements, Bundle ID и набор встроенных компонентов не меняются между средами, оставьте один Target. Используйте разные Build Configuration и Scheme. Это уменьшает риск расхождения настроек и избавляет от синхронизации одинаковых параметров в нескольких местах.

Когда отдельный Target оправдан?

Если среда представляет отдельный продукт, отличается идентификатор приложения, набор capabilities или состав ресурсов, отдельный Target может быть обоснован. Но создавать Target только ради другого URL обычно не стоит: это копирует проблему вместо разделения конфигурации.

Для локальной проверки сравнивайте не только статус сборки:

фактический Bundle ID;
имя приложения;
развёрнутый URL в Info.plist;
значения feature flags;
выбранную конфигурацию Archive;
содержимое экспортируемого приложения.

Если Xcode показывает ожидаемое значение в одном Target, это ещё не доказывает, что оно будет таким же для Archive другого действия.

Scheme и Build Configuration для нескольких сред

Проблема «локально работает, а на удалённом Mac нет» часто появляется потому, что разработчик переносит файл, но не переносит Scheme или не включает пользовательскую схему в репозиторий. В результате удалённая машина выбирает стандартный Release с другим источником настроек.

Свяжите объекты явно:

каждая среда получает собственную Build Configuration;
каждая рабочая конфигурация получает Scheme с понятным названием;
действие Archive использует только производственную конфигурацию;
схема, необходимая CI, хранится в репозитории;
значения Scheme проверяются после открытия проекта на чистой машине.

Порядок наследования и переопределения нужно проверять для каждого спорного параметра. Особое внимание уделите одинаковым ключам в общей базе, файле среды, настройках Target и командной строке. Последняя строка в xcconfig не обязательно является последним значением в итоговой конфигурации.

Как подтвердить, что Archive использует правильный xcconfig?

Проверьте выбранную Scheme, её действие Archive и Build Configuration. Затем откройте финальные Build Settings для этого Target и убедитесь, что URL, Bundle ID и флаги соответствуют production. После Archive извлеките информацию из созданного продукта и проверьте уже развёрнутый Info.plist. Добавьте автоматическую проверку, которая завершает сборку ошибкой при обнаружении тестового домена в production-пакете.

Apple описывает настройку Scheme в руководстве по кастомизации Build Schemes. Используйте его как источник для интерфейсных шагов, но не подменяйте документированную настройку памятью о том, какой пункт был выбран на вашем компьютере.

Внимание: имя файла Release.xcconfig не гарантирует, что он используется в Archive. Решение принимает связка действия Scheme, Build Configuration, Target и итоговых значений.

Несколько Target и границы наследования

Widget, Notification Service Extension, Share Extension и другие встроенные компоненты имеют собственные настройки. Главный App Target может успешно архивироваться, пока расширение получает неправильный Bundle ID, deployment target или App Group.

Разделите настройки на две категории.

Общие для проекта:

значения, одинаковые для всей кодовой базы;
общие флаги компиляции;
базовые параметры платформы;
публичные настройки, которые должны совпадать у связанных компонентов.

Специфичные для Target:

Bundle ID;
entitlements;
App Group;
расширения возможностей;
deployment target, если он отличается;
ресурсы и параметры конкретного продукта.

Не переносите настройки главного приложения в расширение автоматически. Наследование должно быть намеренным: для каждого Target проверьте финальные значения в нужной Build Configuration. Успешная сборка основного приложения не подтверждает корректность всех компонентов.

Как выбрать между несколькими Target и несколькими Build Configuration?

Если меняется только сервер или публичный режим функций, выбирайте Build Configuration. Если меняется самостоятельный продукт, Bundle ID, entitlements или состав пакета, рассматривайте отдельный Target. Если обе оси меняются одновременно, сначала опишите допустимые комбинации и удалите невозможные. Иначе количество Scheme быстро станет трудным для ручной проверки.

Для Archive проверяйте каждый Target, который попадёт в пакет:

правильный Bundle ID;
ожидаемые entitlements;
корректный App Group;
production-адрес;
отсутствие тестовых флагов;
наличие нужных символов и ресурсов.

Руководство Apple по сборке нескольких Target помогает сверить роль Target в проекте. Однако разделение секретов, выбор среды и контроль production-адреса остаются задачами вашей архитектуры.

Решение по структуре конфигурации

Используйте этот список перед переносом проекта на удалённый Mac. Отмечайте только те пункты, которые уже подтверждены чистой сборкой.

[ ] Общая база содержит только настройки, одинаковые для всех сред.
[ ] Различия Debug, Staging и Release записаны в версионируемых xcconfig.
[ ] API keys, пароли, токены и signing credentials отсутствуют в репозитории.
[ ] Для каждого Archive заранее определены Scheme и Build Configuration.
[ ] Target не переопределяет средовые значения без явной причины.
[ ] Для каждого расширения проверены Bundle ID, entitlements и App Group.
[ ] На production Archive есть стоп-проверка тестового URL и debug-флагов.
[ ] Проект собирается после чистого checkout без локального файла разработчика.
[ ] Повторная сборка после перезапуска среды не требует ручного переключения.

Принимайте решение по условиям:

Если отмечены все пункты, выбирайте текущую архитектуру и переносите её на удалённый Mac.
Если не отмечен только пункт о секретах, сначала вынесите чувствительные значения во внешний слой и перевыпустите скомпрометированные ключи.
Если отсутствует связь Scheme с Archive, не запускайте публикацию: сначала зафиксируйте производственную конфигурацию.
Если основной Target проходит, а расширение нет, исправляйте границу наследования Target, а не создавайте ещё один общий xcconfig.
Если чистый checkout не собирается, восстановите недостающие Scheme, публичные файлы и процедуру подготовки в репозитории.
Если production Archive содержит тестовый домен, остановите выпуск независимо от успешного статуса Xcode.
Если сборка зависит от ручных действий в графическом интерфейсе, среда ещё не готова для CI или постоянного удалённого использования.

Эта проверка лучше простого правила «выберите Release»: она связывает источник настроек, объект сборки и содержимое результата.

Удалённый Mac и чистое восстановление

Удалённый Mac нужно рассматривать как чистую машину, а не как копию рабочего ноутбука. Если сборка требует файла, который не описан в репозитории или процедуре подготовки, она пока не воспроизводима.

Следуйте такому порядку:

Получите чистую копию репозитория без Derived Data, локальных настроек Xcode и случайных файлов из домашнего каталога.
Убедитесь, что публичные xcconfig и нужные Scheme находятся под контролем версий.
Проверьте совместимость версии Xcode и используемых SDK с проектом.
Создайте внешний конфигурационный слой из защищённых переменных или контролируемого файла.
Установите signing assets отдельно от настроек среды.
Запустите неинтерактивный Build с явно указанной Scheme.
Перезапустите удалённую сессию или машину и повторите проверку.
Выполните Release Archive и сохраните обезличенный отчёт: Scheme, Configuration, Bundle ID, адрес сервера, entitlements и результат проверки.

Для подписи используйте отдельный процесс подготовки. Apple описывает создание provisioning profile для App Store, но профиль не заменяет контроль конфигурации приложения. Не помещайте пароль сертификата или долгоживущий токен в xcconfig и не выводите секреты в журнал сборки.

Если вы готовите удалённую машину, сначала изучите критерии приёмки удалённой среды для iOS-сборки, а затем проведите проверку на чистом checkout. Для задач, где важна физически выделенная среда, заранее сравните выделенный Mac и виртуализацию macOS. Выделенная машина не исправит отсутствующий файл или неверную Scheme.

Финальный Archive и приёмка результата

Release Archive — это точка принятия решения, а не просто зелёный статус сборки. Apple отдельно описывает создание App Archive в Xcode и последующую проверку Archive. Используйте обе стадии: создание подтверждает процесс, валидация помогает проверить пригодность результата.

Перед публикацией зафиксируйте:

фактическую Scheme и Build Configuration;
Bundle ID основного приложения и расширений;
production-адрес API;
значения, развернувшиеся в Info.plist;
entitlements и App Group;
наличие ожидаемых символов;
отсутствие тестовых доменов, debug-флагов и заглушек;
результат проверки Archive;
отсутствие секретов в логах и артефактах.

Добавьте стоп-условия. Сборка должна завершаться ошибкой, если production Archive содержит тестовый URL, неизвестный Bundle ID или недопустимый флаг. Это надёжнее, чем инструкция «перед публикацией не забудьте переключить схему».

Для миграции с локального Mac на удалённую машину также оформите процедуру резервного копирования signing assets. Она не заменяет внутреннюю политику доступа, но помогает не смешивать конфигурацию среды с сертификатами и профилями.

Итоговый выбор для независимого разработчика

Оцените подход по четырём критериям: воспроизводимость чистого checkout, ясность границ среды, безопасность секретов и проверяемость Archive.

Одна Build Configuration и ручные переключения — низкая сложность сегодня, но высокий риск отправить тестовый адрес в production. Подходит только для временного прототипа.
Несколько Target ради каждой среды — понятный визуальный выбор, но много дублирования Bundle ID, entitlements и ресурсов. Подходит, когда среды действительно являются разными продуктами.
Общая база плюс xcconfig для сред — умеренная сложность и хорошая трассируемость. Это базовый вариант для одного приложения и небольшой команды.
xcconfig плюс внешний слой секретов и автоматическая проверка Archive — требует дисциплины подготовки, зато лучше всего подходит для удалённого Mac и CI.

Если ваш компьютер не может постоянно оставаться включённым, а сборку приходится повторять после каждого изменения, аренда удалённого Mac может быть удобнее локальной машины: вам не нужно покупать отдельный компьютер только для Archive, а среду можно проверить как самостоятельный чистый узел. При этом для постоянной тяжёлой нагрузки, физических периферийных устройств или строгого локального хранения данных собственный Mac может оказаться рациональнее.

Следующий шаг — выполнить чистый checkout на удалённом Mac и пройти полный Release Archive без ручного создания файлов. Если окружение восстанавливается, тестовые значения блокируются, а итоговый пакет проходит проверку, конфигурация готова к повторяемой работе. Если нет, исправляйте слой настроек или процедуру подготовки, а не добавляйте очередное локальное исключение.