CocoaPods & Pod Install

Q: Devo executar pod install antes ou depois do npm install?

Sempre npm install primeiro - o autolinking lê node_modules. Em seguida, npx expo prebuild (se usar CNG) e depois npx pod-install.

Q: O EAS Build executa pod install para mim?

Sim - quando ios/ está ausente, o EAS executa expo prebuild que inclui a instalação de pods. Quando ios/ está commitado, o EAS usa sua pasta e executa pod install no worker.

Q: Posso usar Bundler para CocoaPods?

Sim - algumas equipes adicionam Gemfile com pin do cocoapods e executam bundle exec pod install. npx pod-install continua sendo o padrão mais simples do Expo.

Higiene do Podfile.lock e peculiaridades do simulador Apple Silicon - o cookbook do CocoaPods que os desenvolvedores React Native precisam quando npx expo run:ios falha em Pods/, o EAS Build relata um erro de resolução de pod, ou um Mac com processador M seleciona a arquitetura incorreta do simulador.

Receita

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

# Ponto de entrada preferido da raiz do projeto (Expo envolve CocoaPods)
npx pod-install
 
# Equivalente quando já está em ios/
cd ios && pod install && cd ..
 
# Regeneração nativa completa (CNG) e depois pods
npx expo prebuild --platform ios
npx pod-install
 
# Reset nuclear quando os pods estiverem corrompidos após um bump de SDK
rm -rf ios/Pods ios/Podfile.lock ios/build
npx expo prebuild --platform ios
npx pod-install
npx expo run:ios

Quando usar isto:

The sandbox is not in sync with the Podfile.lock após um git pull.
Adicionando ou removendo um módulo nativo (expo-camera, react-native-maps, etc.).
Atualizando Expo SDK ou React Native - as versões dos pods mudam.
A compilação do simulador falha com erros de arquitetura no Apple Silicon.
O EAS Build passa localmente mas falha - desvio do lockfile entre colegas de equipe.

Exemplo de Trabalho

Passo 1 - Saiba quem é o dono do Podfile

Sob o Expo SDK 57, npx expo prebuild gera:

# ios/Podfile (excerto - não mantenha manualmente o bloco de autolinking)
require File.join(File.dirname(`node --print "require.resolve('expo/package.json')"`), "scripts/autolinking")
require File.join(File.dirname(`node --print "require.resolve('react-native/package.json')"`), "scripts/react_native_pods")
 
target 'ShopApp' do
  use_expo_modules!
  config = use_native_modules!
  use_react_native!(:path => config[:reactNativePath], :hermes_enabled => true)
end

Módulos nativos do package.json aparecem via autolinking - não linhas manuais de pod 'SomeLibrary' a menos que a documentação de uma biblioteca exija explicitamente.

Passo 2 - Adicione uma dependência nativa da maneira correta

npx expo install expo-camera
npx expo prebuild --platform ios   # aplica o plugin + entradas do Podfile
npx pod-install
npx expo run:ios

Passo 3 - Higiene do Podfile.lock

`ios/` no git?	Política do Podfile.lock
Sim (nativo bruto / commitado)	Commit `Podfile.lock` - CI e EAS devem resolver versões de pod idênticas
Não (CNG / gitignored)	O lockfile é efêmero - EAS o regenera a cada build; ainda assim, comite `package-lock.json`

# Após atualizações intencionais de pods em ios/ commitado
git add ios/Podfile.lock
git commit -m "chore(ios): fixa pods após adicionar expo-camera"

Passo 4 - Seleção do simulador Apple Silicon

# Lista os runtimes - prefira simuladores arm64 (Apple Silicon)
xcrun simctl list devices available | grep -E "iPhone|Booted"
 
# Execute em um simulador arm64 nomeado
npx expo run:ios --simulator "iPhone 16 Pro"

No Xcode → Product → Destination: evite simuladores marcados como Rosetta, a menos que um pod legado force x86_64 (raro no SDK 57).

