EAS Build: сборка в облаке без Xcode

Android собирается на любой машине, где стоит Android Studio. iOS — только в Xcode, а Xcode бывает только на Mac. Облачный сервис Expo EAS Build это ограничение снимает. В таблице из статьи «Что Expo делает за вас» это третий этаж: те же prebuild, Gradle и xcodebuild, что и у вас на компьютере, но на машинах Expo, и для iOS это Mac с Xcode. Своя машина нужна только для того, чтобы отправить задание.

Работы на вашей машине у eas build немного. Команда разрешает профиль из eas.json, вычисляет app.config.js с его переменными, договаривается о подписи и номере сборки, упаковывает проект и отправляет архив. Всё остальное делает сервер: разворачивает чистую машину, ставит зависимости, запускает prebuild, если в репозитории нет ios/ и android/, собирает, подписывает и выкладывает файл. Вот что напечатает сборка для Google Play в проекте автора — вывод собран по исходнику eas-cli:

$ eas build --platform android --profile production

Три первые строки говорят про окружение, в котором будет вычислен конфиг; о них — секция «Чего сервер не видит». Следующие две — номер сборки и ключ подписи; оба хранятся на серверах Expo, об этом последняя секция. Строка «Compressing project files» — архив: какие файлы в него попадают, решает не вы, а правило, о котором тоже будет речь. Дальше CLI только ждёт. Если нажать Ctrl+C, сборка не прервётся: она уже стоит в очереди на сервере, а её журнал по шагам доступен по ссылке «See logs».

В архив попадает весь репозиторий, а не только папка apps/mobile. eas-cli находит корень git (git rev-parse --show-toplevel), упаковывает его, а на сервере работает в подпапке проекта. В монорепо автора из этого вытекает вот что. Пакет @jsp/contracts, из которого клиент берёт типы API, лежит в git исходниками, собранного кода там нет. Собирает его скрипт в package.json приложения. Имя у скрипта особое, eas-build-post-install — один из npm-хуков EAS Build. Сервер запускает его сам: на Android после установки зависимостей и prebuild, на iOS — ещё и после pod install. Так что к началу Gradle и xcodebuild пакет уже собран.

// apps/mobile/package.json, фрагмент
"scripts": {
  "eas-build-post-install": "cd ../.. && pnpm --filter @jsp/contracts build"
}

Сборка идёт на машине Expo, а не на вашей. Всё, что есть только у вас — файлы вне git, переменные вашего терминала, — туда не попадёт.

Как собирать, описывает eas.json рядом с app.config.js. У автора он такой, целиком:

{
  "cli": {
    "version": ">=16.0.0",
    "appVersionSource": "remote"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "channel": "development",
      "ios": {
        "simulator": true
      }
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "developmentClient": false,
      "android": {
        "buildType": "apk"
      },
      "ios": {
        "simulator": true
      },
      "env": {
        "EXPO_PUBLIC_API_URL": "https://example.com",
        "EXPO_PUBLIC_YANDEX_METRIKA_ID": "",
        "EXPO_PUBLIC_APPMETRICA_KEY": ""
      }
    },
    "production": {
      "channel": "production",
      "autoIncrement": true,
      "android": {
        "buildType": "app-bundle"
      },
      "ios": {
        "simulator": false
      },
      "env": {
        "EXPO_PUBLIC_API_URL": "https://example.com",
        "EXPO_PUBLIC_YANDEX_METRIKA_ID": "",
        "EXPO_PUBLIC_APPMETRICA_KEY": ""
      }
    }
  },
  "submit": {
    "production": {}
  }
}

Каждый ключ в build — профиль, его имя передают флагом --profile. Секция cli касается самого eas-cli, appVersionSource разберём в конце. Секция submit нужна для отправки в магазины — это статья «Магазины». Что значат поля профилей:

Перед сборкой eas-cli сворачивает профиль в один плоский объект для одной платформы. Этим занимается функция resolveBuildProfile из пакета @expo/eas-json. Правил у неё три. Сначала раскрывается extends. Потом секция нужной платформы накладывается поверх общей части, а секция другой платформы выбрасывается. Всё это ложится на значения по умолчанию из схемы файла. Ниже функция перенесена почти дословно; кусок eas.json тоже взят у автора, только env сокращён до одной переменной.

