Perfis e Flavors de Build

Q: Desenvolvimento e produção podem ser instalados no mesmo telefone?

Sim, se bundleIdentifier / package forem diferentes - use sufixos APP_VARIANT como .dev e .staging. Não, se eles compartilharem o mesmo ID - a nova instalação substitui o aplicativo antigo.

Q: Quantos perfis devemos ter?

Comece com três: development, preview, production. Adicione perfis específicos de marca ou plataforma com extends quando necessário. Evite perfis nomeados por engenheiros ("jane-debug") - use ambientes e canais em vez disso.

Q: O preview deve usar distribuição store ou internal?

internal para APK/ad hoc e iteração rápida. store + TestFlight interno quando o QA precisar de assinatura idêntica à de produção - Distribuição TestFlight.

Q: Como aplicativos white-label compartilham um repositório?

Código-base único + env BRAND + credenciais separadas por nome de pacote. Projetos EAS separados ou isolamento rigoroso de canal por marca. Documente qual perfil mapeia para qual aplicativo Play Console / App Store Connect.

Variantes de desenvolvimento, preview, produção e white-label - o guia para estruturar perfis do eas.json e app.config.ts dinâmico no Expo SDK 57.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// eas.json - base de três ambientes
{
  "cli": { "version": ">= 16.0.0", "appVersionSource": "remote" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "environment": "development",
      "channel": "development"
    },
    "preview": {
      "distribution": "internal",
      "environment": "preview",
      "channel": "preview"
    },
    "production": {
      "distribution": "store",
      "environment": "production",
      "channel": "production",
      "autoIncrement": true
    }
  }
}

// app.config.ts - APP_VARIANT do env do eas.json
import type { ExpoConfig } from "expo/config";
 
const variant = process.env.APP_VARIANT ?? "production";
 
const bundleIds: Record<string, string> = {
  development: "com.example.shopapp.dev",
  preview: "com.example.shopapp.staging",
  production: "com.example.shopapp",
};
 
const config: ExpoConfig = {
  name: variant === "production" ? "Shop" : `Shop (${variant})`,
  slug: "shop-app",
  ios: { bundleIdentifier: bundleIds[variant] },
  android: { package: bundleIds[variant] },
  extra: {
    apiUrl: process.env.EXPO_PUBLIC_API_URL,
    eas: { projectId: "00000000-0000-0000-0000-000000000000" },
  },
};
 
export default config;

// eas.json - passa a variante para o prebuild
{
  "build": {
    "preview": {
      "env": { "APP_VARIANT": "preview" },
      "environment": "preview"
    }
  }
}

Quando usar isso:

Staging e produção precisam ser instalados lado a lado no mesmo dispositivo.
Marcas white-label compartilham uma base de código com ícones e IDs de bundle diferentes.
QA precisa de URLs de API de preview sem arriscar dados de produção.
Canais do EAS Update não devem cruzar ambientes.

Exemplo de Trabalho

Passo 1 - Defina as responsabilidades do perfil

Perfil	Público	Distribuição	Binário Típico
development	Engenheiros	internal	Cliente Dev + simulador/APK
preview	QA / stakeholders	internal	IPA/APK com formato de release
production	Usuários Finais	store	AAB + App Store IPA

eas build --profile development --platform all
eas build --profile preview --platform ios
eas build --profile production --platform android

Passo 2 - Vincule ambientes EAS

Crie variáveis no painel Expo → Project → Environment variables:

development   EXPO_PUBLIC_API_URL=https://api.dev.example.com
preview       EXPO_PUBLIC_API_URL=https://api.staging.example.com
production    EXPO_PUBLIC_API_URL=https://api.example.com

{
  "build": {
    "preview": { "environment": "preview" }
  }
}

environment puxa variáveis do EAS - não do .env.local do laptop
eas update --environment production deve corresponder ao perfil de produção - Regras de Release e OTA

Passo 3 - White-label com app.config.ts

// app.config.ts - multi-marca a partir do env BRAND
type Brand = "acme" | "contoso";
 
const brand = (process.env.BRAND ?? "acme") as Brand;
 
const brands: Record<Brand, { name: string; bundleId: string; icon: string }> = {
  acme: {
    name: "Acme Shop",
    bundleId: "com.acme.shop",
    icon: "./brands/acme/icon.png",
  },
  contoso: {
    name: "Contoso Market",
    bundleId: "com.contoso.market",
    icon: "./brands/contoso/icon.png",
  },
};
 
