Configuración expo-updates

Política de versión en tiempo de ejecución, URL de actualización y políticas de verificación al iniciar - el libro de recetas de app.config para conectar EAS Update en aplicaciones Expo SDK 57 para que los binarios y los bundles OTA permanezcan compatibles.

Receta

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

npx expo install expo-updates
npx eas init
npx eas update:configure

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  version: "2.4.0",
  runtimeVersion: {
    policy: "appVersion",
  },
  extra: {
    eas: {
      projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    },
  },
  updates: {
    url: "https://u.expo.dev/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    checkAutomatically: "ON_LOAD",
    fallbackToCacheTimeout: 0,
    requestHeaders: {
      "expo-channel-name": "production",
    },
  },
};
 
export default config;

# Verifica la configuración pública resuelta
npx expo config --type public | jq '{runtimeVersion, updates}'
 
# Publica con ambiente de EAS (SDK 55+)
eas update --channel production --environment production --message "Config verified"

Cuándo usarlo:

• Configuración inicial de EAS Update después de eas init.
• Auditar por qué los dispositivos saltan actualizaciones (desajuste de runtimeVersion o channel).
• Ajustar el comportamiento de inicio - verificación silenciosa en segundo plano versus descarga bloqueante.
• Sabores de etiqueta blanca que necesitan requestHeaders y projectId por variante.

Cuándo evitarlo:

• Cambiar permisos nativos o plugins - la edición de config aún requiere eas build.
• Apuntar aplicaciones de producción a headers de development channel - en su lugar usa perfiles de build.
• Esperar que expo start aplique OTA - las actualizaciones están deshabilitadas en desarrollo.

Ejemplo de Trabajo

Un app.config.ts listo para producción con headers de channel impulsados por perfil, política de runtime explícita y política de verificación al inicio.

Paso 1 - Canales eas.json por perfil de build

{
  "cli": { "version": ">= 16.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "channel": "development"
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview"
    },
    "production": {
      "channel": "production"
    }
  }
}

Paso 2 - app.config.ts dinámico

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const EAS_PROJECT_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
 
const channel =
  process.env.EAS_BUILD_PROFILE === "preview"
    ? "preview"
    : process.env.EAS_BUILD_PROFILE === "development"
      ? "development"
      : "production";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  version: "2.4.0",
  runtimeVersion: { policy: "appVersion" },
  extra: { eas: { projectId: EAS_PROJECT_ID } },
  updates: {
    url: `https://u.expo.dev/${EAS_PROJECT_ID}`,
    checkAutomatically: "ON_LOAD",
    fallbackToCacheTimeout: 0,
    requestHeaders: { "expo-channel-name": channel },
  },
  ios: { bundleIdentifier: "com.example.shopapp" },
  android: { package: "com.example.shopapp" },
};
 
export default config;

Paso 3 - Primer build nativo después de configurar

eas build --profile preview --platform all
eas update --channel preview --environment preview --message "Smoke test channel wiring"

Lo que esto demuestra:

• runtimeVersion.policy: "appVersion" vincula la orientación de OTA a expo.version
• updates.url usa el UUID del proyecto de EAS de extra.eas.projectId
• requestHeaders["expo-channel-name"] debe coincidir con el channel del perfil en eas.json
• checkAutomatically: "ON_LOAD" verifica en cada inicio en frío; fallbackToCacheTimeout: 0 nunca bloquea el lanzamiento en la red

Análisis Profundo

Opciones de runtimeVersion

// Runtime explícito estático (avanzado / brownfield)
runtimeVersion: "shop-native-2026-q1",

• Elige una política por aplicación - docméntala en README y tickets de lanzamiento
• Cambiar la política en vuelo deja dispositivos sin servicio - coordina con un lanzamiento en tienda
• Consulta Política de versión en tiempo de ejecución para orientación de selección

Valores de checkAutomatically

updates: {
  checkAutomatically: "ON_LOAD",
  fallbackToCacheTimeout: 0, // 0 = nunca bloquea el lanzamiento esperando red
},

• fallbackToCacheTimeout: 3000 bloquea el lanzamiento hasta 3s para un bundle fresco - usa con moderación
• Empareja verificaciones automáticas con recarga de consentimiento del usuario para actualizaciones disruptivas - consulta expo-updates (API de Cliente)

Cableado de Headers de Channel

eas.json build.profile.channel  ->  incrustado en binario en eas build
app.config updates.requestHeaders  ->  enviado en cada verificación de actualización
eas update --channel <name>     ->  publica bundle a ese channel

• Los tres deben coincidir - el desajuste de channel es el incidente #1 "la fix nunca llegó"
• eas update:configure andamia updates.url y projectId - no reemplaza la disciplina de perfil
• Etiqueta blanca: separado projectId, channel y bundle ID por variante de aplicación

Variables de Entorno en Corredores de Actualización

# SDK 55+ - el .env local NO se usa en los corredores de EAS update
eas update --channel production --environment production

• Crea ambientes de EAS coincidentes para preview y production
• Alinea variables EXPO_PUBLIC_* entre eas build y eas update para el mismo channel
• Las URL de API no coincidentes en OTA versus binario causan interrupciones de autenticación - trata la paridad de env como una puerta de lanzamiento

Trampas Comunes

• updates.url faltante - Updates.isEnabled es false. Fix: eas update:configure + reconstruir.
• Divergencia de runtimeVersion - Build usó 2.4.0, actualización publicada bajo 2.5.0 después del aumento de versión sin reconstrucción. Fix: Reconstruye binarios o publica con runtime coincidente.
• Header production codificado en perfil de desarrollo - La QA de Preview recibe OTAs de producción. Fix: Impulsa el header desde EAS_BUILD_PROFILE.
• Primer configure sin reconstrucción - Binario antiguo carece del cableado nativo de expo-updates. Fix: Nuevo eas build después de agregar config de updates.
• Bloqueando fallbackToCacheTimeout en redes lentas - Los usuarios miran la pantalla de inicio. Fix: Mantén 0 a menos que tengas una UX de offline-update fuerte.
• Publicar sin --environment - Hosts de API desactualizado o incorrecto cocidos en el bundle OTA. Fix: Siempre pasa --environment en SDK 55+.

Alternativas

FAQs

Relacionado

• Conceptos Básicos de OTA Updates - Límites de OTA versus tienda
• Política de Versión en Tiempo de Ejecución - Comparación de políticas
• Canales de Lanzamiento y Ramas - Promoción de channels
• expo-updates (API de Cliente) - Verificación y recarga programática
• Perfiles de Build y Sabores - Mapeo de channel en eas.json
• Reglas de Lanzamiento y OTA - Lista de verificación de config de Tier 1

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