Noções Básicas de iOS para Desenvolvedores RN

Q: Onde a versão iOS / target de implantação é definida?

expo.ios.deploymentTarget em app.config.ts, ou plugin expo-build-properties. Reconstrua o nativo após a alteração - não é uma alteração OTA.

Q: Posso excluir DerivedData?

Sim, quando os builds parecem assombrados: rm -rf ~/Library/Developer/Xcode/DerivedData. Em seguida, cd ios && pod install && cd .. e reconstrua.

Q: Qual pasta eu commito?

CNG: commite app.config.ts, não ios/. Puro: commite ios/ incluindo Podfile.lock - veja CocoaPods & Pod Install.

Essenciais do Xcode sem se tornar um engenheiro iOS em tempo integral - o modelo mental mínimo que os desenvolvedores React Native precisam quando npx expo run:ios, EAS Build ou um crash log nativo o puxam para a cadeia de ferramentas da Apple no SDK 57.

Receita

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

# Gera ios/ a partir de app.config.ts (CNG) e executa no simulador
npx expo prebuild --platform ios
npx expo run:ios
 
# Escolhe um simulador específico
npx expo run:ios --simulator "iPhone 16 Pro"
 
# Dispositivo USB (requer conta Apple Developer + Xcode)
npx expo run:ios --device
 
