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

Swift Package Manager es la dirección por defecto para proyectos de iOS Capacitor. Si su aplicación sigue utilizando CocoaPods, puede migrar la aplicación en sí a SPM sin reconstruir su proyecto de JavaScript code, Android o flujo de lanzamiento desde cero.

Esta guía está destinada a equipos de aplicaciones. Explica cómo migrar una aplicación de iOS Capacitor de CocoaPods a SPM, qué cambios hace el asistente de migración, qué aún necesita comprobar en Xcode y cómo limpiar CI después de que la aplicación se compile.

¿Qué cambia en la aplicación?

A CocoaPods-based Capacitor app depends on files such as:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Una aplicación Capacitor basada en SPM mueve la configuración de dependencias de iOS al Gestor de Paquetes de Swift. Durante la migración, Capacitor crea un paquete local denominado CapApp-SPM y utiliza para conectar el objetivo de la aplicación con Capacitor y las dependencias nativas instaladas.

La compilación web sigue funcionando de la misma manera. Todavía ejecutas una compilación web, sincronizas Capacitor, abres Xcode y archivas la aplicación. La principal diferencia es que CocoaPods ya no posee el gráfico de dependencias de iOS.

Antes de migrar

Comienza desde una rama limpia y asegúrate de que la aplicación actual se compile antes de cambiar los administradores de dependencias:

git status
npm run build
npx cap sync ios

Luego, haz un commit del estado de trabajo. La migración toca los archivos de proyecto de iOS generados, por lo que tener un punto de rollback limpio es importante.

Después, revisa qué ha personalizado tu aplicación bajo ios/App/Archivos y configuraciones comunes a preservar incluyen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si está presente
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si utilizas Firebase
personalizado .xcconfig archivos
configuración de firma, identificador de paquete, ID de equipo y perfiles de provisión
extensiones de la aplicación, archivos Swift nativos, archivos Objective-C o marcos incorporados

También comprueba tus dependencias de Capacitor y Cordova instaladas. Una migración de SPM de nivel de aplicación puede estar bloqueada por una dependencia nativa que no tiene un camino compatible de SPM. Actualiza esos paquetes antes de migrar cuando sea posible.

Utiliza el asistente de migración

Para la mayoría de las aplicaciones existentes, comienza con el asistente de migración oficial de Capacitor:

npx cap spm-migration-assistant

Ejecútalo desde la raíz de tu proyecto de Capacitor. El asistente elimina la integración de CocoaPods, crea el paquete local, genera referencias de paquete para las dependencias nativas instaladas y agrega la configuración generada necesaria por el proyecto de iOS. CapApp-SPM Después de que termine, abre el proyecto de iOS:

Lee la salida del asistente antes de cerrar tu terminal. Si te pide que completes pasos manuales de Xcode, hazlo antes de sincronizar de nuevo.

npx cap open ios

Finaliza los pasos de Xcode

En Xcode, comprueba la configuración del proyecto y objetivo de la aplicación:

Confirma

Confirmar CapApp-SPM se agrega como dependencia de paquete local.
Confirme que los enlaces de destino de la aplicación vinculan los productos de paquete generados.
Agregar los generados debug.xcconfig a la configuración del proyecto si el asistente lo solicita.
Resuelva cualquier advertencia de paquete en Xcode.
Construya la aplicación una vez desde Xcode.

Si Xcode no puede resolver paquetes, utilice Archivo > Paquetes > Reiniciar Cachés de Paquetes, luego resuelva los paquetes de nuevo.

Sincronice y construya de nuevo

Después de que Xcode esté configurado, regrese al terminal y sincronice Capacitor:

npx cap sync ios

Luego construya desde Xcode de nuevo. No trate la migración como hecha hasta que una construcción limpia funcione desde Xcode, porque la firma de lanzamiento, las entidades, las extensiones de la aplicación y la resolución de paquetes se validan allí.

If el app utiliza notificaciones push, dominios asociados, modos de fondo, grupos de app, Firebase, o cualquier configuración nativa SDK, ejecuta esas flujo en un simulador o dispositivo después de que el build tenga éxito.

Opcional: recrea iOS con SPM

Si tu ios/ carpeta está cerca del template predeterminado Capacitor, puede ser más rápido recrearla con SPM en lugar de migrar en su lugar.