Passo 5 - Corrija "building for iOS Simulator, but linking in object file built for iOS"

# 1. Garanta que não há caches de arquitetura mista
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ios/Pods ios/build
 
# 2. Reinstale os pods
npx pod-install
 
# 3. Recompile
npx expo run:ios --simulator "iPhone 16 Pro"

Se um pod de terceiros distribuir apenas binários pré-compilados x86_64, as opções são: atualizar o pod, escolher uma versão compatível com arm64, ou usar temporariamente um simulador Rosetta como ponte - não é uma solução de longo prazo.

O que isto demonstra:

npx pod-install é o ponto de entrada multiplataforma que o Expo documenta.
Disciplina de Lockfile previne falhas do EAS do tipo "funciona na minha máquina".
Alinhamento de arquitetura entre o runtime do simulador e os pods compilados.
Autolinking substitui edições manuais do Podfile para módulos do ecossistema.

Mergulho Profundo

pod install vs pod update

Comando	Efeito
`pod install`	Resolve a partir do Podfile.lock quando presente; adiciona/remove pods para corresponder ao Podfile
`pod update SomePod`	Atualiza `SomePod` para a última versão permitida pelo Podfile - altera o lockfile
`pod update`	Atualiza tudo - evite em branches de lançamento

Em equipes com ios/ commitado, execute pod install após o pull - não pod update - a menos que você pretenda atualizar as dependências nativas.

Expo prebuild e pods

Dependências do package.json
      ↓
expo-modules-autolinking + autolinking do RN
      ↓
ios/Podfile (gerado)
      ↓
pod install → Pods/ + Podfile.lock
      ↓
YourApp.xcworkspace

Plugins de configuração podem injetar subspecs de pod ou use_frameworks! - veja Config Plugins. Se um plugin e uma edição manual do Podfile entrarem em conflito, o plugin vence na próxima prebuild.

Notas sobre Apple Silicon (M1/M2/M3/M4)

Host: CocoaPods e Xcode rodam nativamente no Apple Silicon - Rosetta para CocoaPods não é necessário no Expo/RN moderno.
Simulador: Simuladores iOS padrão são arm64 - correspondem à arquitetura ARM do dispositivo, mais rápidos que Rosetta x86_64.
"My Mac (Designed for iPad)" - destino do Mac Catalyst; não o seu alvo de app iOS RN.
USE_FRAMEWORKS=static - alguns scripts de CI definem isso para Firebase; corresponda ao eas.json env do EAS com builds locais.

Falhas de CDN e rede

[!] CDN: trunk URL couldn't be downloaded: https://cdn.cocoapods.org/...

# Tente novamente com atualização do repositório
cd ios && pod install --repo-update && cd ..
 
# Proxy corporativo persistente: defina HTTP_PROXY / HTTPS_PROXY para o shell que executa pod install

Ambiente Ruby

O EAS Build gerencia Ruby/CocoaPods nos workers da nuvem. Localmente:

O Ruby do sistema macOS é depreciado - Ruby do Homebrew ou rbenv é aceitável.
npx pod-install usa o caminho esperado do projeto; prefira-o em vez de adivinhar pod no PATH.
sudo gem install cocoapods causa problemas de permissão - use instalações de gem no nível do usuário.

Nova Arquitetura (Padrão do SDK 57)

React Native 0.86 habilita a Nova Arquitetura por padrão. Os pods compilam cientes de Fabric/TurboModule. Se uma biblioteca legada não for compatível, expo-doctor e erros de compilação aparecerão cedo - corrija atualizando ou substituindo a biblioteca, não desabilitando a Nova Arquitetura em produção sem um ADR.

Armadilhas