Пусть тестировщику нужна сборка preview на его iPhone, а preview у автора собирает iOS только для симулятора. Заводим профиль preview-device, который наследует preview и выключает симулятор. Прогноз: что получит iOS-сборка этого профиля? И что соберёт eas build --platform android, если забыть --profile?

type Env = Record<string, string>;
interface PlatformProfile {
  credentialsSource?: "local" | "remote";
  distribution?: "store" | "internal";
  developmentClient?: boolean;
  channel?: string;
  autoIncrement?: boolean;
  env?: Env;
  buildType?: "apk" | "app-bundle";
  simulator?: boolean;
}
interface BuildProfile extends PlatformProfile {
  extends?: string;
  android?: PlatformProfile;
  ios?: PlatformProfile;
}
type Platform = "android" | "ios";
type EasJson = { build: Record<string, BuildProfile> };

// @expo/eas-json 24 · build/build/resolver.js: слияние неглубокое, вглубь идут только env, android и ios
function mergeProfiles(base: BuildProfile, update: BuildProfile): BuildProfile {
  const result: BuildProfile = { ...base, ...update };
  if (base.env && update.env) result.env = { ...base.env, ...update.env };
  if (base.android && update.android) result.android = mergeProfiles(base.android, update.android);
  if (base.ios && update.ios) result.ios = mergeProfiles(base.ios, update.ios);
  return result;
}

function resolveProfile(easJson: EasJson, name: string, depth = 0): BuildProfile {
  if (depth >= 5) throw new Error("Too long chain of profile extensions, make sure \"extends\" keys do not make a cycle");
  const profile = easJson.build[name];
  if (!profile) throw new Error("Missing build profile in eas.json: \"" + name + "\"");
  const { extends: parent, ...rest } = profile;
  return parent ? mergeProfiles(resolveProfile(easJson, parent, depth + 1), rest) : rest;
}

// всё, что схема eas.json дописывает к пустому профилю
const defaults: BuildProfile = { credentialsSource: "remote", distribution: "store" };

function resolveBuildProfile(easJson: EasJson, platform: Platform, name = "production"): BuildProfile {
  const { android, ios, ...base } = resolveProfile(easJson, name);
  return mergeProfiles(defaults, mergeProfiles(base, (platform === "android" ? android : ios) ?? {}));
}

// eas.json автора, env сокращён до одного ключа, и новый профиль для iPhone тестировщика
const easJson: EasJson = {
  build: {
    development: { developmentClient: true, distribution: "internal", channel: "development", ios: { simulator: true } },
    preview: {
      distribution: "internal", channel: "preview", developmentClient: false,
      android: { buildType: "apk" }, ios: { simulator: true }, env: { EXPO_PUBLIC_API_URL: "https://example.com" },
    },
    production: {
      channel: "production", autoIncrement: true,
      android: { buildType: "app-bundle" }, ios: { simulator: false }, env: { EXPO_PUBLIC_API_URL: "https://example.com" },
    },
    "preview-device": { extends: "preview", ios: { simulator: false } },
  },
};

console.log(resolveBuildProfile(easJson, "ios", "preview-device"));
console.log(resolveBuildProfile(easJson, "android"));

preview-device получил от preview всё: канал, internal, выключенный dev client и env. Свою секцию ios он наложил на родительскую, после чего ключи android и ios исчезли: для iOS-сборки осталось одно плоское simulator: false. Эту же функцию мы прогнали на настоящем @expo/eas-json — вывод совпал ключ в ключ, вместе с порядком.

Вторая строка удивляет сильнее. Без --profile команда берёт production, так и написано в справке флага: «Defaults to "production" if defined in eas.json». distribution: "store" и credentialsSource: "remote" в файле автора не написаны нигде, их дописала схема eas.json. Значит, забытый флаг даёт сборку для магазина, и из-за autoIncrement она ещё и поднимает номер сборки.

И последнее о слиянии: оно неглубокое. Вглубь идут только env, android и ios. Любой другой объект наследник заменяет целиком: если переопределить cache.paths, пропадёт родительский cache.key. Цепочка extends ограничена пятью уровнями. Циклы отдельно не ищутся, их ловит тот же предел: профили, наследующие друг друга по кругу, дают «Too long chain of profile extensions, make sure "extends" keys do not make a cycle».

Профиль, где не написан distribution, собирается для магазина. Так решает схема eas.json, а не ваш файл.