const config: ExpoConfig = {
  name: brands[brand].name,
  slug: `shop-${brand}`,
  icon: brands[brand].icon,
  ios: { bundleIdentifier: brands[brand].bundleId },
  android: {
    package: brands[brand].bundleId,
    adaptiveIcon: { foregroundImage: brands[brand].icon, backgroundColor: "#fff" },
  },
};
 
export default config;

// eas.json - um perfil por marca para produção
{
  "build": {
    "production-acme": {
      "extends": "production",
      "env": { "BRAND": "acme" },
      "environment": "production-acme"
    },
    "production-contoso": {
      "extends": "production",
      "env": { "BRAND": "contoso" },
      "environment": "production-contoso"
    }
  }
}

eas build --profile production-acme --platform all
eas build --profile production-contoso --platform all

Cada marca precisa de um projectId separado ou isolamento rigoroso de canal por ID de bundle
Certificados iOS e keystores Android separados para cada bundleIdentifier / package

Herança de Perfis com extends

DRY configurações compartilhadas entre perfis:

{
  "build": {
    "base": {
      "node": "22.11.0",
      "resourceClass": "medium"
    },
    "development": {
      "extends": "base",
      "developmentClient": true,
      "distribution": "internal"
    },
    "production": {
      "extends": "base",
      "distribution": "store",
      "autoIncrement": true
    },
    "production-ios-simulator": {
      "extends": "production",
      "ios": { "simulator": true },
      "distribution": "internal"
    }
  }
}

extends mescla chaves pai - as do filho têm precedência
Use para builds de simulador Detox, CI Maestro e pins de versão Node compartilhados

Perfis vs. Flavors de Produto Android

O Expo CNG geralmente usa um único Gradle applicationId por prebuild, controlado por app.config.ts:

eas.json profile  →  APP_VARIANT env  →  app.config.ts  →  applicationId

Flavors de produto nativos do Android em build.gradle são possíveis em projetos brownfield, mas entram em conflito com a regeneração do CNG. Prefira:

app.config.ts dinâmico para ID do bundle, nome e ícones
Perfis EAS separados por variante
Plugins de configuração para recursos nativos específicos de flavor, se inevitável

Veja Noções Básicas de Prebuild - flavors de produto android/app/build.gradle editados manualmente são perdidos em um prebuild limpo.

Alinhamento de Canal e Runtime

// app.config.ts
runtimeVersion: {
  policy: "fingerprint",
},
updates: {
  url: "https://u.expo.dev/<project-id>",
},

{
  "build": {
    "preview": { "channel": "preview" },
    "production": { "channel": "production" }
  }
}

eas update --channel preview --environment preview --message "Correção de QA"
eas update --channel production --environment production --message "Hotfix"

O canal no binário deve corresponder ao canal no eas update
Diferentes flavors com diferentes impressões digitais nativas precisam de versões de runtime diferentes

FAQs

Desenvolvimento e produção podem ser instalados no mesmo telefone?

Sim, se bundleIdentifier / package forem diferentes - use sufixos APP_VARIANT como .dev e .staging.
Não, se eles compartilharem o mesmo ID - a nova instalação substitui o aplicativo antigo.

Quantos perfis devemos ter?

Comece com três: development, preview, production.
Adicione perfis específicos de marca ou plataforma com extends quando necessário.
Evite perfis nomeados por engenheiros ("jane-debug") - use ambientes e canais em vez disso.

O preview deve usar distribuição store ou internal?

internal para APK/ad hoc e iteração rápida.
store + TestFlight interno quando o QA precisar de assinatura idêntica à de produção - Distribuição TestFlight.

Como aplicativos white-label compartilham um repositório?

Código-base único + env BRAND + credenciais separadas por nome de pacote.
Projetos EAS separados ou isolamento rigoroso de canal por marca.
Documente qual perfil mapeia para qual aplicativo Play Console / App Store Connect.

Relacionados