Sólo utiliza este camino después de haber cometido o respaldado todos los archivos y ajustes de firma nativos que necesitas:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Luego restaura tus archivos y ajustes nativos específicos de la app. Este camino te da un proyecto SPM limpio, pero es más fácil perder cambios personalizados de Xcode si no los inventariaste primero.

Para nuevas Capacitor apps, Capacitor 8 crea proyectos iOS con SPM por defecto:

npx cap add ios

Todavía puedes ser explícito:

npx cap add ios --packagemanager SPM

Elimina residuos de CocoaPods

Después de que el app de SPM se construye, elimina suposiciones de CocoaPods de scripts locales y CI.

Elimina pasos como:

pod install

También elimina cachés que solo existían para CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repositorios de especificaciones de CocoaPods
Las claves de caché de CI se basan en el archivo Podfile

Un flujo de CI básico después de la migración debería instalar las dependencias de JavaScript, compilar la aplicación web, sincronizar Capacitor, y compilar con Xcode:

npm ci
npm run build
npx cap sync ios

Si tu CI sigue compilando App.xcworkspace, actualiza a la ruta del proyecto o espacio de trabajo que existe después de la migración. No mantengas rutas de CocoaPods obsoletas solo porque la antigua tarea las utilizó.

Solución de problemas

El asistente advierte sobre una dependencia incompatible

Actualiza la dependencia primero y ejecuta el asistente de nuevo. Si no existe una versión compatible con SPM, mantén la aplicación en CocoaPods hasta que reemplaces esa dependencia o el mantenedor agregue soporte para SPM.

Xcode no puede resolver paquetes

Reinicia las cachés de paquetes en Xcode, verifica que CapApp-SPM esté presente como un paquete local, y ejecuta npx cap sync ios de nuevo.

The app compila localmente pero CI falla

Busque suposiciones de CocoaPods antiguas: pod install, Pods/ cachés, Podfile.lock claves de caché, o comandos de compilación que apuntan a un archivo eliminado .xcworkspace.

Se cambiaron la firma o permisos

Compare el objetivo de Xcode migrado con el proyecto pre-migración. Restaure el identificador de paquete, equipo, perfil de provisión, archivo de permisos, capacidades y ajustes de extensiones.

Lista de verificación de migración

Antes de la migración:

Crear una rama.
Confirmar que la aplicación iOS actual compila.
Comitar el estado de trabajo.
Realice un inventario de archivos nativos personalizados y ajustes de firma.
Actualice dependencias nativas que ya tienen versiones más recientes compatibles con SPM.

Durante la migración:

Ejecutar npx cap spm-migration-assistant.
Abrir el proyecto con npx cap open ios.
Agregar CapApp-SPM en Xcode si es necesario.
Agregar debug.xcconfig en Xcode si es necesario.
Resolver advertencias de paquetes.
Ejecutar npx cap sync ios.

Después de la migración:

Compilar la aplicación desde Xcode.
Prueba capacidades nativas en un simulador o dispositivo.
Elimina comandos de CocoaPods de CI.
Elimina cachés solo de CocoaPods.
Verifica la firma de archivo y lanzamiento.

Utiliza Capgo Habilidades para la migración

Si utilizas agentes de IA para manejar la migración, comienza desde Capgo Habilidades en lugar de una solicitud en blanco. Las habilidades más útiles para este trabajo son:

capacitor-best-practices para revisar la estructura de la aplicación antes de cambiar ios/.
cocoapods-to-spm para planificar los pasos de migración de SPM y Xcode.
capacitor-ci-cd para eliminar suposiciones de CocoaPods de las líneas de pipeline de compilación.
debugging-capacitor y ios-android-logs To investigar problemas solo de dispositivo después de la migración.

Utilícelos antes de cambiar el proyecto de iOS para que el agente audite archivos nativos, CI y compatibilidad de dependencias en lugar de ejecutar solo el comando de migración.

Conclusión

Migrar una aplicación Capacitor a Swift Package Manager es principalmente un cambio de gestión de dependencias de iOS. El camino más seguro es empezar desde una rama limpia, ejecutar npx cap spm-migration-assistantterminar los pasos manuales de Xcode, sincronizar nuevamente y eliminar CocoaPods de CI solo después de que la aplicación se compile.

Si su proyecto de iOS está muy personalizado, migre en lugar. Si está cerca del modelo de plantilla Capacitor predeterminado, recrear ios/ con npx cap add ios --packagemanager SPM puede ser más limpio.

Cómo Migrar su Aplicación Capacitor a Swift Package Manager