Configuração do expo-updates

Versão de runtime, URL de atualização e políticas de verificação no lançamento - o cookbook do app.config para conectar o EAS Update a aplicativos Expo SDK 57 para que binários e pacotes OTA permaneçam compatíveis.

Receita

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

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;

# Verifique a configuração pública resolvida
npx expo config --type public | jq '{runtimeVersion, updates}'
 
# Publique com o ambiente EAS (SDK 55+)
eas update --channel production --environment production --message "Config verified"

Quando usar isso:

• Configuração inicial do EAS Update após eas init.
• Auditoria de por que os dispositivos pulam atualizações (incompatibilidade de runtimeVersion ou canal).
• Ajuste do comportamento de inicialização - verificação silenciosa em segundo plano vs. busca bloqueante.
• Sabores white-label que precisam de requestHeaders e projectId por variante.

Quando evitar:

• Alteração de permissões nativas ou plugins - a edição de configuração ainda requer eas build.
• Apontar aplicativos de produção para cabeçalhos do canal development - use perfis de build em vez disso.
• Esperar que expo start aplique OTA - as atualizações são desativadas no modo de desenvolvimento.

Exemplo de Trabalho

Um app.config.ts pronto para produção com cabeçalhos de canal orientados por perfil, política de runtime explícita e política de verificação de inicialização.

Etapa 1 - Canais 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"
    }
  }
}

Etapa 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;

Etapa 3 - Primeira build nativa após a configuração

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

O que isso demonstra:

• runtimeVersion.policy: "appVersion" vincula o direcionamento OTA ao expo.version
• updates.url usa o UUID do projeto EAS de extra.eas.projectId
• requestHeaders["expo-channel-name"] deve corresponder ao channel do perfil em eas.json
• checkAutomatically: "ON_LOAD" verifica em cada inicialização fria; fallbackToCacheTimeout: 0 nunca bloqueia o lançamento em rede

Mergulho Profundo

Opções de runtimeVersion

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

• Escolha uma política por aplicativo - documente-a no README e nos tickets de lançamento
• Mudar a política no meio do caminho deixa os dispositivos sem suporte - coordene com um lançamento na loja
• Veja Runtime Version Policy para orientação de seleção

Valores de checkAutomatically

updates: {
  checkAutomatically: "ON_LOAD",
  fallbackToCacheTimeout: 0, // 0 = nunca bloqueia o lançamento esperando pela rede
},

• fallbackToCacheTimeout: 3000 bloqueia o lançamento por até 3s para um pacote atualizado - use com moderação
• Emparelhe verificações automáticas com recarga por consentimento do usuário para atualizações disruptivas - veja expo-updates (Client API)

Conexão de Cabeçalhos de Canal

eas.json build.profile.channel  →  embutido no binário em eas build
app.config updates.requestHeaders  →  enviado a cada verificação de atualização
eas update --channel <name>     →  publica o pacote nesse canal

• Todos os três devem concordar - a incompatibilidade de canal é o incidente #1 de "correção nunca chegou"
• eas update:configure gera updates.url e projectId - não substitui a disciplina de perfil
• White-label: projectId, canal e ID do pacote separados por variante de aplicativo

Variáveis de Ambiente em Executores de Atualização

# SDK 55+ - o .env local NÃO é usado nos executores de atualização EAS
eas update --channel production --environment production

• Crie ambientes EAS correspondentes para preview e production
• Alinhe as variáveis EXPO_PUBLIC_* entre eas build e eas update para o mesmo canal
• URLs de API incompatíveis em OTA vs. binário causam interrupções de autenticação - trate a paridade de ambiente como um portão de lançamento

Armadilhas

• updates.url ausente - Updates.isEnabled é falso. Correção: eas update:configure + reconstruir.
• Derivação de runtimeVersion - A build usou 2.4.0, a atualização foi publicada sob 2.5.0 após o aumento da versão sem reconstrução. Correção: Reconstruir binários ou publicar no runtime correspondente.
• Cabeçalho production codificado em hard-code no perfil de desenvolvimento - O QA de preview recebe OTAs de produção. Correção: Direcionar o cabeçalho a partir de EAS_BUILD_PROFILE.
• Primeira configuração sem reconstrução - O binário antigo não possui a fiação nativa do expo-updates. Correção: Nova eas build após adicionar a configuração de atualizações.
• fallbackToCacheTimeout bloqueante em redes lentas - Os usuários ficam olhando para a splash screen. Correção: Mantenha 0 a menos que você tenha uma UX de atualização offline forte.
• Publicação sem --environment - Hosts de API desatualizados ou incorretos embutidos no pacote OTA. Correção: Sempre passe --environment no SDK 55+.

Alternativas

FAQs

Relacionados

• Noções Básicas de Atualizações OTA - Limites OTA vs. loja
• Runtime Version Policy - Comparação de políticas
• Canais e Branches de Lançamento - Promoção de canais
• expo-updates (Client API) - Verificação e recarga programáticas
• Perfis e Sabores de Build - Mapeamento de canal eas.json
• Regras de Lançamento e OTA - Checklist de configuração Nível 1

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