Noções Básicas do EAS Build - fundamentos de perfil
Credenciais e Provisionamento iOS - assinatura por ID de bundle
Keystores e Assinatura Android - keystores por pacote
Distribuição Interna - mecânica de instalação preview
../cng-prebuild/prebuild-basics/prebuild-basics.md - app.config controla IDs nativos
../cng-prebuild/config-plugins-in-cng/config-plugins-in-cng.md - mutações nativas específicas de flavor
../ios-platform/ios-basics-for-rn-devs/ios-basics-for-rn-devs.md - regras de ID de bundle
../android-platform/android-basics-for-rn-devs/android-basics-for-rn-devs.md - applicationId vs namespace
../expo-rules/release-and-ota-rules/release-and-ota-rules.md - política de canal e runtime

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// eas.json - base de três ambientes
{
  "cli": { "version": ">= 16.0.0", "appVersionSource": "remote" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "environment": "development",
      "channel": "development"
    },
    "preview": {
      "distribution": "internal",
      "environment": "preview",
      "channel": "preview"
    },
    "production": {
      "distribution": "store",
      "environment": "production",
      "channel": "production",
      "autoIncrement": true
    }
  }
}

// app.config.ts - APP_VARIANT do env do eas.json
import type { ExpoConfig } from "expo/config";
 
const variant = process.env.APP_VARIANT ?? "production";
 
const bundleIds: Record<string, string> = {
  development: "com.example.shopapp.dev",
  preview: "com.example.shopapp.staging",
  production: "com.example.shopapp",
};
 
const config: ExpoConfig = {
  name: variant === "production" ? "Shop" : `Shop (${variant})`,
  slug: "shop-app",
  ios: { bundleIdentifier: bundleIds[variant] },
  android: { package: bundleIds[variant] },
  extra: {
    apiUrl: process.env.EXPO_PUBLIC_API_URL,
    eas: { projectId: "00000000-0000-0000-0000-000000000000" },
  },
};
 
export default config;

// eas.json - passa a variante para o prebuild
{
  "build": {
    "preview": {
      "env": { "APP_VARIANT": "preview" },
      "environment": "preview"
    }
  }
}

Quando usar isso:

Staging e produção precisam ser instalados lado a lado no mesmo dispositivo.
Marcas white-label compartilham uma base de código com ícones e IDs de bundle diferentes.
QA precisa de URLs de API de preview sem arriscar dados de produção.
Canais do EAS Update não devem cruzar ambientes.

Exemplo de Trabalho

Passo 1 - Defina as responsabilidades do perfil

Perfil	Público	Distribuição	Binário Típico
development	Engenheiros	internal	Cliente Dev + simulador/APK
preview	QA / stakeholders	internal	IPA/APK com formato de release
production	Usuários Finais	store	AAB + App Store IPA

eas build --profile development --platform all
eas build --profile preview --platform ios
eas build --profile production --platform android

Passo 2 - Vincule ambientes EAS

Crie variáveis no painel Expo → Project → Environment variables:

development   EXPO_PUBLIC_API_URL=https://api.dev.example.com
preview       EXPO_PUBLIC_API_URL=https://api.staging.example.com
production    EXPO_PUBLIC_API_URL=https://api.example.com

{
  "build": {
    "preview": { "environment": "preview" }
  }
}

environment puxa variáveis do EAS - não do .env.local do laptop
eas update --environment production deve corresponder ao perfil de produção - Regras de Release e OTA

Passo 3 - White-label com app.config.ts

// app.config.ts - multi-marca a partir do env BRAND
type Brand = "acme" | "contoso";
 
const brand = (process.env.BRAND ?? "acme") as Brand;
 
const brands: Record<Brand, { name: string; bundleId: string; icon: string }> = {
  acme: {
    name: "Acme Shop",
    bundleId: "com.acme.shop",
    icon: "./brands/acme/icon.png",
  },
  contoso: {
    name: "Contoso Market",
    bundleId: "com.contoso.market",
    icon: "./brands/contoso/icon.png",
  },
};
 
const config: ExpoConfig = {
  name: brands[brand].name,
  slug: `shop-${brand}`,
  icon: brands[brand].icon,
  ios: { bundleIdentifier: brands[brand].bundleId },
  android: {
    package: brands[brand].bundleId,
    adaptiveIcon: { foregroundImage: brands[brand].icon, backgroundColor: "#fff" },
  },
};
 
export default config;

