Ambientes & Variáveis de Ambiente do EAS

Separe a configuração de desenvolvimento, staging e produção sem confirmar segredos - usando arquivos .env locais para desenvolvimento e variáveis de ambiente do EAS para builds na nuvem, atualizações e fluxos de trabalho.

Receita

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

// eas.json - conecte cada perfil de build a um ambiente EAS
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "environment": "development"
    },
    "preview": {
      "distribution": "internal",
      "environment": "preview"
    },
    "production": {
      "distribution": "store",
      "environment": "production"
    }
  }
}

# Crie variáveis na nuvem (repita por ambiente)
eas env:create --name EXPO_PUBLIC_API_URL \
  --value https://api.staging.example.com \
  --environment preview \
  --visibility plaintext
 
# Puxe variáveis de preview localmente (escreve .env.local - mantenha no gitignore)
eas env:pull --environment preview
 
# Publique uma atualização OTA usando o mesmo ambiente do build
eas update --environment production --message "Correção de redirecionamento de autenticação"

// src/config.ts - apenas variáveis EXPO_PUBLIC_ são incorporadas ao bundle
export const config = {
  apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000",
  appEnv: process.env.EXPO_PUBLIC_APP_ENV ?? "development",
} as const;

Quando usar isso:

• Você envia múltiplas variantes do aplicativo (cliente de desenvolvimento, QA interno, App Store) que precisam de endpoints de API ou identificadores de bundle diferentes.
• Sua equipe executa EAS Build ou EAS Update e não pode depender de arquivos .env locais não confirmados em executores remotos.
• Você precisa de visibilidade baseada em função - texto simples para configuração pública, sensível para logs ofuscados, segredo para tokens NPM e chaves de assinatura.
• Você quer uma única fonte de verdade para que um build de preview e uma atualização OTA de preview resolvam os mesmos valores EXPO_PUBLIC_*.

Exemplo de Trabalho

// app.config.ts - ramifique a configuração nativa por ambiente sem codificar segredos
import type { ExpoConfig } from "expo/config";
 
const APP_ENV = process.env.EXPO_PUBLIC_APP_ENV ?? "development";
 
const bundleIds: Record<string, string> = {
  development: "com.example.myapp.dev",
  preview: "com.example.myapp.staging",
  production: "com.example.myapp",
};
 
const apiUrls: Record<string, string> = {
  development: "http://localhost:3000",
  preview: "https://api.staging.example.com",
  production: "https://api.example.com",
};
 
const config: ExpoConfig = {
  name: APP_ENV === "production" ? "Meu App" : `Meu App (${APP_ENV})`,
  slug: "my-app",
  version: "1.0.0",
  ios: {
    bundleIdentifier: bundleIds[APP_ENV] ?? bundleIds.development,
  },
  android: {
    package: bundleIds[APP_ENV] ?? bundleIds.development,
  },
  extra: {
    appEnv: APP_ENV,
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? apiUrls[APP_ENV],
    eas: {
      projectId: "00000000-0000-0000-0000-000000000000",
    },
  },
};
 
export default config;

// App.tsx - leia a configuração em tempo de execução de variáveis públicas incorporadas e o campo extra de app.config
import Constants from "expo-constants";
import { StyleSheet, Text, View } from "react-native";
 
export default function App() {
  const apiUrl =
    process.env.EXPO_PUBLIC_API_URL ??
    (Constants.expoConfig?.extra?.apiUrl as string | undefined) ??
    "não configurado";
 
  const appEnv =
    process.env.EXPO_PUBLIC_APP_ENV ??
    (Constants.expoConfig?.extra?.appEnv as string | undefined) ??
    "desconhecido";
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Ambiente: {appEnv}</Text>
      <Text style={styles.body}>API: {apiUrl}</Text>
      <Text style={styles.hint}>
        Builds do EAS injetam EXPO_PUBLIC_* no momento do bundle. Segredos nunca aparecem aqui.
      </Text>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 20, fontWeight: "700" },
  body: { fontSize: 15, color: "#374151" },
  hint: { fontSize: 13, color: "#6b7280", marginTop: 12 },
});

# .gitignore - nunca confirme substituições locais ou segredos puxados
.env*.local

O que isso demonstra:

• Mapeamento de ambientes EAS (development, preview, production) para perfis de build do eas.json.
• Uso de EXPO_PUBLIC_* para valores seguros para o cliente que o Metro incorpora em tempo de bundle.
• Manutenção de identificadores de bundle e nomes de exibição específicos do ambiente via app.config.ts.
• Separação de segredos em tempo de build (tokens NPM, chaves de assinatura) de qualquer coisa referenciada em JavaScript.

Mergulho Profundo

Como Funciona

