Capacitor 8 crea nuevos proyectos de iOS con Swift Package Manager (SPM) por defecto. Las aplicaciones existentes que aún utilizan CocoaPods pueden migrar también, pero el camino más seguro depende de cuánta personalización nativa de iOS tenga tu aplicación.
Este guía te guía a través de los cambios, qué respaldar y los dos métodos prácticos de migración: utilizar la asistente de migración de Capacitor o rearmar el proyecto de iOS con SPM.
¿Por qué migrar ahora?
CocoaPods está moviéndose hacia un tronco de solo lectura. El plan actual es que el tronco de CocoaPods deje de aceptar nuevos podspecs en 2 de diciembre de 2026Los builds existentes deberían seguir funcionando, pero las nuevas versiones y actualizaciones de dependencias que dependen de la rama principal no se publicarán allí después de la transición.
SPM también es la dirección a la que se está moviendo Capacitor. Capacitor ha apoyado la elección de CocoaPods o SPM desde Capacitor 6, y Capacitor 8 ahora crea proyectos de iOS SPM como plantilla por defecto.
¿Qué cambia en un proyecto Capacitor de SPM
La migración de CocoaPods a SPM reemplaza la capa de dependencias de iOS. La aplicación web, el proyecto de Android y la mayoría de los comandos de flujo de trabajo de Capacitor siguen siendo los mismos.
CapApp-SPM reemplaza el archivo Podfile
En una aplicación CocoaPods, las dependencias de iOS se cablean a través de ios/App/Podfile, Podfile.lock, Pods/y el archivo generado .xcworkspace.
In una aplicación de SPM, Capacitor crea un paquete local llamado CapApp-SPMEste paquete se convierte en el lugar central donde Capacitor referencia sus dependencias de plugin nativo de iOS. El Capacitor CLI se actualiza CapApp-SPM cuando sincronices plugins, así que tratalo como salida generada y evita editarla a mano.
debug.xcconfig reemplaza la configuración de Pods
El asistente de migración también crea un archivo generado debug.xcconfig. Este archivo contiene ajustes de compilación que CocoaPods proporcionaba anteriormente a través de sus archivos xcconfig generados.
Después de la migración, es posible que debas agregar debug.xcconfig a la configuración del proyecto de Xcode si el asistente te dice que lo hagas.
Cada plugin debe soportar SPM
No puedes mezclar CocoaPods y SPM en el mismo Capacitor proyecto iOS. Antes de migrar, verifica cada Capacitor y plugin de Cordova en package.json.
Si un plugin no soporta SPM todavía, actualízalo, reemplázalo o migra el plugin primero. Los plugins de Swift simples a menudo pueden convertirse con Ionic’s capacitor-plugin-converter, pero los plugins con diseños de Objective-C y Swift más complejos pueden requerir trabajo manual.
¿Qué respaldar primero?
Comienza desde una rama de Git limpia y haz un commit de tu estado actual antes de tocar el proyecto iOS. Luego, enumera los archivos nativos en los que tu aplicación depende.
Archivos comunes para preservar de ios/App/ incluyen:
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swift, si tu aplicación tiene unoApp/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plist, si utiliza Firebase- Personalizado
.xcconfigarchivos - Configuración de firma, identificador de paquete, ID de equipo y configuración de perfil de provisión
También preserva cualquier archivo nativo Swift, Objective-C, framework, extensión o SDK que agregó fuera del template estándar Capacitor.
Opción 1: Utilice la asistente de migración Capacitor
Utilice este camino cuando su proyecto de iOS tenga ediciones nativas personalizadas que no quiere perder.
Ejecutar el asistente desde la raíz de su proyecto Capacitor:
bunx cap spm-migration-assistantEl asistente elimina la infraestructura de CocoaPods, crea el paquete local, genera referencias de paquete a partir de sus plugins instalados y crea los archivos de configuración SPM generados. CapApp-SPM Cuando termine, abra el proyecto:
Luego siga los pasos manuales de Xcode impresas por el asistente. En la mayoría de los proyectos esto significa:
bunx cap open iosOpción 2: Utilice el __CAPGO_KEEP_0__ template para iOS
- Agregar
CapApp-SPMcomo dependencia de paquete local. - Agregar el generado
debug.xcconfiga la configuración de la aplicación. - Resolver cualquier advertencia sobre plugins que no pudieron ser convertidos a SPM.
- Construir la aplicación desde Xcode una vez antes de actualizar CI.
Después de que el proyecto de Xcode se construye, sincronice nuevamente:
bunx cap sync iosOpción 2: Re-estructurar el proyecto de iOS con SPM
Utilice este camino cuando su ios/ carpeta esté cerca del template predeterminado Capacitor y pueda restaurar archivos personalizados con seguridad después.
Primero, asegúrese de que los archivos listados en la sección de respaldo estén comprometidos o copiados en algún lugar seguro. Luego elimine y vuelva a crear el proyecto de iOS con SPM:
rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync iosRestaurar los archivos nativos que su aplicación necesita, luego abra el proyecto:
bunx cap open iosThis path is often cleaner than an in-place migration because it gives you a fresh Capacitor 8 iOS template. The tradeoff is that you must carefully reapply signing, entitlements, Firebase files, native source changes, y cualquier ajuste personalizado de Xcode.
Nuevos Capacitor apps
Para una nueva aplicación, Capacitor 8 utiliza SPM por defecto cuando se agrega iOS:
bunx cap add iosSi necesita ser explícito, puede pasar la opción del administrador de paquetes:
bunx cap add ios --packagemanager SPMActualizar CI después de la migración
Una vez que la aplicación se compila localmente, actualice CI/CD para que ya no asuma CocoaPods.
Eliminar pasos que ejecutan:
pod installTambién elimine cachés para:
ios/App/Podsios/App/Podfile.lock- Los repositorios de especificaciones de CocoaPods, si su flujo de trabajo los cacheó solo para esta aplicación
Mantenga sus pasos de compilación web regulares y Capacitor sincronizados. Un trabajo de iOS típico debe instalar dependencias de JavaScript, compilar los activos web, sincronizar Capacitor, y luego compilar con Xcode:
bun install --frozen-lockfile
bun run build
bunx cap sync iosLista de verificación de migración
Antes de la migración:
- Crear una nueva rama de Git.
- Comitar la aplicación de trabajo actual.
- Verificar que cada plugin instalado admite SPM.
- Grabar archivos iOS personalizados y configuraciones de firma.
- Confirmar que la aplicación se construye antes de la migración.
Durante la migración:
- Ejecutar
bunx cap spm-migration-assistanto volver a esqueletizarios/. - Agregar
CapApp-SPMen Xcode si es necesario. - Agregar
debug.xcconfigen Xcode si es necesario. - Restaurar archivos nativos específicos de la aplicación.
- Ejecutar
bunx cap sync ios.
Después de la migración:
- Construir y ejecutar la aplicación en Xcode.
- Eliminar archivos CocoaPods sobrantes.
- Eliminar
pod installde CI. - Verificar que la firma de lanzamiento sigue funcionando.
- Ejecutar la aplicación en al menos un simulador y un dispositivo real antes de enviar.
Solución de problemas
Si Xcode no puede resolver paquetes, reinicia las cachés de paquetes desde Xcode y ejecuta bunx cap sync ios de nuevo.
Si la migración falla debido a un plugin, compruebe si el plugin tiene una versión más reciente con soporte de SPM. Para los plugins que mantenga, migre el paquete del plugin primero y luego regrese a la migración de la aplicación.
Cuando la aplicación se compila localmente pero CI falla, compruebe suposiciones de CocoaPods antiguas. Las causas comunes son un camino de compilación forzado, un comando .xcworkspace obsoleto, o caché pod install de ediciones anteriores. Pods/ Conclusión
Migrar una __CAPGO_KEEP_0__ aplicación a Swift Package Manager es principalmente sobre reemplazar la configuración de dependencias de iOS.
Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM reemplaza la configuración de compilación de CocoaPods generada, y CI ya no necesita debug.xcconfig Para proyectos de iOS personalizados, comience con pod install.
Para proyectos cercanos a la plantilla predeterminada, una reestructuración de SPM limpia es a menudo más rápida y fácil de razonar. bunx cap spm-migration-assistantRecursos
