Cómo migrar una aplicación Capacitor a Swift Package Manager

Capacitor 8 crea nuevos proyectos de iOS con Swift Package Manager (SPM) por defecto. Las aplicaciones existentes que aún utilizan CocoaPods también pueden migrar, 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 de migración prácticos: utilizar la asistente de migración de Capacitor o rearmar el proyecto de iOS con SPM.

¿Por qué migrar ahora?

CocoaPods se está moviendo hacia un tronco de lectura solo. El plan actual es que el tronco de CocoaPods deje de aceptar nuevos podspecs el 2 de diciembre de 2026. Los 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 del cambio.

SPM también es la dirección en la que Capacitor está moviéndose. Capacitor ha apoyado la elección de CocoaPods o SPM desde Capacitor 6, y Capacitor 8 ahora crea proyectos de iOS SPM como plantilla predeterminada.

¿Qué cambia en un proyecto Capacitor SPM?

Migrar 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 conectan a través de ios/App/Podfile, Podfile.lock, Pods/y se genera .xcworkspace.

En una aplicación SPM, Capacitor crea un paquete local llamado CapApp-SPM. Este paquete se convierte en el lugar central donde Capacitor referencia sus dependencias de plugin nativo de iOS. Los Capacitor CLI se actualizan CapApp-SPM cuando sincronices plugins, por lo 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.xcconfigEste archivo lleva configuraciones de compilación que CocoaPods proporcionaba 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

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

y plugin de Cordova en capacitor-plugin-converterSi un plugin no soporta SPM todavía, actualízalo, reemplázalo o migra el plugin primero. Los plugins de Swift simples a menudo se pueden convertir con Ionic’s

pero los plugins con diseños de Objective-C y Swift más complejos pueden requerir trabajo manual.

¿Qué guardar 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. ios/App/ Los archivos comunes a preservar de

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftSi tu aplicación tiene uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistSi utilizas Firebase
Personalizado .xcconfig archivos
Configuración de firmas, identificador de paquete, ID de equipo y configuración de perfil de provisión

También conserva cualquier archivo nativo Swift, Objective-C, marco, extensión o SDK que agregaste fuera del modelo estándar Capacitor.

Opción 1: Utiliza la asistente de migración Capacitor

Utiliza este camino cuando tu proyecto de iOS tiene ediciones nativas personalizadas que no deseas perder.

Ejecuta el asistente desde la raíz de tu proyecto Capacitor:

bunx cap spm-migration-assistant

El asistente elimina la infraestructura de CocoaPods, crea el paquete local, genera referencias de paquete a partir de tus plugins instalados y crea los archivos de configuración de SPM generados. CapApp-SPM Cuando termine, abre el proyecto:

El asistente elimina la infraestructura de CocoaPods, crea el paquete local, genera referencias de paquete a partir de tus plugins instalados y crea los archivos de configuración de SPM generados.

bunx cap open ios

Entonces, sigue los pasos manuales de Xcode impresos por el asistente. En la mayoría de los proyectos esto significa:

Agregar CapApp-SPM como una dependencia de paquete local.
Agregar el generado debug.xcconfig a la configuración de la aplicación.
Resolver cualquier advertencia sobre plugins que no pudieron ser convertidos a SPM.
Construye la aplicación desde Xcode una vez antes de actualizar CI.

Después de que el proyecto de Xcode se construye, sincroniza nuevamente:

bunx cap sync ios

Opción 2: Re-estructura el proyecto de iOS con SPM

Utiliza este camino cuando tu ios/ carpeta esté cerca del template predeterminado Capacitor y puedas restaurar archivos personalizados con seguridad después.

Primero, asegúrate de que los archivos listados en la sección de respaldo estén comprometidos o copiados en algún lugar seguro. Luego elimina y recrea el proyecto de iOS con SPM:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Restablezca los archivos nativos que necesita su aplicación, luego abra el proyecto:

bunx cap open ios

Esta ruta suele ser más limpia que una migración en lugar porque le da a usted un Capacitor 8 plantilla de iOS fresca. El contrapeso es que debe aplicar con cuidado la firma, las concesiones, los archivos de Firebase, los cambios en el código nativo y cualquier ajuste personalizado de Xcode.

Nuevas Capacitor aplicaciones

Para una nueva aplicación, Capacitor 8 utiliza SPM por defecto cuando agrega iOS:

bunx cap add ios

Si necesita ser explícito, puede pasar la opción del administrador de paquetes:

bunx cap add ios --packagemanager SPM

Actualice CI después de la migración

Una vez que la aplicación se construye localmente, actualice CI/CD para que ya no asuma CocoaPods.

Elimine los pasos que ejecutan:

pod install

También elimine las cachés para:

ios/App/Pods
ios/App/Podfile.lock
Los repositorios de especificaciones de CocoaPods, si su flujo de trabajo las cacheó solo para esta aplicación

Mantenga sus pasos de construcción web regulares y Capacitor sincronizados. Un trabajo de iOS típico debe instalar las dependencias de JavaScript, construir los activos web, sincronizar Capacitor, y luego construir con Xcode:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Lista de verificación de migración

Antes de la migración:

Crear una nueva rama de Git.
Comitar la aplicación actual.
Verificar que cada plugin instalado admite SPM.
Grabar archivos y configuraciones de firmado iOS personalizados.
Confirmar que la aplicación se compila antes de la migración.

Durante la migración:

Ejecutar bunx cap spm-migration-assistant o re-estructurar ios/.
Agregar CapApp-SPM en Xcode si es necesario.
Agregar debug.xcconfig en 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 install de 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, resetear cachés de paquetes desde Xcode y ejecutar 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 construye localmente pero falla en CI, compruebe las suposiciones anticuadas de CocoaPods. Las causas comunes son un camino de construcción forzado, un comando estancado, o caché de construcciones anteriores. .xcworkspace Conclusión pod install Migrar una aplicación __CAPGO_KEEP_0__ a Swift Package Manager es principalmente sobre reemplazar la configuración de dependencias de iOS. Pods/ asume las referencias de dependencias,

reemplaza la configuración de construcción generada de CocoaPods, y CI ya no necesita

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM Para proyectos cercanos al modelo de plantilla predeterminado, una reestructuración limpia de SPM es a menudo más rápida y fácil de razonar. debug.xcconfig Para proyectos cercanos al modelo de plantilla predeterminado, una reestructuración limpia de SPM es a menudo más rápida y fácil de razonar. pod install.

Para proyectos cercanos al modelo de plantilla predeterminado, una reestructuración limpia de SPM es a menudo más rápida y fácil de razonar. bunx cap spm-migration-assistantPara proyectos cercanos al modelo de plantilla predeterminado, una reestructuración limpia de SPM es a menudo más rápida y fácil de razonar.

Recursos

Sigue adelante desde Cómo Migrar una Aplicación Capacitor a Swift Package Manager

Si estás utilizando Cómo Migrar una Aplicación Capacitor a Swift Package Manager para planificar la migración y las operaciones empresariales, conecta con Capgo Enterprise para el flujo de trabajo del producto en Capgo Enterprise Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Ionic Enterprise Plugin, Capgo Alternativas para el flujo de trabajo del producto en Capgo Alternativas, Capgo Consultoría para el flujo de trabajo del producto en Capgo Consultoría, y Capgo Soporte Premium para el flujo de trabajo del producto en Capgo Soporte Premium.