• Desenvolvimento local: O Expo CLI carrega .env, .env.local e outros arquivos dotenv padrão. Variáveis prefixadas com EXPO_PUBLIC_ são substituídas estaticamente em seu código durante o bundling.
• EAS Build: Quando environment é definido em um perfil de build, o EAS injeta as variáveis desse ambiente no worker de build. Variáveis de texto simples e sensíveis estão disponíveis ao resolver app.config.ts; variáveis secretas estão disponíveis apenas no servidor durante o trabalho.
• EAS Update (SDK 55+): eas update --environment <nome> é obrigatório. Apenas variáveis desse ambiente EAS são usadas - arquivos .env locais são ignorados, mantendo os bundles OTA alinhados com os builds da loja.
• Escopo: Variáveis podem ser para todo o projeto (um app) ou para toda a conta (compartilhadas entre apps em uma organização).

Mapeamento de Ambientes EAS

Campos environment explícitos são recomendados - a detecção automática é conveniente, mas fácil de configurar incorretamente quando os perfis compartilham sinalizadores semelhantes.

Configurações de Visibilidade

Qualquer coisa incorporada em JavaScript do cliente é extraível do aplicativo compilado. Use segredos para NPM_TOKEN, SENTRY_AUTH_TOKEN e valores semelhantes em tempo de build - não para chaves de API "privadas" enviadas aos usuários.

Variáveis de Build EAS Integradas

Estas são definidas automaticamente nos workers do EAS Build (não fazem parte dos seus ambientes de projeto):

Use EAS_BUILD_PROFILE em app.config.ts quando precisar de lógica específica do perfil além dos três ambientes padrão.

Notas de TypeScript

// env.d.ts - documente as variáveis públicas esperadas para a equipe
declare namespace NodeJS {
  interface ProcessEnv {
    EXPO_PUBLIC_API_URL: string;
    EXPO_PUBLIC_APP_ENV: "development" | "preview" | "production";
  }
}
 
// Acesso estático apenas - o Metro NÃO incorporará notação de colchetes ou desestruturação
const url = process.env.EXPO_PUBLIC_API_URL; // ✓ incorporado
// const url = process.env["EXPO_PUBLIC_API_URL"]; // ✗ não incorporado

Armadilhas

• Colocar segredos de API em EXPO_PUBLIC_* - Qualquer valor incorporado em JavaScript é visível no binário do aplicativo. Correção: Mantenha os segredos no lado do servidor; use tokens de curta duração do seu backend.
• Omitir --environment em eas update (SDK 55+) - As atualizações podem não corresponder às variáveis usadas no seu build de produção. Correção: Sempre passe --environment correspondendo ao perfil de build de destino.
• Usar NODE_ENV para alternar arquivos .env - npx expo export força NODE_ENV=production, portanto, arquivos de teste/staging não serão carregados como esperado. Correção: Use eas env:pull --environment <nome> ou EXPO_PUBLIC_APP_ENV explícito.
• Notação de colchetes para variáveis de ambiente - process.env['EXPO_PUBLIC_KEY'] não é analisável estaticamente e não será incorporado. Correção: Use notação de ponto: process.env.EXPO_PUBLIC_KEY.
• Assumir que segredos estão disponíveis em app.config.ts localmente - Variáveis do tipo segredo são ilegíveis fora dos servidores EAS. Correção: Use texto simples/sensível para valores necessários durante a resolução de configuração local, ou forneça padrões de desenvolvimento.
• Confirmar .env.local após eas env:pull - Arquivos puxados frequentemente contêm valores de staging/produção. Correção: Adicione .env*.local ao .gitignore e use comandos de pull separados por máquina de desenvolvedor.
• Ambientes inconsistentes entre trabalhos de fluxo de trabalho - Um trabalho de impressão digital em production emparelhado com um build de preview causa segredos incorretos. Correção: Defina jobs.<id>.environment para corresponder ao ambiente do perfil de build nos Fluxos de Trabalho EAS.

Alternativas

FAQs

{
  "build": {
    "production": {
      "environment": "production"
    }
  }
}

eas env:pull --environment development

eas env:exec --environment production 'npx sentry-expo-upload-sourcemaps dist'

Relacionados

• app.json & app.config.js - configuração dinâmica, plugins e manifestos multientorno
• Noções Básicas da Plataforma Expo - ramificação APP_VARIANT e vinculação de projetos EAS
• Expo Go vs. Builds de Desenvolvimento - perfil de desenvolvimento e configuração do cliente de desenvolvimento
• Atualizando Versões do SDK do Expo - mudanças no comportamento das variáveis de ambiente entre atualizações de SDK
• Conta, Projetos e Permissões do Expo - variáveis de escopo de organização e acesso a funções
• Melhores Práticas - higiene de segredos e governança de configuração de longo prazo

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).