На выходе у каждой платформы свой вопрос. На Android это формат пакета. APK ставится на телефон напрямую. AAB (Android App Bundle) — не установочный файл, а заготовка для Google Play: магазин сам нарезает из неё APK под каждое устройство. На iOS это подпись. Сборку для симулятора не подписывают вовсе, ad hoc встаёт только на заранее зарегистрированные iPhone, а подпись App Store принимают только TestFlight и сам магазин. Решает всё это профиль, и в eas-cli правила короткие:

// eas-cli 24.8.0 · build/build/android/prepareJob.js
let buildType = buildProfile.buildType;
if (!buildType && !buildProfile.gradleCommand && buildProfile.distribution === "internal") {
  buildType = Android.BuildType.APK;
}

// eas-cli 24.8.0 · build/build/ios/credentials.js: нужна ли iOS-сборке подпись
return !buildCtx.buildProfile.simulator && !buildCtx.buildProfile.withoutCredentials;

Если buildType не задан и раздача не internal, CLI не шлёт серверу ничего, и тот собирает app-bundle. Это поведение сервера, в исходнике CLI его нет. Разрешение профиля из прошлого примера лежит в подложке. Прогноз: какие файлы придут по четырём профилям для каждой платформы?

interface PlatformProfile {
  distribution?: "store" | "internal";
  developmentClient?: boolean;
  buildType?: "apk" | "app-bundle";
  simulator?: boolean;
}
type Platform = "android" | "ios";
// из подложки — разрешение профиля из прошлого примера и тот же eas.json
declare function resolveBuildProfile(easJson: object, platform: Platform, name?: string): PlatformProfile;
declare const easJson: { build: Record<string, object> };

// prepareJob в eas-cli 24 ставит apk для internal; без buildType сервер собирает app-bundle
function androidArtifact(profile: PlatformProfile): string {
  const type = profile.buildType ?? (profile.distribution === "internal" ? "apk" : "app-bundle");
  return type === "apk" ? ".apk" : ".aab";
}

// сборку для симулятора не подписывают, остальные подписывают под способ раздачи
function iosArtifact(profile: PlatformProfile): string {
  if (profile.simulator) return ".app для симулятора";
  return profile.distribution === "internal" ? ".ipa, подпись ad hoc" : ".ipa, подпись App Store";
}

for (const name of Object.keys(easJson.build)) {
  const android = resolveBuildProfile(easJson, "android", name);
  const ios = resolveBuildProfile(easJson, "ios", name);
  const debug = android.developmentClient ? " (Debug)" : "";
  console.log(name + debug + ": " + androidArtifact(android) + " · " + iosArtifact(ios));
}

Файлы для обоих магазинов даёт только production: .aab для Google Play и .ipa с подписью App Store. preview на Android ставится на любой телефон. На iOS тот же профиль собирает сборку только для симулятора — это ловушка из прошлой статьи, и она же объясняет, зачем нужен preview-device. Его .ipa подписана ad hoc и встанет только на iPhone, чей UDID зарегистрирован командой eas device:create до сборки. Сборка development — это Debug с лаунчером: наш dev client.

Как .apk, .app для симулятора и ad hoc .ipa попадают на устройство, разобрано в прошлой статье. Новые здесь две строки — файлы для магазинов, и вывод eas-cli для них устроен иначе. У сборки с distribution: "internal" printBuildInfo.js рисует QR-код и пишет «Open this link on your … devices (or scan the QR code) to install the app». У сборки для магазина QR-кода нет — только строка «🤖 Android app:» или «🍏 iOS app:» и ссылка на файл: ставить его на телефон не предполагается.

Сервер получает от вас две вещи: архив и окружение. Архив eas-cli собирает в два хода. Сначала неглубокий git clone без извлечения файлов. Потом поверх него копируется ваша рабочая папка — чтобы уехали и незакоммиченные правки, — но через фильтр: .git и node_modules не едут никогда, остальное отсекает .gitignore. Окружение сервера — это env профиля поверх переменных окружения EAS, которые хранятся у Expo и заводятся командой eas env:set. Если имя совпало, побеждает профиль: «The values from the build profile configuration will be used». Стандартных окружений у EAS три — development, preview и production (свои можно завести только на плане Enterprise), — и если в профиле нет поля environment, eas-cli выбирает его сам: distribution: "store" даёт production, dev client — development, всё остальное — preview. Это и есть первая строка вывода в начале статьи, «Resolved "production" environment». Окружение вашего терминала в задание сборки не кладётся вовсе: в prepareJob.js туда уходит только buildProfile.env.

