¿Cómo Migrar una Aplicación Capacitor a Gerente de Paquetes de Swift

Capacitor 8 crea nuevos proyectos de iOS con el Gestor de Paquetes de Swift (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 tiene tu aplicación.

Esta guía te guía a través de los cambios, qué respaldar y de los dos caminos prácticos de migración: utilizar el 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 lectura solo. El plan actual es que el tronco de CocoaPods deje de aceptar nuevos podspecs el 2 de diciembre de 2026. Los compilados existentes deberían seguir funcionando, pero las nuevas versiones y actualizaciones de dependencias que dependen del tronco no se publicarán allí después de la transición.

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

¿Qué cambia en un proyecto de 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 de CocoaPods, las dependencias de iOS se conectan a través de ios/App/Podfile, Podfile.lock, Pods/y se generan .xcworkspace.

In una aplicación SPM, Capacitor crea un paquete local denominado CapApp-SPMEste paquete se convierte en el lugar central donde Capacitor referencia las dependencias de plugins nativos de iOS. El Capacitor CLI se actualiza CapApp-SPM cuando sincronices plugins, así que tratalo como salida generada y evita editarla a mano.

xcconfig de depuración 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.

Si 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 capacitor-plugin-converterpero los plugins con diseños más complejos de Objective-C y Swift pueden necesitar trabajo manual.

¿Qué guardar primero

Comienza desde una rama Git limpia y haz un commit de tu estado actual antes de tocar el proyecto de iOS. Luego, enumera los archivos nativos en los que tu aplicación depende.

Archivos comunes a preservar desde ios/App/ include:

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
Archivos personalizados .xcconfig Archivos
Configuración de firmas, 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 agregaste fuera del template 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:

Luego sigue los pasos manuales de Xcode impresas por el asistente. En la mayoría de los proyectos esto significa:

bunx cap open ios

Agrega

como una dependencia de paquete local. CapApp-SPM Agrega el generado
a la configuración de la aplicación. debug.xcconfig Resuelve cualquier advertencia sobre plugins que no pudieron ser convertidos a SPM.
Compila la aplicación desde Xcode una vez antes de actualizar CI.
Después de que el proyecto de Xcode se compile, sincroniza nuevamente:

After the Xcode project builds, sync again:

bunx cap sync ios

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

Utilice este camino cuando su ios/ directorio está cerca del modelo predeterminado Capacitor y puede restaurar archivos personalizados con seguridad.

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 ios

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

bunx cap open ios

Este camino a menudo es más limpio que una migración en lugar porque le da un Capacitor 8 plantilla de iOS fresca. El contrapunto es que debe aplicar con cuidado la firma, las autorizaciones, los archivos de Firebase, los cambios en el código nativo y cualquier ajuste de Xcode personalizado.

Aplicaciones nuevas Capacitor

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

bunx cap add ios

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

bunx cap add ios --packagemanager SPM

Actualizar 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 sincronización de web regulares y Capacitor. Un trabajo de iOS típico debería instalar las dependencias de JavaScript, compilar los activos de web, sincronizar Capacitor, y luego compilar 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:

Cree una nueva rama de Git.
Comite la aplicación de trabajo actual.
Verifique que cada plugin instalado admita SPM.
Registre archivos y ajustes de firma de iOS personalizados.
Confirme que la aplicación se compila antes de la migración.

Durante la migración:

Ejecutar bunx cap spm-migration-assistant o re-scaffold 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:

Compilar y ejecutar la aplicación en Xcode.
Eliminar archivos CocoaPods sobrantes.
Eliminar pod install de CI.
Verifique que la firma de lanzamiento sigue funcionando.
Corra la aplicación en al menos un simulador y un dispositivo real antes de enviarla.

Solución de problemas

Si Xcode no puede resolver los paquetes, reinicie las cachés de paquetes desde Xcode y vuelva a 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 causas de CocoaPods antiguas. Las causas comunes son un camino de construcción forzado, una orden .xcworkspace obsoleta pod install o caché Pods/ de ediciones anteriores.

Conclusión

Migrar una aplicación Capacitor a Swift Package Manager es principalmente sobre reemplazar la configuración de dependencias de iOS. CapApp-SPM tomando el control de las referencias de dependencias, debug.xcconfig sustituye la configuración de compilación CocoaPods generada, y ya no necesita pod install.

Para proyectos de iOS personalizados, comience con bunx cap spm-migration-assistant. Para proyectos cercanos a la plantilla predeterminada, una reestructuración SPM limpia es a menudo más rápida y fácil de razonar.

Recursos

Siga adelante desde Cómo Migrar una Aplicación Capacitor a Gestor de Paquetes Swift

Si está utilizando Cómo Migrar una Aplicación Capacitor a Gestor de Paquetes Swift para planificar la migración y las operaciones empresariales, conecte con Capgo Empresa para el flujo de trabajo del producto en Capgo Empresa Alternativas de plugins de Ionic Empresa para el flujo de trabajo del producto en Alternativas de plugins de Ionic Empresa 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.

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