Linhas manuais de pod 'ExpoModulesCore' - duplicadas com autolinking, erros de símbolo duplicado. Correção: remova edições manuais; npx expo prebuild --clean.
Commit do diretório Pods/ - repositório inchado, inferno de merge. Correção: comite apenas Podfile.lock; ignore Pods/ no .gitignore (padrão Expo).
Lockfile desatualizado após troca de branch - erros de sincronização do sandbox. Correção: npx pod-install ou delete Pods/ e reinstale.
Executar pod do diretório errado - cria Pods/ solto na raiz do repositório. Correção: execute apenas dentro de ios/ ou use npx pod-install da raiz.
Simulador x86_64 em Mac arm64 para desenvolvimento diário - lento e erros de incompatibilidade de arquitetura. Correção: use runtimes de simulador arm64 do Xcode → Settings → Platforms.
Versões diferentes do CocoaPods entre colegas de equipe - churn de lockfile. Correção: documente a versão do CocoaPods no README; EAS ignora desvios locais com prebuild limpo.

Alternativas

Alternativa	Use Quando	Não Use Quando
Swift Package Manager	Dependências puramente Swift, sem ecossistema RN	Pods do React Native - o ecossistema é primariamente CocoaPods
`eas build --local`	Reproduzir resolução de pod na nuvem	Iteração rápida apenas com JS
`npx expo prebuild --clean`	`ios/` é gerado e assombrado	Nativo commitado com merges manuais que você precisa preservar
`use_frameworks! :linkage => :static`	Firebase / documentação gRPC exigem isso	Apps RN padrão - aumenta o tempo de build

FAQs

Devo executar pod install antes ou depois do npm install?

Sempre npm install primeiro - o autolinking lê node_modules.
Em seguida, npx expo prebuild (se usar CNG) e depois npx pod-install.

O EAS Build executa pod install para mim?

Sim - quando ios/ está ausente, o EAS executa expo prebuild que inclui a instalação de pods.
Quando ios/ está commitado, o EAS usa sua pasta e executa pod install no worker.

Por que expo prebuild --clean exclui minhas edições do Podfile?

CNG assume que o nativo é gerado - edições manuais do Podfile não são duráveis.
Codifique as alterações em um plugin de configuração ou mantenha ios/ commitado sem --clean.

Posso usar Bundler para CocoaPods?

Sim - algumas equipes adicionam Gemfile com pin do cocoapods e executam bundle exec pod install.
npx pod-install continua sendo o padrão mais simples do Expo.

E sobre use_modular_headers!?

Ocasionalmente necessário para pods Swift em targets mistos.
Prefira expo-build-properties ou um plugin de configuração em vez de hacks manuais pontuais no Podfile.

Relacionados

Noções Básicas de iOS para Desenvolvedores RN - workspace, esquemas, entrada no Xcode
Noções Básicas de Prebuild - quando ios/ é regenerado
Plugins de Configuração - alterações nativas duráveis
Regras de Módulos Nativos - adicionando pacotes com segurança
Noções Básicas do EAS Build - compilação iOS na nuvem

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.

# Ponto de entrada preferido da raiz do projeto (Expo envolve CocoaPods)
npx pod-install
 
# Equivalente quando já está em ios/
cd ios && pod install && cd ..
 
# Regeneração nativa completa (CNG) e depois pods
npx expo prebuild --platform ios
npx pod-install
 
# Reset nuclear quando os pods estiverem corrompidos após um bump de SDK
rm -rf ios/Pods ios/Podfile.lock ios/build
npx expo prebuild --platform ios
npx pod-install
npx expo run:ios

Quando usar isto:

The sandbox is not in sync with the Podfile.lock após um git pull.
Adicionando ou removendo um módulo nativo (expo-camera, react-native-maps, etc.).
Atualizando Expo SDK ou React Native - as versões dos pods mudam.
A compilação do simulador falha com erros de arquitetura no Apple Silicon.
O EAS Build passa localmente mas falha - desvio do lockfile entre colegas de equipe.

Exemplo de Trabalho

Passo 1 - Saiba quem é o dono do Podfile

Sob o Expo SDK 57, npx expo prebuild gera:

