В Capacitor есть несколько разных состояний проекта. Ошибка в планировании возникает, когда их называют одной «сборкой».

Официальные требования Capacitor прямо связывают iOS-разработку с macOS, Xcode и Xcode Command Line Tools: документация по настройке окружения Capacitor. Это не означает, что вы обязаны покупать отдельный компьютер. Это означает, что в цепочке должен присутствовать доступный Mac — локальный, выделенный удалённый или временный.

На Windows или Linux можно выполнить большую часть повседневной работы:

• вести исходный код и pull request;
• запускать линтеры и Web-тесты;
• собирать веб-часть приложения;
• проверять API, маршрутизацию и бизнес-логику;
• готовить команды CI до macOS-этапа.

Но такая машина не заменяет Xcode. Она не доказывает, что нативный проект компилируется. Она также не подтверждает работу разрешений, глубоких ссылок, push-уведомлений, камеры и жизненного цикла приложения после перехода в фон.

Именно поэтому вопрос следует формулировать не как «можно ли разработать Capacitor без Mac», а как «на каком этапе мне понадобится macOS и кто будет отвечать за этот этап». Для ранней Web-разработки ответом остаётся Windows или Linux. Для iOS-поставки — Mac.

Перед подключением CI подготовьте отдельную базовую линию. Не начинайте с рабочего каталога, где уже остались старые пакеты, ручные исправления или глобальные инструменты неизвестного происхождения.

Зафиксируйте в репозитории:

• версию Capacitor и состояние всех пакетов;
• версию Node.js, выбранную проектом;
• активную версию Xcode;
• способ установки нативных зависимостей;
• команды синхронизации и сборки;
• способ хранения переменных CI;
• ожидаемые имена артефактов;
• процедуру удаления и повторного создания рабочей директории.

Для первого запуска используйте условные значения:

export PROJECT_DIR="$HOME/work/<PROJECT_ID>"
export BUNDLE_ID="<BUNDLE_ID>"
export TEAM_ID="<TEAM_ID>"
export SCHEME="<SCHEME>"

Не подставляйте в документацию команды реальные пароли, идентификаторы команды, ключи или пути к связке ключей. Внутри проекта оставляйте маркеры <PROJECT_ID>, <BUNDLE_ID> и <TEAM_ID>, а реальные значения передавайте через защищённые переменные CI.

Базовая последовательность

Сначала подключитесь к удалённому Mac по SSH. Затем проверьте инструменты, но не обновляйте их вслепую:

sw_vers
xcodebuild -version
node --version
npm --version
git --version
xcode-select -p

После этого выполните чистое получение исходного кода:

git clone <REPOSITORY_URL> "$PROJECT_DIR"
cd "$PROJECT_DIR"
git checkout <COMMIT_OR_BRANCH>
npm ci

Команда npm ci должна использовать lock-файл проекта. Если он отсутствует, остановите проверку и сначала согласуйте способ фиксации зависимостей. Иначе результат на удалённом узле нельзя будет сравнить с локальным.

Далее создайте минимальный Web-артефакт штатной командой проекта:

npm run build

Синхронизируйте iOS-часть только после успешной Web-сборки:

npx cap sync ios

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

В Capacitor 8.5 переход на Xcode 27 связан с требованиями к UIScene. Руководство обновления нужно читать как список проверок проекта, а не как рекомендацию «просто открыть его в новой версии Xcode».

Проверьте следующие области:

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

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

Новые проекты Capacitor ориентируются на Swift Package Manager. Это не означает, что существующий проект на CocoaPods обязан немедленно переходить на SPM. Для принятия решения разделите два вопроса:

1. Собирается ли текущий проект с его фактическим менеджером зависимостей?
2. Есть ли отдельная причина для миграции менеджера?

Если CocoaPods-проект стабильно устанавливает зависимости, его переход на SPM не должен быть условием первого успешного запуска. Одновременная миграция Capacitor, Xcode, UIScene и менеджера пакетов увеличивает область поиска ошибки. Сначала зафиксируйте рабочую сборку с текущей схемой. Затем планируйте смену CocoaPods на Swift Package Manager как отдельную задачу.

