Как подключить значок Icon Composer к Xcode 27: чек-лист 2026

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

Icon Composer предназначен для создания многослойных иконок с несколькими внешними видами и целевыми платформами. Это не замена маркетинговому изображению для страницы приложения и не гарантия того, что Xcode автоматически выберет нужный ресурс.

В Xcode необходимо проверить связь между именем файла Icon Composer, настройкой цели и фактическим источником App Icon. Если файл добавлен в навигатор проекта, но не включён в нужную цель, редактор может его отображать, а сборка — продолжать использовать старый AppIcon.

На дату проверки Apple выпускала Xcode 27 beta 6; состояние финального релиза нужно сверять с последующей записью на странице выпусков, а не предполагать заранее. Это особенно важно для проектов, которые должны проходить проверку на нескольких версиях системы.

Новый проект: когда можно сразу выбрать Icon Composer

Для нового приложения решение проще. Если минимальная версия системы и целевые устройства соответствуют вашей стратегии, Icon Composer можно принять как основной источник иконки. Старый AppIcon не нужно добавлять «на всякий случай», если вы не планируете обратную совместимость или аварийный откат.

Подготовьте исходные материалы:

1. Отдельные слои в SVG или PNG.
2. Прозрачный фон там, где его требует дизайн.
3. Понятные имена слоёв без локальных путей и персональных данных.
4. Версии, которые можно повторно открыть другим участником команды.
5. Контрольный плоский вариант для сравнения с прежней иконкой.

Затем создайте файл Icon Composer, импортируйте слои и добавьте файл в проект. В настройках Target Membership отметьте именно ту цель, которая создаёт приложение. Для iOS и macOS это могут быть разные targets, даже если они используют общий исходный набор.

В разделе конфигурации App Icon укажите имя ресурса, выбранного для цели. Не ориентируйтесь только на картинку в редакторе. Сверьте строковое имя в настройках сборки и имя подключённого файла. При несовпадении проект может успешно компилироваться, но упаковывать не тот ресурс.

После этого проверьте три внешних вида:

• Default — базовая иконка;
• Dark — вариант для тёмного оформления;
• Mono — монохромный вариант.

Официальная инструкция Apple по созданию и подключению иконки через Icon Composer описывает саму интеграцию, но не отменяет проверку установленного приложения. Превью в редакторе — только промежуточный результат.

Если приложение уже выпускается, не удаляйте каталог AppIcon в первой же ревизии. После добавления Icon Composer новый файл может изменить источник иконки для цели. Для пользователя это проявится не в Xcode, а после установки сборки на конкретную версию системы.

Создайте отдельную ветку миграции. В ней сохраните:

• исходный AppIcon;
• новый файл Icon Composer;
• изменения Build Settings;
• параметры target;
• скриншоты старой и новой иконки;
• результат Archive;
• запись о версии, к которой можно вернуться.

Уже существующий AppIcon можно сохранить на время миграции. Но наличие двух ресурсов само по себе не создаёт корректный fallback. Вы должны понимать, какой ресурс выбирает конкретный target и что реально попадает в Bundle. Документация Apple по настройке App Icon в Xcode используется как контрольная точка для параметров проекта, а не как замена тесту установленного приложения.

Icon Composer в существующем проекте: порядок добавления

Выполните действия в отдельной ветке.

1. Скопируйте текущий проект и зафиксируйте чистое состояние Git.
2. Запишите активный target, Bundle ID и имя текущего AppIcon.
3. Создайте файл Icon Composer из подготовленных слоёв.
4. Добавьте файл в проект через Xcode, а не только копированием в папку.
5. Проверьте Target Membership для приложения, расширений и дополнительных целей.
6. Сверьте настройку App Icon с именем нового ресурса.
7. Выполните чистую сборку и сохраните журнал.
8. Установите приложение на Simulator и реальное устройство.
9. Создайте Archive и проверьте его содержимое.
10. Отправьте отдельную сборку в TestFlight и сравните результат после установки.

Не меняйте одновременно иконку, минимальную версию системы, Bundle ID и настройки подписи. Иначе при ошибке вы не определите, что именно стало причиной.

Почему на старой версии iOS иконка может выглядеть иначе

Различие между системами не всегда означает ошибку сборки. На результат влияют поддерживаемый набор внешних видов, обработка маски, масштабирование, контраст и то, какой ресурс понимает конкретная версия системы. Поэтому нельзя объявлять Icon Composer полностью совместимым со всеми будущими или неподтверждёнными платформами без отдельной проверки.

Для низкой версии iOS сохраните контрольный снимок:

• экран устройства после установки;
• значок на домашнем экране;
• состояние в настройках приложения, если оно отображается;
• вариант при включённых системных настройках доступности;
• сравнение с прежним AppIcon.

Если старая система показывает базовый вариант вместо Dark или Mono, это нужно зафиксировать как ожидаемое ограничение либо отклонить миграцию. Не заменяйте проверку догадкой о том, как система «должна» обработать файл.

Важно: не смешивайте иконку приложения с изображением, которое загружается для страницы App Store. Первая проверяется внутри установленного Bundle и интерфейса устройства, второе — как отдельный маркетинговый материал.

Одна многослойная композиция не обязана одинаково хорошо работать на iPhone, iPad, Mac и Apple Watch. Маска, свободное поле, масштаб и визуальная плотность на платформах различаются. Общая структура слоёв полезна для бренда, но не должна заставлять вас жертвовать узнаваемостью отдельной версии.

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

• какая часть композиции должна оставаться в безопасной зоне;
• не исчезают ли тонкие детали после уменьшения;
• читается ли силуэт в светлом и тёмном варианте;
• не становится ли Mono-версия слишком пустой или слишком плотной;
• нужна ли отдельная корректировка слоёв, а не просто общий файл.