# ios/Podfile (excerto - não mantenha manualmente o bloco de autolinking)
require File.join(File.dirname(`node --print "require.resolve('expo/package.json')"`), "scripts/autolinking")
require File.join(File.dirname(`node --print "require.resolve('react-native/package.json')"`), "scripts/react_native_pods")
 
target 'ShopApp' do
  use_expo_modules!
  config = use_native_modules!
  use_react_native!(:path => config[:reactNativePath], :hermes_enabled => true)
end

Módulos nativos do package.json aparecem via autolinking - não linhas manuais de pod 'SomeLibrary' a menos que a documentação de uma biblioteca exija explicitamente.

Passo 2 - Adicione uma dependência nativa da maneira correta

npx expo install expo-camera
npx expo prebuild --platform ios   # aplica o plugin + entradas do Podfile
npx pod-install
npx expo run:ios

Passo 3 - Higiene do Podfile.lock

`ios/` no git?	Política do Podfile.lock
Sim (nativo bruto / commitado)	Commit `Podfile.lock` - CI e EAS devem resolver versões de pod idênticas
Não (CNG / gitignored)	O lockfile é efêmero - EAS o regenera a cada build; ainda assim, comite `package-lock.json`

# Após atualizações intencionais de pods em ios/ commitado
git add ios/Podfile.lock
git commit -m "chore(ios): fixa pods após adicionar expo-camera"

Passo 4 - Seleção do simulador Apple Silicon

# Lista os runtimes - prefira simuladores arm64 (Apple Silicon)
xcrun simctl list devices available | grep -E "iPhone|Booted"
 
# Execute em um simulador arm64 nomeado
npx expo run:ios --simulator "iPhone 16 Pro"

No Xcode → Product → Destination: evite simuladores marcados como Rosetta, a menos que um pod legado force x86_64 (raro no SDK 57).

Passo 5 - Corrija "building for iOS Simulator, but linking in object file built for iOS"

# 1. Garanta que não há caches de arquitetura mista
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ios/Pods ios/build
 
# 2. Reinstale os pods
npx pod-install
 
# 3. Recompile
npx expo run:ios --simulator "iPhone 16 Pro"

O que isto demonstra:

npx pod-install é o ponto de entrada multiplataforma que o Expo documenta.
Disciplina de Lockfile previne falhas do EAS do tipo "funciona na minha máquina".
Alinhamento de arquitetura entre o runtime do simulador e os pods compilados.
Autolinking substitui edições manuais do Podfile para módulos do ecossistema.

Mergulho Profundo

pod install vs pod update

Comando	Efeito
`pod install`	Resolve a partir do Podfile.lock quando presente; adiciona/remove pods para corresponder ao Podfile
`pod update SomePod`	Atualiza `SomePod` para a última versão permitida pelo Podfile - altera o lockfile
`pod update`	Atualiza tudo - evite em branches de lançamento

Em equipes com ios/ commitado, execute pod install após o pull - não pod update - a menos que você pretenda atualizar as dependências nativas.

Expo prebuild e pods

Dependências do package.json
      ↓
expo-modules-autolinking + autolinking do RN
      ↓
ios/Podfile (gerado)
      ↓
pod install → Pods/ + Podfile.lock
      ↓
YourApp.xcworkspace

Notas sobre Apple Silicon (M1/M2/M3/M4)

Host: CocoaPods e Xcode rodam nativamente no Apple Silicon - Rosetta para CocoaPods não é necessário no Expo/RN moderno.
Simulador: Simuladores iOS padrão são arm64 - correspondem à arquitetura ARM do dispositivo, mais rápidos que Rosetta x86_64.
"My Mac (Designed for iPad)" - destino do Mac Catalyst; não o seu alvo de app iOS RN.
USE_FRAMEWORKS=static - alguns scripts de CI definem isso para Firebase; corresponda ao eas.json env do EAS com builds locais.

Falhas de CDN e rede

