CocoaPods e Instalación de Pods

Higiene de Podfile.lock y peculiaridades de simuladores Apple Silicon - el recetario de CocoaPods que los desarrolladores de React Native necesitan cuando npx expo run:ios falla en Pods/, EAS Build reporta un error de resolución de pods, o una Mac con chip M elige la arquitectura de simulador incorrecta.

Receta

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

# Punto de entrada preferido desde la raíz del proyecto (Expo envuelve CocoaPods)
npx pod-install
 
# Equivalente cuando ya está en ios/
cd ios && pod install && cd ..
 
# Regeneración nativa completa (CNG) luego pods
npx expo prebuild --platform ios
npx pod-install
 
# Reinicio nuclear cuando los pods están corrompidos después de una actualización de SDK
rm -rf ios/Pods ios/Podfile.lock ios/build
npx expo prebuild --platform ios
npx pod-install
npx expo run:ios

Cuándo usar esto:

• The sandbox is not in sync with the Podfile.lock después de un git pull.
• Agregar o eliminar un módulo nativo (expo-camera, react-native-maps, etc.).
• Actualizar Expo SDK o React Native - las versiones de pods cambian.
• La compilación del simulador falla con errores de arquitectura en Apple Silicon.
• EAS Build pasa localmente pero falla - deriva de lockfile entre compañeros de equipo.

Ejemplo de Trabajo

Paso 1 - Sabe quién es el propietario del Podfile

Bajo Expo SDK 57, npx expo prebuild genera:

# ios/Podfile (fragmento - no mantengas a mano el bloque 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

Los módulos nativos de package.json aparecen mediante autolinking - no líneas manuales pod 'SomeLibrary' a menos que la documentación de una biblioteca lo requiera explícitamente.

Paso 2 - Agregar una dependencia nativa de la forma correcta

npx expo install expo-camera
npx expo prebuild --platform ios   # aplica plugin y entradas de Podfile
npx pod-install
npx expo run:ios

Paso 3 - Higiene de Podfile.lock

# Después de actualizaciones de pods intencionales en ios/ confirmado
git add ios/Podfile.lock
git commit -m "chore(ios): pin pods after expo-camera add"

Paso 4 - Selección de simulador Apple Silicon

# Lista runtimes - prefiere simuladores arm64 (Apple Silicon)
xcrun simctl list devices available | grep -E "iPhone|Booted"
 
# Ejecuta en un simulador arm64 nombrado
npx expo run:ios --simulator "iPhone 16 Pro"

En Xcode - Producto - Destino: evita simuladores marcados como Rosetta a menos que un pod heredado force x86_64 (raro en SDK 57).

Paso 5 - Corregir "building for iOS Simulator, but linking in object file built for iOS"

# 1. Asegúrate de que no haya cachés de arquitectura mixta
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ios/Pods ios/build
 
# 2. Reinstala pods
npx pod-install
 
# 3. Reconstruye
npx expo run:ios --simulator "iPhone 16 Pro"

Si un pod de terceros solo envía binarios x86_64 precompilados, las opciones son: actualizar el pod, elegir una versión compatible con arm64, o usar temporalmente un simulador Rosetta como puente - no es una solución a largo plazo.

Lo que esto demuestra:

• npx pod-install es el punto de entrada multiplataforma que Expo documenta.
• Disciplina de lockfile previene fallos "funciona en mi Mac" en EAS.
• Alineación de arquitectura entre el runtime del simulador y los pods compilados.
• Autolinking reemplaza ediciones manuales de Podfile para módulos del ecosistema.

Profundización

pod install vs pod update

En equipos con ios/ confirmado, ejecuta pod install después de un pull - no pod update - a menos que tengas intención de actualizar deps nativos.

Expo prebuild y pods

package.json deps
      ↓
expo-modules-autolinking + RN autolinking
      ↓
ios/Podfile (generated)
      ↓
pod install → Pods/ + Podfile.lock
      ↓
YourApp.xcworkspace

Los config plugins pueden inyectar pod subspecs o use_frameworks! - ver Config Plugins. Si un plugin y una edición manual de Podfile entran en conflicto, el plugin gana en el siguiente prebuild.

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

• Host: CocoaPods y Xcode se ejecutan nativamente en Apple Silicon - Rosetta para CocoaPods no es requerido en Expo/RN moderno.
• Simulador: Los simuladores iOS predeterminados son arm64 - coincide con la arquitectura ARM del dispositivo, más rápido que Rosetta x86_64.
• "My Mac (Designed for iPad)" - destino Mac Catalyst; no es tu objetivo de app iOS de RN.
• USE_FRAMEWORKS=static - algunos scripts de CI establecen esto para Firebase; coincide con EAS eas.json env con compilaciones locales.

Fallos de CDN y red

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

# Reintenta con actualización de repo
cd ios && pod install --repo-update && cd ..
 
# Proxy corporativo persistente: establece HTTP_PROXY / HTTPS_PROXY para el shell que ejecuta pod install

Entorno Ruby

EAS Build gestiona Ruby/CocoaPods en trabajadores en la nube. Localmente:

• Ruby del sistema macOS está deprecated - Homebrew Ruby o rbenv está bien.
• npx pod-install usa la ruta esperada del proyecto; prefiere esto sobre adivinar pod en PATH.
• sudo gem install cocoapods causa dolor de permisos - usa instalaciones de gems a nivel de usuario.

Nueva Arquitectura (SDK 57 por defecto)

React Native 0.86 habilita la Nueva Arquitectura por defecto. Los Pods se compilan como Fabric/TurboModule-aware. Si una biblioteca heredada no es compatible, expo-doctor y errores de compilación aparecen temprano - corrige actualizando o reemplazando la biblioteca, no deshabilitando New Arch en producción sin un ADR.

Errores comunes

• Líneas manuales pod 'ExpoModulesCore' - duplicadas con autolinking, errores de símbolo duplicado. Corregir: elimina ediciones a mano; npx expo prebuild --clean.
• Confirmar directorio Pods/ - repo hinchado, infierno de fusión. Corregir: confirma solo Podfile.lock; ignora Pods/ en .gitignore (por defecto en Expo).
• Lockfile obsoleto después de cambio de rama - errores de sincronización de sandbox. Corregir: npx pod-install o elimina Pods/ y reinstala.
• Ejecutar pod desde directorio incorrecto - crea Pods/ extraño en la raíz del repo. Corregir: solo ejecuta dentro de ios/ o usa npx pod-install desde la raíz.
• Simulador x86_64 en Mac arm64 para dev diario - lento y errores de desajuste de arquitectura. Corregir: usa runtimes de simuladores arm64 desde Xcode - Configuración - Plataformas.
• Diferentes versiones de CocoaPods entre compañeros de equipo - variabilidad de lockfile. Corregir: documenta versión de CocoaPods en README; EAS ignora deriva local por prebuild limpio.

Alternativas

Preguntas Frecuentes

Relacionado

• iOS Basics for RN Devs - workspace, schemes, entrada en Xcode
• Prebuild Basics - cuándo ios/ se regenera
• Config Plugins - cambios nativos duraderos
• Native Module Rules - agregar paquetes de forma segura
• EAS Build Basics - compilación iOS en la nube

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