Теперь вспомним app.config.js автора из статьи «Что Expo делает за вас». Firebase подключается только тогда, когда в окружении есть путь к файлу с ключами и сам файл на месте. Ключи в репозиторий не кладут, поэтому папка с ними стоит в .gitignore. На вашем Mac путь задан в терминале, и всё работает. В подложке — реестр и цепочка плагинов из прошлых статей, и плагин Firebase встаёт в тот же реестр со своей настоящей проверкой. Прогноз: что уедет в архиве и какие плагины применит prebuild на вашем Mac, на EAS и на EAS с конфигом, где проверки нет?

interface AppConfig {
  name: string;
  ios?: { googleServicesFile?: string; infoPlist?: Record<string, string> };
}
type ConfigPlugin = (config: AppConfig) => AppConfig;
type Env = Record<string, string | undefined>;
type Prebuild = [AppConfig, string[]];
// из подложки — реестр и цепочка плагинов из статьи «Что Expo делает за вас»
declare const registry: Record<string, ConfigPlugin>;
declare function withPlugins(config: AppConfig, plugins: string[]): AppConfig;

// @react-native-firebase/app 26 · plugin/build/ios/googleServicesPlist.js: без пути плагин бросает
registry["@react-native-firebase/app"] = (config) => {
  if (!config.ios?.googleServicesFile) {
    throw new Error("Path to GoogleService-Info.plist is not defined. Please specify the `expo.ios.googleServicesFile` field in app.json.");
  }
  return config;
};

// как makeShallowCopyAsync в eas-cli 24: .git и node_modules не едут никогда, остальное отсекает .gitignore
function upload(tree: string[], gitignore: string[]): Set<string> {
  const rules = [".git/", "node_modules/", ...gitignore];
  return new Set(tree.filter((file) => !rules.some((rule) => file.startsWith(rule))));
}

// app.config.js автора, сокращено: Firebase — только если путь есть в окружении и файл на месте
function careful(env: Env, files: Set<string>): Prebuild {
  const path = env.GOOGLE_SERVICES_PLIST;
  const has = path !== undefined && files.has(path);
  return [{ name: "Подход", ios: has ? { googleServicesFile: path } : {} }, ["expo-secure-store", ...(has ? ["@react-native-firebase/app"] : [])]];
}
// тот же конфиг без проверки: плагин в списке всегда
function naive(env: Env): Prebuild {
  return [{ name: "Подход", ios: { googleServicesFile: env.GOOGLE_SERVICES_PLIST } }, ["expo-secure-store", "@react-native-firebase/app"]];
}

function prebuild(where: string, [config, plugins]: Prebuild): void {
  try {
    withPlugins(config, plugins);
    console.log(where + ": " + plugins.join(", "));
  } catch (e) {
    console.log(where + ": " + (e as Error).message);
  }
}

const tree = ["app.config.js", "package.json", "src/app.tsx", "secrets/GoogleService-Info.plist", "node_modules/expo/package.json"];
const shell: Env = { GOOGLE_SERVICES_PLIST: "secrets/GoogleService-Info.plist" };
// на сервере — env профиля поверх переменных окружения EAS; окружение вашего терминала туда не едет
const server: Env = { EXPO_PUBLIC_API_URL: "https://example.com" };
const archive = upload(tree, ["secrets/", ".env.local"]);

console.log([...archive].join(", "));
prebuild("мой Mac", careful(shell, new Set(tree)));
prebuild("EAS", careful(server, archive));
prebuild("EAS, конфиг без проверки", naive(server));

На EAS сборка прошла и Firebase не подключила: в окружении сервера нет пути, в архиве нет файла, и осторожный конфиг честно выбросил плагин. Ошибок нет, журнал зелёный, аналитики в приложении нет. Конфиг без проверки падает громко, уже на prebuild на сервере, и текст ошибки — дословно тот, что бросает @react-native-firebase/app. Осторожность автора спасает сборку, но расплачивается тишиной. Тот же вопрос стоит к каждому process.env в конфиге: у автора так же читаются EAS_PROJECT_ID и EAS_OWNER, и если они есть только в вашем терминале, в облаке конфиг вычислится без них.