Для диагностики используйте командную строку и сохраняйте журнал:

mkdir -p artifacts/logs

xcodebuild \
  -workspace "<WORKSPACE_PATH>" \
  -scheme "<SCHEME>" \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=<SIMULATOR_NAME>' \
  clean build \
  2>&1 | tee artifacts/logs/simulator-build.log

Точные имена workspace, scheme и Simulator должны соответствовать проекту. Не копируйте их из чужого примера. После завершения проверьте код возврата команды и наличие ожидаемых файлов. Если команда завершилась ошибкой, этап подписи не начинается: сертификат не исправляет ошибку исходников, пакетов или настроек Xcode.

Документация Capacitor для iOS помогает отделить генерацию iOS-проекта от последующих действий Xcode. Для процесса CI это важное разделение: Web-артефакт можно получить вне Mac, но доказательство готовности iOS-приложения появляется только после нативной сборки.

Пустой шаблон не показывает, выдержит ли проект релиз. Добавьте в проверку хотя бы один плагин, который действительно используется приложением. Выбор зависит от продукта:

• глубокие ссылки для проверки перехода из внешнего URL;
• push-уведомления для проверки разрешений и восстановления состояния;
• камера для проверки доступа к оборудованию;
• собственный Swift-код для проверки связки приложения с нативным модулем.

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

Для каждого плагина соберите наблюдаемые доказательства:

• приложение запускается после чистой установки;
• URL вызывает ожидаемый маршрут;
• разрешение запрашивается в правильный момент;
• отказ в разрешении обрабатывается;
• возврат из фона не сбрасывает состояние;
• повторный запуск не создаёт дубликаты обработчиков;
• ошибка плагина появляется в журнале с понятным контекстом;
• тест повторяется после удаления и повторной установки приложения.

Холодный запуск, восстановление из фона, URL-вызов и обращение к плагину проверяйте отдельными сценариями. Не смешивайте их в один длинный тест: при сбое будет непонятно, на каком переходе нарушился жизненный цикл.

У удалённого Mac Simulator запускается через графическую сессию macOS. SSH сам по себе не создаёт полноценный рабочий стол. Для командной сборки достаточно xcodebuild, но для интерактивного запуска Simulator потребуется VNC или другой рабочий удалённый доступ, а также активная пользовательская сессия. Это одна из причин, по которой удалённый Mac удобнее обычного Linux-сервера: вы получаете не только командный интерфейс, но и среду Xcode.

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

Когда Debug-сборка и плагины подтверждены, переходите к подписи. Эти этапы должны быть отделены от обычной Web-проверки, чтобы Mac не занимался задачами, которым Xcode не нужен.

В CI разделите контуры так:

• Windows или Linux выполняют установку JavaScript-зависимостей, линтинг и Web-тесты;
• macOS выполняет синхронизацию iOS-проекта, xcodebuild, Simulator и Archive;
• защищённый этап выполняет экспорт и загрузку;
• ручное подтверждение остаётся перед публикацией.

Apple описывает подготовку приложения к бета-тестированию и релизу в документации по распространению приложения. Для вашего процесса это означает, что Archive и загрузка — отдельные состояния, а не синоним успешной компиляции.

Разделяйте:

• обычную учётную запись сборки;
• сертификат распространения;
• закрытый ключ;
• профиль подписи;
• ключ API;
• права на загрузку;
• ручное утверждение публикации.

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

Пример командного этапа без реальных идентификаторов:

xcodebuild \
  -workspace "<WORKSPACE_PATH>" \
  -scheme "<SCHEME>" \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  archive \
  -archivePath "$PWD/artifacts/<APP_NAME>.xcarchive" \
  | tee artifacts/logs/archive.log

Затем отдельно выполните экспорт с конфигурацией, хранящейся вне исходного кода:

xcodebuild \
  -exportArchive \
  -archivePath "$PWD/artifacts/<APP_NAME>.xcarchive" \
  -exportOptionsPlist "<EXPORT_OPTIONS_PATH>" \
  -exportPath "$PWD/artifacts/export"