// eas.json - um perfil por marca para produção
{
  "build": {
    "production-acme": {
      "extends": "production",
      "env": { "BRAND": "acme" },
      "environment": "production-acme"
    },
    "production-contoso": {
      "extends": "production",
      "env": { "BRAND": "contoso" },
      "environment": "production-contoso"
    }
  }
}

eas build --profile production-acme --platform all
eas build --profile production-contoso --platform all

Cada marca precisa de um projectId separado ou isolamento rigoroso de canal por ID de bundle
Certificados iOS e keystores Android separados para cada bundleIdentifier / package

Herança de Perfis com extends

DRY configurações compartilhadas entre perfis:

{
  "build": {
    "base": {
      "node": "22.11.0",
      "resourceClass": "medium"
    },
    "development": {
      "extends": "base",
      "developmentClient": true,
      "distribution": "internal"
    },
    "production": {
      "extends": "base",
      "distribution": "store",
      "autoIncrement": true
    },
    "production-ios-simulator": {
      "extends": "production",
      "ios": { "simulator": true },
      "distribution": "internal"
    }
  }
}

extends mescla chaves pai - as do filho têm precedência
Use para builds de simulador Detox, CI Maestro e pins de versão Node compartilhados

Perfis vs. Flavors de Produto Android

O Expo CNG geralmente usa um único Gradle applicationId por prebuild, controlado por app.config.ts:

eas.json profile  →  APP_VARIANT env  →  app.config.ts  →  applicationId

Flavors de produto nativos do Android em build.gradle são possíveis em projetos brownfield, mas entram em conflito com a regeneração do CNG. Prefira:

app.config.ts dinâmico para ID do bundle, nome e ícones
Perfis EAS separados por variante
Plugins de configuração para recursos nativos específicos de flavor, se inevitável

Veja Noções Básicas de Prebuild - flavors de produto android/app/build.gradle editados manualmente são perdidos em um prebuild limpo.

Alinhamento de Canal e Runtime

// app.config.ts
runtimeVersion: {
  policy: "fingerprint",
},
updates: {
  url: "https://u.expo.dev/<project-id>",
},

{
  "build": {
    "preview": { "channel": "preview" },
    "production": { "channel": "production" }
  }
}

eas update --channel preview --environment preview --message "Correção de QA"
eas update --channel production --environment production --message "Hotfix"

O canal no binário deve corresponder ao canal no eas update
Diferentes flavors com diferentes impressões digitais nativas precisam de versões de runtime diferentes

FAQs

Desenvolvimento e produção podem ser instalados no mesmo telefone?

Sim, se bundleIdentifier / package forem diferentes - use sufixos APP_VARIANT como .dev e .staging.
Não, se eles compartilharem o mesmo ID - a nova instalação substitui o aplicativo antigo.

Quantos perfis devemos ter?

Comece com três: development, preview, production.
Adicione perfis específicos de marca ou plataforma com extends quando necessário.
Evite perfis nomeados por engenheiros ("jane-debug") - use ambientes e canais em vez disso.

O preview deve usar distribuição store ou internal?

internal para APK/ad hoc e iteração rápida.
store + TestFlight interno quando o QA precisar de assinatura idêntica à de produção - Distribuição TestFlight.

Como aplicativos white-label compartilham um repositório?

Código-base único + env BRAND + credenciais separadas por nome de pacote.
Projetos EAS separados ou isolamento rigoroso de canal por marca.
Documente qual perfil mapeia para qual aplicativo Play Console / App Store Connect.

Relacionados

Noções Básicas do EAS Build - fundamentos de perfil
Credenciais e Provisionamento iOS - assinatura por ID de bundle
Keystores e Assinatura Android - keystores por pacote
Distribuição Interna - mecânica de instalação preview
../cng-prebuild/prebuild-basics/prebuild-basics.md - app.config controla IDs nativos
../cng-prebuild/config-plugins-in-cng/config-plugins-in-cng.md - mutações nativas específicas de flavor
../ios-platform/ios-basics-for-rn-devs/ios-basics-for-rn-devs.md - regras de ID de bundle
../android-platform/android-basics-for-rn-devs/android-basics-for-rn-devs.md - applicationId vs namespace
../expo-rules/release-and-ota-rules/release-and-ota-rules.md - política de canal e runtime

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Perfis e Flavors de Build

Buscar na documentação

Perfis e Flavors de Build