Файлы с ключами передают переменной окружения EAS типа file. Файл хранится у Expo, а переменная содержит путь к нему — ровно то, чего ждёт конфиг автора. Так же этот тип понимает eas env:pull: такие файлы он кладёт локально в .eas/.env/.

$ eas env:set --name GOOGLE_SERVICES_PLIST --type file --value ./secrets/GoogleService-Info.plist --environment production

Переменные с префиксом EXPO_PUBLIC_ Metro вшивает в бандл при сборке, как NEXT_PUBLIC_ в статье «Стили, сборка и выкладка» части IV. Поэтому EXPO_PUBLIC_API_URL: "https://example.com" в профилях автора — это адрес, который окажется в приложении у пользователей, пока его не заменят. А секретам в таких переменных не место: бандл лежит внутри .ipa и .apk, и достать его может любой.

Последняя ловушка архива — файл .easignore. Его заводят, чтобы архив похудел: CLI сам советует это сделать, когда архив больше 150 МБ, а больше 2 ГБ не примет вовсе. Но в vcs/local.js eas-cli правило записано прямым текстом: «if .easignore exists, .gitignore files are not used». Появился .easignore — и ни один .gitignore, ни корневой, ни во вложенных папках, больше не читается. На этом стоит первая задача к статье.

Сборку, которую ставят на телефон, нужно подписать. Раньше это требовало Keychain и Xcode, в EAS хватает ответов на вопросы в терминале. По умолчанию credentialsSource: "remote": ключи живут на серверах Expo, и CLI сообщает об этом строкой «Using remote Android credentials (Expo server)». При первой сборке для Android ключа ещё нет, и eas-cli спрашивает «Generate a new Android Keystore?». Согласие — и ключ создан и сохранён у Expo: «Created keystore». Для Google Play этот keystore — ключ загрузки: им подписан каждый .aab, и консоль принимает сборки только с ним. На телефоны Google Play отдаёт APK со своей подписью (Play App Signing), поэтому потерянный ключ загрузки заменить можно, но только запросом на сброс в Play Console. А там, где файл отдают как есть, — в RuStore и при установке .apk напрямую, — keystore и есть подпись приложения, и обновление с другой подписью поверх не встанет; к этому вернётся статья «Магазины». Поэтому копию стоит скачать командой eas credentials и хранить отдельно от репозитория.

С iOS шагов больше, но Mac не нужен и здесь. Нужен платный аккаунт в Apple Developer Program: без него не выпустить ни ad hoc, ни App Store. eas-cli сам входит в аккаунт Apple и через API Apple создаёт сертификат распространения и профиль подписи. Фрагмент первой сборки:

$ eas build --platform ios --profile production

Следующие сборки берут готовое. Сборкам для симулятора ничего из этого не нужно: проверка из секции «Какой файл придёт» пропускает подпись, если стоит simulator. Поэтому профили development и preview автора собираются для iOS и без аккаунта Apple.

Вторая забота — номер. У приложения их два. version из конфига (1.0.0) видит пользователь; на iOS это CFBundleShortVersionString, на Android — versionName. Номер сборки — versionCode на Android и CFBundleVersion на iOS — видят магазины, и каждая загрузка обязана нести новый. Где хранится номер сборки, решает cli.appVersionSource. У автора стоит "remote": номер лежит на серверах EAS и подставляется в проект только во время сборки. Так в объяснении и сказано: «remotely on EAS servers and only applied to the project at build time». Вместе с autoIncrement в профиле production каждая сборка поднимает его на единицу — строка «Incremented versionCode from 1 to 2» в самом первом выводе статьи. Без appVersionSource CLI предупреждает, что поле скоро станет обязательным, а начальный номер задаёт eas build:version:set.

Итог: eas build --platform all --profile production с любой машины — хоть с Windows, хоть с Linux — ставит в очередь две сборки. На выходе .aab для Google Play и .ipa для App Store, подписанные ключами, которые хранит EAS, и с номерами, которые ведёт EAS. Прежде чем отправлять их в магазины, нужно довести до ума то, что пользователь увидит первым: иконку, сплэш и имя. Этому посвящена следующая статья.

Скачайте копию keystore командой eas credentials и храните её вне репозитория: для Google Play это ключ загрузки, а для RuStore и .apk напрямую — подпись самого приложения.