До загрузки убедитесь, что Archive создан в чистом рабочем каталоге, схема совпадает с ожидаемой, а артефакт можно передать следующему этапу. Рекомендации Apple по диагностической информации при сборке приведены в материале о debug-информации. Сохраняйте журнал xcodebuild, описание окружения и идентификатор коммита, но удаляйте из логов секреты.

Используйте этот список после первого полного прогона. Каждый пункт должен быть подтверждён артефактом, журналом или ссылкой на результат CI.

• [ ] Новый рабочий каталог создаётся из репозитория без ручных файлов.
• [ ] Версии Capacitor, Node.js и Xcode записываются в журнал.
• [ ] Web-сборка проходит до запуска macOS-этапа.
• [ ] npx cap sync ios проходит с зафиксированным lock-файлом.
• [ ] Изменения UIScene проверены по руководству Capacitor 8.5.
• [ ] Выбранный менеджер зависимостей документирован.
• [ ] Debug-сборка через xcodebuild создаёт ожидаемый результат.
• [ ] Приложение запускается в Simulator через доступную графическую сессию.
• [ ] Реальный нативный плагин проверен после чистой установки.
• [ ] Проверены холодный запуск, фон, URL-вызов и восстановление состояния.
• [ ] Ограничения Simulator сопоставлены с планом тестирования на устройстве.
• [ ] Archive выполняется отдельно от Web-проверок.
• [ ] Сертификаты, ключи и API-доступы не хранятся в репозитории.
• [ ] Повторный запуск после перезагрузки Mac описан и проверен.
• [ ] При сбое есть понятная точка остановки и процедура отката.

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

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

Временная среда подходит, если:

• релизы происходят редко;
• проект почти не меняет нативную часть;
• плагины уже проверены;
• вам нужен короткий доступ для Archive и загрузки;
• команда готова каждый раз заново подтверждать окружение.

Удалённый Mac лучше подходит, если:

• нативные плагины регулярно меняются;
• нужно исследовать UIScene и фоновые переходы;
• Xcode используется как постоянный инструмент;
• CI должен запускаться по расписанию;
• требуется доступ по SSH и интерактивный доступ к Simulator;
• вы хотите хранить воспроизводимую базовую линию и процедуру восстановления.

Двойной контур разумен, если миграция ещё не стабилизировалась. Web-проверки остаются в существующем CI, а macOS-задачи запускаются на временном или удалённом Mac. После нескольких повторяемых прогонов можно решить, нужен ли постоянный узел.

Для команд, которым нужно сначала проверить доступ и процесс, можно изучить варианты удалённого Mac в KVMNODE. Если требуется сравнить именно формат Mac mini для постоянной работы, используйте страницу заказа Mac mini для удалённой разработки. Не выбирайте узел только по названию чипа: для Capacitor важнее доступность нужной версии Xcode, графической сессии, SSH, восстановления и безопасного хранения подписей.

Windows или Linux остаются правильным местом для Web-кода, тестов бизнес-логики и большинства ежедневных задач. Но они не закрывают Capacitor 8.5 iOS-поставку: нативная компиляция, Xcode 27, Simulator, Archive и подпись требуют macOS.

Текущая схема «разработка на Windows или Linux плюс случайный доступ к чужому Mac» обычно имеет три недостатка: состояние окружения неизвестно, нативный плагин трудно воспроизвести, а ключи и процесс восстановления не принадлежат команде. Обычный Linux-сервер добавляет ещё одно ограничение — он не заменяет Xcode и macOS Simulator. В такой ситуации аренда удалённого Mac у KVMNODE даёт более управляемый путь для пробного запуска: вы можете пройти полный цикл, проверить перезапуск, отделить SSH-задачи от графических и только затем решить, нужен ли постоянный CI-узел.

Начните с чистой копии проекта, завершите миграцию UIScene и проверьте реальный плагин. После успешного Archive возьмите период удалённого доступа, покрывающий полный цикл сборки, подписи и восстановления. Если все пункты чек-листа повторяются без ручных исправлений, переводите macOS-этап в постоянный CI. Если нет — сохраняйте двойной контур до устранения причины, а не заменяйте проблему покупкой оборудования.