# Abre o workspace quando você precisar inspecionar as configurações de build nativas
open ios/*.xcworkspace
 
# Lista simuladores e dispositivos conectados
xcrun simctl list devices available
xcrun xctrace list devices

Quando usar isso:

Primeira vez abrindo ios/ após npx expo prebuild.
Um build nativo falha no EAS e você precisa reproduzi-lo localmente no Xcode.
QA relata um bug exclusivo de dispositivo (push, câmera, biometria, links universais).
Você precisa ler um crash log ou anexar o depurador nativo a um problema do Hermes.
Alguém na equipe pergunta "qual arquivo devo editar?" - resposta: geralmente app.config.ts, não pbxproj.

Exemplo de Trabalho

Etapa 1 - Entenda o que o prebuild gerou

ios/
├── Podfile                 ← Manifesto de dependência do CocoaPods (autolinking escreve aqui)
├── Podfile.lock            ← Versões de pod fixadas (commite se ios/ estiver no git)
├── YourApp.xcworkspace     ← ABRA ISTO no Xcode (inclui o projeto Pods)
├── YourApp.xcodeproj       ← Apenas o target do app - entrada incorreta quando os Pods existem
└── YourApp/
    ├── AppDelegate.swift   ← Ponto de entrada do RN; raramente edite manualmente sob CNG
    ├── Info.plist          ← Strings de permissão; prefira plugins de app.config
    └── YourApp.entitlements ← Push, domínios associados, grupos de apps

Etapa 2 - Execute a partir da CLI (caminho diário)

npx expo install expo-dev-client
npx expo prebuild --platform ios
npx expo run:ios --simulator "iPhone 16 Pro"
npx expo start --dev-client

Etapa 3 - Abra o Xcode apenas quando necessário

open ios/ShopApp.xcworkspace

No Xcode:

Scheme (barra de ferramentas): ShopApp → seleciona o target do app a ser compilado.
Destination: simulador ou iPhone conectado.
Product → Run (⌘R): o mesmo que npx expo run:ios, mas com breakpoints gráficos no código nativo.
Aba Signing & Capabilities: bundle ID, equipe, entitlements espelham - devem corresponder a app.config.ts.

Etapa 4 - Leia uma falha de build nativa

▸ Compiling SomePod.m
❌ Arquivo 'SomeHeader.h' não encontrado

Ordem típica de correção RN/Expo:

cd ios && pod install && cd ..
npx expo prebuild --platform ios --no-clean   # apenas se ios/ estiver committado
npx expo run:ios

Se o erro for de assinatura:

error: Nenhum perfil para 'com.example.app' foi encontrado

Corrija em Credenciais iOS do EAS ou Xcode → Signing → selecione sua Equipe - não desabilitando a assinatura.

O que isso demonstra:

Workspace vs projeto - CocoaPods requer .xcworkspace.
Fluxo de trabalho CLI-first - Comandos Expo envolvem o Xcode; você não vive no Interface Builder.
Configuração é a fonte da verdade - entitlements e chaves do Info.plist devem fluir de plugins de app.config.ts.
Simulador vs dispositivo - escolha o hardware certo para o recurso em teste.

Mergulho Profundo

Conceitos do Xcode mapeados para RN

Termo Xcode	Equivalente RN / Expo
Target	O binário `.app` (seu app, ou uma extensão de widget)
Scheme	Configuração de build + execução para um target (Debug/Release)
Workspace	Projeto do app + `Pods.xcodeproj`
Bundle Identifier	`ios.bundleIdentifier` em `app.config.ts`
Provisioning Profile	Permissão assinada pela Apple ligando certificado + bundle ID + dispositivos
Capabilities / Entitlements	`ios.associatedDomains`, push, keychain - veja Entitlements & Capabilities
Info.plist	Strings de uso de permissão, esquemas de URL, modos de segundo plano
Archive	Build de Release para TestFlight - `eas build` faz isso em CI

Debug vs Release

	Debug	Release
Hermes	Ferramentas de desenvolvimento habilitadas	Bytecode otimizado
Bundle JS	Servidor de desenvolvimento Metro	Bundle de produção embutido
Assinatura	Certificado de desenvolvimento	Certificado de distribuição
Use quando	Desenvolvimento diário, depuração USB	TestFlight, App Store

npx expo run:ios compila Debug por padrão. Binários de loja vêm de eas build --profile production.

Essenciais do Simulador

# Inicia um simulador sem executar o app
xcrun simctl boot "iPhone 16 Pro"
 
# Abre uma URL (teste rápido de link universal)
xcrun simctl openurl booted "https://shop.example.com/orders/42"
 
# Apaga o estado (chaveiro travado / AASA em cache)
xcrun simctl erase booted

Macs com Apple Silicon executam simuladores arm64 nativamente - prefira-os sobre simuladores Rosetta-x86_64.
Simuladores não podem receber push APNs real, não executam BGTaskScheduler fielmente e simulam alguns sensores.
Dispositivos físicos iOS 16+ exigem Modo de Desenvolvedor (Ajustes → Privacidade e Segurança).

CNG vs `ios/` committado

Modelo	Você edita	Papel do Xcode
CNG (`ios/` ignorado pelo git)	`app.config.ts`, plugins	Apenas depurador; regenerado no prebuild
Nativo committado	`ios/` + plugins	Mescle alterações nativas cuidadosamente em atualizações de SDK

Padrão do SDK 57: npx expo prebuild executa --clean - veja Noções Básicas de Prebuild.

Quando você realmente precisa do Xcode

Erros de compilação de módulo nativo em um pod específico.
Inspecionar Signing & Capabilities após uma rejeição.
Anexar a um crash nativo (não caixa vermelha JS) em AppDelegate ou um SDK de terceiros.
Profiling com Instruments (vazamentos de memória em pipelines de imagem nativa).

Para depuração JS, prefira React Native DevTools e Metro - não breakpoints do Xcode em código de aplicativo.

Armadilhas

Abrir .xcodeproj em vez de .xcworkspace - Headers do Pods ausentes, build falha. Correção: sempre open ios/*.xcworkspace.
Editar Info.plist / entitlements manualmente sob CNG - apagados no próximo prebuild. Correção: plugin de configuração ou campos ios de app.config.ts.
Assumir que o simulador prova push ou Live Activities - APNs requer dispositivo + entitlements adequados. Correção: teste em dispositivo USB.
Discrepância de Bundle ID - app.config.ts, portal Apple Developer e appID do AASA devem corresponder exatamente.
Perseguir a UI do Xcode em cada upgrade do RN - se ios/ for gerado, exclua e prebuild --clean antes de merges manuais profundos.
Usar Expo Go para recursos de entitlements do iOS - links universais, Sign in with Apple e grupos de apps precisam do seu bundle ID em um cliente de desenvolvimento ou build de loja.

Alternativas

Alternativa	Use Quando	Não Use Quando
`eas build --local`	Reproduzir build iOS na nuvem no seu Mac	Você só precisa de uma execução rápida de simulador Debug
Xcode Cloud	Equipe já usa CI da Apple	Equipes Expo padrão - EAS Build é mais simples
`npx react-native run-ios`	RN puro sem prebuild do Expo	Projetos Expo - perde o pipeline de plugins de configuração
VS Code + sweetpad	Integração de editor mais leve	Problemas complexos de assinatura - use a GUI do Xcode

FAQs

Preciso de uma conta Apple Developer paga para builds de simulador?

Não - builds de simulador funcionam com Apple ID gratuito.
Dispositivo físico, TestFlight e App Store exigem o programa de US$ 99/ano.

Onde a versão iOS / target de implantação é definida?

expo.ios.deploymentTarget em app.config.ts, ou plugin expo-build-properties.
Reconstrua o nativo após a alteração - não é uma alteração OTA.

Por que o Metro diz "No bundle URL present" no dispositivo?

Telefone e Mac não estão na mesma rede, ou o cliente de desenvolvimento não consegue alcançar o Metro.
Tente npx expo start --dev-client --tunnel ou USB com flags de hostname apropriadas.

Como vejo logs nativos?

Xcode → Window → Devices and Simulators → Open Console.
CLI: npx react-native log-ios ou xcrun simctl spawn booted log stream --predicate 'processImagePath contains "YourApp"'.

Posso excluir DerivedData?

Sim, quando os builds parecem assombrados: rm -rf ~/Library/Developer/Xcode/DerivedData.
Em seguida, cd ios && pod install && cd .. e reconstrua.

Qual pasta eu commito?

CNG: commite app.config.ts, não ios/.
Puro: commite ios/ incluindo Podfile.lock - veja CocoaPods & Pod Install.

Relacionado

CocoaPods & Pod Install - pod install e peculiaridades do Apple Silicon
Entitlements & Capabilities - push, domínios, keychain
Teste em Dispositivo Físico - depuração USB e sem fio
Noções Básicas de Prebuild - fluxo de trabalho CNG
Links Universais iOS - domínios associados e AASA
Credenciais e Provisionamento iOS - certificados e perfis

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.

# Gera ios/ a partir de app.config.ts (CNG) e executa no simulador
npx expo prebuild --platform ios
npx expo run:ios
 
# Escolhe um simulador específico
npx expo run:ios --simulator "iPhone 16 Pro"
 
# Dispositivo USB (requer conta Apple Developer + Xcode)
npx expo run:ios --device
 
# Abre o workspace quando você precisar inspecionar as configurações de build nativas
open ios/*.xcworkspace
 
# Lista simuladores e dispositivos conectados
xcrun simctl list devices available
xcrun xctrace list devices

Quando usar isso:

Primeira vez abrindo ios/ após npx expo prebuild.
Um build nativo falha no EAS e você precisa reproduzi-lo localmente no Xcode.
QA relata um bug exclusivo de dispositivo (push, câmera, biometria, links universais).
Você precisa ler um crash log ou anexar o depurador nativo a um problema do Hermes.
Alguém na equipe pergunta "qual arquivo devo editar?" - resposta: geralmente app.config.ts, não pbxproj.

Exemplo de Trabalho

Etapa 1 - Entenda o que o prebuild gerou

ios/
├── Podfile                 ← Manifesto de dependência do CocoaPods (autolinking escreve aqui)
├── Podfile.lock            ← Versões de pod fixadas (commite se ios/ estiver no git)
├── YourApp.xcworkspace     ← ABRA ISTO no Xcode (inclui o projeto Pods)
├── YourApp.xcodeproj       ← Apenas o target do app - entrada incorreta quando os Pods existem
└── YourApp/
    ├── AppDelegate.swift   ← Ponto de entrada do RN; raramente edite manualmente sob CNG
    ├── Info.plist          ← Strings de permissão; prefira plugins de app.config
    └── YourApp.entitlements ← Push, domínios associados, grupos de apps

Etapa 2 - Execute a partir da CLI (caminho diário)

npx expo install expo-dev-client
npx expo prebuild --platform ios
npx expo run:ios --simulator "iPhone 16 Pro"
npx expo start --dev-client

Etapa 3 - Abra o Xcode apenas quando necessário

open ios/ShopApp.xcworkspace

No Xcode:

Scheme (barra de ferramentas): ShopApp → seleciona o target do app a ser compilado.
Destination: simulador ou iPhone conectado.
Product → Run (⌘R): o mesmo que npx expo run:ios, mas com breakpoints gráficos no código nativo.
Aba Signing & Capabilities: bundle ID, equipe, entitlements espelham - devem corresponder a app.config.ts.

Etapa 4 - Leia uma falha de build nativa

▸ Compiling SomePod.m
❌ Arquivo 'SomeHeader.h' não encontrado

Ordem típica de correção RN/Expo:

cd ios && pod install && cd ..
npx expo prebuild --platform ios --no-clean   # apenas se ios/ estiver committado
npx expo run:ios

Se o erro for de assinatura:

error: Nenhum perfil para 'com.example.app' foi encontrado

Corrija em Credenciais iOS do EAS ou Xcode → Signing → selecione sua Equipe - não desabilitando a assinatura.

O que isso demonstra:

Workspace vs projeto - CocoaPods requer .xcworkspace.
Fluxo de trabalho CLI-first - Comandos Expo envolvem o Xcode; você não vive no Interface Builder.
Configuração é a fonte da verdade - entitlements e chaves do Info.plist devem fluir de plugins de app.config.ts.
Simulador vs dispositivo - escolha o hardware certo para o recurso em teste.

Mergulho Profundo

Conceitos do Xcode mapeados para RN

Termo Xcode	Equivalente RN / Expo
Target	O binário `.app` (seu app, ou uma extensão de widget)
Scheme	Configuração de build + execução para um target (Debug/Release)
Workspace	Projeto do app + `Pods.xcodeproj`
Bundle Identifier	`ios.bundleIdentifier` em `app.config.ts`
Provisioning Profile	Permissão assinada pela Apple ligando certificado + bundle ID + dispositivos
Capabilities / Entitlements	`ios.associatedDomains`, push, keychain - veja Entitlements & Capabilities
Info.plist	Strings de uso de permissão, esquemas de URL, modos de segundo plano
Archive	Build de Release para TestFlight - `eas build` faz isso em CI

Debug vs Release

	Debug	Release
Hermes	Ferramentas de desenvolvimento habilitadas	Bytecode otimizado
Bundle JS	Servidor de desenvolvimento Metro	Bundle de produção embutido
Assinatura	Certificado de desenvolvimento	Certificado de distribuição
Use quando	Desenvolvimento diário, depuração USB	TestFlight, App Store

npx expo run:ios compila Debug por padrão. Binários de loja vêm de eas build --profile production.

Essenciais do Simulador

# Inicia um simulador sem executar o app
xcrun simctl boot "iPhone 16 Pro"
 
# Abre uma URL (teste rápido de link universal)
xcrun simctl openurl booted "https://shop.example.com/orders/42"
 
# Apaga o estado (chaveiro travado / AASA em cache)
xcrun simctl erase booted

Macs com Apple Silicon executam simuladores arm64 nativamente - prefira-os sobre simuladores Rosetta-x86_64.
Simuladores não podem receber push APNs real, não executam BGTaskScheduler fielmente e simulam alguns sensores.
Dispositivos físicos iOS 16+ exigem Modo de Desenvolvedor (Ajustes → Privacidade e Segurança).

CNG vs `ios/` committado

Modelo	Você edita	Papel do Xcode
CNG (`ios/` ignorado pelo git)	`app.config.ts`, plugins	Apenas depurador; regenerado no prebuild
Nativo committado	`ios/` + plugins	Mescle alterações nativas cuidadosamente em atualizações de SDK

Padrão do SDK 57: npx expo prebuild executa --clean - veja Noções Básicas de Prebuild.

Quando você realmente precisa do Xcode

Erros de compilação de módulo nativo em um pod específico.
Inspecionar Signing & Capabilities após uma rejeição.
Anexar a um crash nativo (não caixa vermelha JS) em AppDelegate ou um SDK de terceiros.
Profiling com Instruments (vazamentos de memória em pipelines de imagem nativa).

Para depuração JS, prefira React Native DevTools e Metro - não breakpoints do Xcode em código de aplicativo.

Armadilhas

Abrir .xcodeproj em vez de .xcworkspace - Headers do Pods ausentes, build falha. Correção: sempre open ios/*.xcworkspace.
Editar Info.plist / entitlements manualmente sob CNG - apagados no próximo prebuild. Correção: plugin de configuração ou campos ios de app.config.ts.
Assumir que o simulador prova push ou Live Activities - APNs requer dispositivo + entitlements adequados. Correção: teste em dispositivo USB.
Discrepância de Bundle ID - app.config.ts, portal Apple Developer e appID do AASA devem corresponder exatamente.
Perseguir a UI do Xcode em cada upgrade do RN - se ios/ for gerado, exclua e prebuild --clean antes de merges manuais profundos.
Usar Expo Go para recursos de entitlements do iOS - links universais, Sign in with Apple e grupos de apps precisam do seu bundle ID em um cliente de desenvolvimento ou build de loja.

Alternativas

Alternativa	Use Quando	Não Use Quando
`eas build --local`	Reproduzir build iOS na nuvem no seu Mac	Você só precisa de uma execução rápida de simulador Debug
Xcode Cloud	Equipe já usa CI da Apple	Equipes Expo padrão - EAS Build é mais simples
`npx react-native run-ios`	RN puro sem prebuild do Expo	Projetos Expo - perde o pipeline de plugins de configuração
VS Code + sweetpad	Integração de editor mais leve	Problemas complexos de assinatura - use a GUI do Xcode

FAQs

Preciso de uma conta Apple Developer paga para builds de simulador?

Não - builds de simulador funcionam com Apple ID gratuito.
Dispositivo físico, TestFlight e App Store exigem o programa de US$ 99/ano.

Onde a versão iOS / target de implantação é definida?

expo.ios.deploymentTarget em app.config.ts, ou plugin expo-build-properties.
Reconstrua o nativo após a alteração - não é uma alteração OTA.

Por que o Metro diz "No bundle URL present" no dispositivo?

Telefone e Mac não estão na mesma rede, ou o cliente de desenvolvimento não consegue alcançar o Metro.
Tente npx expo start --dev-client --tunnel ou USB com flags de hostname apropriadas.

Como vejo logs nativos?

Xcode → Window → Devices and Simulators → Open Console.
CLI: npx react-native log-ios ou xcrun simctl spawn booted log stream --predicate 'processImagePath contains "YourApp"'.

Posso excluir DerivedData?

Sim, quando os builds parecem assombrados: rm -rf ~/Library/Developer/Xcode/DerivedData.
Em seguida, cd ios && pod install && cd .. e reconstrua.

Qual pasta eu commito?

CNG: commite app.config.ts, não ios/.
Puro: commite ios/ incluindo Podfile.lock - veja CocoaPods & Pod Install.

Relacionado

CocoaPods & Pod Install - pod install e peculiaridades do Apple Silicon
Entitlements & Capabilities - push, domínios, keychain
Teste em Dispositivo Físico - depuração USB e sem fio
Noções Básicas de Prebuild - fluxo de trabalho CNG
Links Universais iOS - domínios associados e AASA
Credenciais e Provisionamento iOS - certificados e perfis

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

Noções Básicas de iOS para Desenvolvedores RN

Buscar na documentação

Noções Básicas de iOS para Desenvolvedores RN