[!] CDN: trunk URL couldn't be downloaded: https://cdn.cocoapods.org/...

# Tente novamente com atualização do repositório
cd ios && pod install --repo-update && cd ..
 
# Proxy corporativo persistente: defina HTTP_PROXY / HTTPS_PROXY para o shell que executa pod install

Ambiente Ruby

O EAS Build gerencia Ruby/CocoaPods nos workers da nuvem. Localmente:

O Ruby do sistema macOS é depreciado - Ruby do Homebrew ou rbenv é aceitável.
npx pod-install usa o caminho esperado do projeto; prefira-o em vez de adivinhar pod no PATH.
sudo gem install cocoapods causa problemas de permissão - use instalações de gem no nível do usuário.

Nova Arquitetura (Padrão do SDK 57)

Armadilhas

Linhas manuais de pod 'ExpoModulesCore' - duplicadas com autolinking, erros de símbolo duplicado. Correção: remova edições manuais; npx expo prebuild --clean.
Commit do diretório Pods/ - repositório inchado, inferno de merge. Correção: comite apenas Podfile.lock; ignore Pods/ no .gitignore (padrão Expo).
Lockfile desatualizado após troca de branch - erros de sincronização do sandbox. Correção: npx pod-install ou delete Pods/ e reinstale.
Executar pod do diretório errado - cria Pods/ solto na raiz do repositório. Correção: execute apenas dentro de ios/ ou use npx pod-install da raiz.
Simulador x86_64 em Mac arm64 para desenvolvimento diário - lento e erros de incompatibilidade de arquitetura. Correção: use runtimes de simulador arm64 do Xcode → Settings → Platforms.
Versões diferentes do CocoaPods entre colegas de equipe - churn de lockfile. Correção: documente a versão do CocoaPods no README; EAS ignora desvios locais com prebuild limpo.

Alternativas

Alternativa	Use Quando	Não Use Quando
Swift Package Manager	Dependências puramente Swift, sem ecossistema RN	Pods do React Native - o ecossistema é primariamente CocoaPods
`eas build --local`	Reproduzir resolução de pod na nuvem	Iteração rápida apenas com JS
`npx expo prebuild --clean`	`ios/` é gerado e assombrado	Nativo commitado com merges manuais que você precisa preservar
`use_frameworks! :linkage => :static`	Firebase / documentação gRPC exigem isso	Apps RN padrão - aumenta o tempo de build

FAQs

Devo executar pod install antes ou depois do npm install?

Sempre npm install primeiro - o autolinking lê node_modules.
Em seguida, npx expo prebuild (se usar CNG) e depois npx pod-install.

O EAS Build executa pod install para mim?

Sim - quando ios/ está ausente, o EAS executa expo prebuild que inclui a instalação de pods.
Quando ios/ está commitado, o EAS usa sua pasta e executa pod install no worker.

Por que expo prebuild --clean exclui minhas edições do Podfile?

CNG assume que o nativo é gerado - edições manuais do Podfile não são duráveis.
Codifique as alterações em um plugin de configuração ou mantenha ios/ commitado sem --clean.

Posso usar Bundler para CocoaPods?

Sim - algumas equipes adicionam Gemfile com pin do cocoapods e executam bundle exec pod install.
npx pod-install continua sendo o padrão mais simples do Expo.

E sobre use_modular_headers!?

Ocasionalmente necessário para pods Swift em targets mistos.
Prefira expo-build-properties ou um plugin de configuração em vez de hacks manuais pontuais no Podfile.

Relacionados

Noções Básicas de iOS para Desenvolvedores RN - workspace, esquemas, entrada no Xcode
Noções Básicas de Prebuild - quando ios/ é regenerado
Plugins de Configuração - alterações nativas duráveis
Regras de Módulos Nativos - adicionando pacotes com segurança
Noções Básicas do EAS Build - compilação iOS na nuvem

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

CocoaPods & Pod Install

Buscar na documentação

CocoaPods & Pod Install