Проверьте также расширения и дополнительные targets. Иконка основного приложения может быть корректной, а расширение — продолжать ссылаться на старый каталог ассетов. Это особенно легко пропустить в автоматической сборке, где проверяется только успешный код возврата.

Для visionOS и других целей, которые не подтверждены вашей текущей документацией и набором инструментов, не переносите этот процесс по аналогии. Используйте отдельные официальные правила платформы. Статус поддержки Icon Composer для неподтверждённой цели нельзя выводить только из того, что редактор открыл файл.

Удалённая сборка добавляет к визуальной проверке проблемы доставки. Локально файл может находиться в рабочей папке, но отсутствовать в репозитории, не синхронизироваться скриптом или быть исключённым из архива проекта.

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

Проверьте среду по пяти направлениям.

Системные требования инструмента

Независимая версия Icon Composer на официальной странице Apple требует macOS Tahoe 26.4 или более новой версии. Это подтверждённое требование для указанного инструмента; совместимость с финальным поведением Xcode 27 проверяйте по актуальным публикациям Apple. Страница загрузки и требований Icon Composer должна быть источником при подготовке удалённого узла.

Не подменяйте системную проверку очисткой кэшей. Если инструмент не запускается, сначала сохраните сведения о macOS, Xcode, доступности Icon Composer и активной цели сборки.

Файл и версия проекта

Файл с расширением .icon должен находиться под контролем версий. Проверьте:

1. Он присутствует в репозитории.
2. Он не исключён правилами синхронизации.
3. Все связанные слои доступны в чистом checkout.
4. Путь не зависит от домашнего каталога конкретного разработчика.
5. Target Membership сохраняется после клонирования.
6. Сборочный скрипт не заменяет файл старым AppIcon.
7. Архив создаётся на том же commit, который прошёл проверку.

Если удалённый Mac не находит Icon Composer, получите полный путь ошибки и список файлов в рабочей директории. Сначала сравните commit, checkout и права чтения. Затем проверьте target и Build Settings. Только после этого анализируйте кэш Xcode.

Командная проверка Archive

Соберите Archive в неинтерактивном режиме с теми же параметрами схемы, которые применяются в CI. Сохраните:

• команду сборки;
• commit;
• выбранную схему;
• идентификатор Archive;
• журнал действий;
• предупреждения actool, ibtool и этапа упаковки.

Не удаляйте все Derived Data по умолчанию. Это уничтожает полезные следы и не исправляет ошибочное имя ресурса, отсутствующий файл или неправильное Target Membership.

После Archive осмотрите приложение внутри архива. Вам нужно подтвердить не только факт успешной компиляции, но и наличие правильного ресурса. Далее отправьте сборку через обычный канал загрузки. Справочник статусов загрузки сборок App Store Connect помогает отделить проблему обработки загрузки от ошибки самого проекта.

Используйте этот список как обязательный gate для pull request или релизной ветки:

• [ ] Название файла Icon Composer совпадает с настройкой нужного target.
• [ ] Файл и связанные слои добавлены в репозиторий.
• [ ] Target Membership проверен после чистого checkout.
• [ ] Старый AppIcon сохранён в ветке миграции.
• [ ] Для нового проекта подтверждено отсутствие случайной ссылки на старый ресурс.
• [ ] Для существующего приложения записано решение: оставить, заменить или временно вести оба варианта.
• [ ] Default, Dark и Mono проверены отдельно.
• [ ] Иконка просмотрена на Simulator.
• [ ] Иконка проверена на реальном устройстве.
• [ ] Проверена минимальная поддерживаемая версия iOS или macOS.
• [ ] Для iPhone, iPad, Mac и Watch выполнена отдельная визуальная оценка, если они входят в продукт.
• [ ] Проверены контраст и системные настройки доступности.
• [ ] Archive создан из чистого состояния.
• [ ] В Archive найден ожидаемый ресурс, а не только старый AppIcon.
• [ ] TestFlight-сборка обработана без ошибки.
• [ ] Иконка после установки TestFlight совпадает с утверждённым вариантом.
• [ ] Маркетинговое изображение для App Store проверено отдельно.
• [ ] Есть commit для отката и записано условие возврата к AppIcon.
• [ ] Логи actool, ibtool и Archive сохранены при любой ошибке.

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

Новому приложению обычно выгоднее сразу принять Icon Composer и закрепить его в target до появления первой релизной ветки. Существующему приложению безопаснее сохранить AppIcon, провести двойную проверку и удалить старый ресурс только после реального TestFlight-результата. Мультиплатформенному проекту нужен не один общий скриншот, а отдельные критерии для каждой цели.

Если локальный Mac не позволяет установить требуемую версию инструмента, текущий вариант имеет три слабых места: вы зависите от одного рабочего компьютера, не можете стабильно держать несколько версий Xcode и рискуете проверять только редакторский preview вместо полного Archive–TestFlight цикла. В такой ситуации аренда удалённого Mac в CALMVPS позволяет вынести миграционную ветку в отдельную среду с root-доступом, подключаться через VNC или SSH и не менять основной компьютер разработчика. Параметры аренды Mac в CALMVPS стоит рассматривать именно для временной проверки, удалённого Archive и повторяемой сборки, а не как автоматическое решение для любого проекта.

Если вам нужен постоянный узел с физическими устройствами, локальными USB-ключами или длительной тяжёлой нагрузкой каждый день, покупка собственного Mac может быть рациональнее. Но для миграции Icon Composer, сравнения старого AppIcon и прохождения TestFlight четырёхуровневая удалённая проверка обычно позволяет принять решение до капитальных затрат. При необходимости можно начать с отдельной среды CALMVPS, выполнить весь чек-лист и только затем решить, нужна ли вам постоянная машина.