Entornos y variables de entorno de EAS

Separa la configuración de desarrollo, staging y producción sin confirmar secretos, usando archivos .env locales para desarrollo y variables de entorno de EAS para compilaciones en la nube, actualizaciones y flujos de trabajo.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

// eas.json - conecta cada perfil de compilación a un entorno de EAS
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "environment": "development"
    },
    "preview": {
      "distribution": "internal",
      "environment": "preview"
    },
    "production": {
      "distribution": "store",
      "environment": "production"
    }
  }
}

# Crear variables en la nube (repite por entorno)
eas env:create --name EXPO_PUBLIC_API_URL \
  --value https://api.staging.example.com \
  --environment preview \
  --visibility plaintext
 
# Extrae variables de preview localmente (escribe .env.local - mantenlo ignorado por git)
eas env:pull --environment preview
 
# Publica una actualización de OTA usando el mismo entorno que la compilación
eas update --environment production --message "Hotfix auth redirect"

// src/config.ts - solo las variables EXPO_PUBLIC_ se insertan en el bundle
export const config = {
  apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000",
  appEnv: process.env.EXPO_PUBLIC_APP_ENV ?? "development",
} as const;

Cuándo usarlo:

• Envías múltiples variantes de aplicación (cliente de dev, QA interno, App Store) que necesitan diferentes puntos finales de API o identificadores de paquete.
• Tu equipo ejecuta EAS Build o EAS Update y no puede confiar en archivos .env locales sin confirmar en ejecutores remotos.
• Necesitas visibilidad basada en roles - texto plano para configuración pública, sensible para registros ofuscados, secreto para tokens NPM y claves de firma.
• Deseas una única fuente de verdad para que una compilación de preview y una actualización de OTA de preview resuelvan los mismos valores EXPO_PUBLIC_*.

Ejemplo de trabajo

// app.config.ts - rama configuración nativa por entorno sin hardcodear secretos
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" ? "My App" : `My 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 - lee configuración en tiempo de ejecución desde variables públicas insertadas y 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) ??
    "not configured";
 
  const appEnv =
    process.env.EXPO_PUBLIC_APP_ENV ??
    (Constants.expoConfig?.extra?.appEnv as string | undefined) ??
    "unknown";
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Entorno: {appEnv}</Text>
      <Text style={styles.body}>API: {apiUrl}</Text>
      <Text style={styles.hint}>
        Las compilaciones de EAS inyectan EXPO_PUBLIC_* en tiempo de bundle. Los secretos nunca aparecen aquí.
      </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 confirmes valores locales sobrescritos o secretos extraídos
.env*.local

Lo que esto demuestra:

• Asignación de entornos de EAS (development, preview, production) a perfiles de compilación en eas.json.
• Uso de EXPO_PUBLIC_* para valores seguros para clientes que Metro inserta en tiempo de bundle.
• Mantención de identificadores de paquete y nombres de visualización específicos del entorno a través de app.config.ts.
• Separación de secretos en tiempo de compilación (tokens NPM, claves de firma) de cualquier cosa referenciada en JavaScript.

Análisis profundo

Cómo funciona

• Desarrollo local: Expo CLI carga .env, .env.local y otros archivos dotenv estándar. Las variables con prefijo EXPO_PUBLIC_ se reemplazan estáticamente en tu fuente durante la compilación.
• EAS Build: Cuando se establece environment en un perfil de compilación, EAS inyecta las variables de ese entorno en el worker de compilación. Las variables de texto plano y sensibles están disponibles al resolver app.config.ts; las variables secretas están disponibles solo en el servidor durante el job.
• EAS Update (SDK 55+): eas update --environment <name> es obligatorio. Solo se utilizan variables de ese entorno de EAS - los archivos .env locales se ignoran, manteniendo bundles de OTA alineados con compilaciones de tienda.
• Alcance: Las variables pueden ser amplias a nivel de proyecto (una aplicación) o amplias a nivel de cuenta (compartidas entre aplicaciones en una organización).

Asignación de entornos de EAS

Se recomiendan campos environment explícitos - la detección automática es conveniente pero fácil de mal configurar cuando los perfiles comparten banderas similares.

Configuración de visibilidad

Cualquier cosa insertada en JavaScript del cliente es extraíble del código de aplicación compilada. Usa secretos para NPM_TOKEN, SENTRY_AUTH_TOKEN y valores similares en tiempo de compilación - no para claves API "privadas" enviadas a usuarios.

Variables de compilación de EAS incorporadas

Se establecen automáticamente en workers de EAS Build (no forman parte de tus entornos de proyecto):

Usa EAS_BUILD_PROFILE en app.config.ts cuando necesites lógica específica del perfil más allá de los tres entornos estándar.

Notas de TypeScript

// env.d.ts - documenta variables públicas esperadas para el equipo
declare namespace NodeJS {
  interface ProcessEnv {
    EXPO_PUBLIC_API_URL: string;
    EXPO_PUBLIC_APP_ENV: "development" | "preview" | "production";
  }
}
 
// Acceso estático solo - Metro NO insertará notación de corchetes o destructuración
const url = process.env.EXPO_PUBLIC_API_URL; // ✓ insertado
// const url = process.env["EXPO_PUBLIC_API_URL"]; // ✗ no insertado

Errores comunes

• Poner secretos de API en EXPO_PUBLIC_* - Cualquier valor insertado en JavaScript es visible en el binario de la aplicación. Solución: Mantén secretos del lado del servidor; usa tokens de corta duración de tu backend.
• Omitir --environment en eas update (SDK 55+) - Las actualizaciones pueden no coincidir con las variables utilizadas en tu compilación de producción. Solución: Siempre pasa --environment que coincida con el perfil de compilación de destino.
• Usar NODE_ENV para cambiar archivos .env - npx expo export fuerza NODE_ENV=production, por lo que los archivos de prueba/staging no se cargarán como se esperaba. Solución: Usa eas env:pull --environment <name> o EXPO_PUBLIC_APP_ENV explícito.
• Notación de corchetes para variables de entorno - process.env['EXPO_PUBLIC_KEY'] no es analizable estáticamente y no se insertará. Solución: Usa notación de punto: process.env.EXPO_PUBLIC_KEY.
• Asumir que los secretos están disponibles en app.config.ts localmente - Las variables de tipo secreto no se pueden leer fuera de servidores de EAS. Solución: Usa sensible/texto plano para valores necesarios durante la resolución de configuración local, o proporciona valores predeterminados de dev.
• Confirmar .env.local después de eas env:pull - Los archivos extraídos suelen contener valores de staging/producción. Solución: Añade .env*.local a .gitignore y usa comandos de extracción separados por máquina de desarrollador.
• Entornos no coincidentes entre jobs de flujo de trabajo - Un job de huella digital en production emparejado con una compilación de preview causa secretos incorrectos. Solución: Establece jobs.<id>.environment para coincidir con el entorno del perfil de compilación en flujos de trabajo de EAS.

Alternativas

Preguntas frecuentes

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

eas env:pull --environment development

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

Relacionado

• app.json & app.config.js - configuración dinámica, plugins, y manifiestos multiambiente
• Conceptos básicos de plataforma Expo - ramificación APP_VARIANT y vinculación de proyecto de EAS
• Expo Go vs Desarrollo de compilaciones - perfil de desarrollo y configuración de cliente de dev
• Actualización de versiones de Expo SDK - cambios de comportamiento de variables de entorno en cambios de SDK
• Cuenta de Expo, proyectos y permisos - variables con alcance de organización y acceso de rol
• Mejores prácticas - higiene de secretos y gobernanza de configuración a largo plazo

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).