Cómo Migrar Su Capacitor App a Mánager de Paquetes de Swift

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

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

¿Qué cambia en la aplicación?

Una aplicación Capacitor basada en CocoaPods depende de archivos como:

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 iOS a Swift Package Manager. Durante la migración, Capacitor crea un paquete local llamado 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 ejecuta una compilación web, sincroniza Capacitor, abre Xcode y archiva la aplicación. La principal diferencia es que CocoaPods ya no es dueño del gráfico de dependencias iOS.

Antes de migrar

Comience desde una rama limpia y asegúrese de que la aplicación actual se construya antes de cambiar los administradores de dependencias:

git status
npm run build
npx cap sync ios

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

Próximo, revise qué tu aplicación ha personalizado bajo ios/App/. Archivos y configuraciones comunes para 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
archivos personalizados .xcconfig archivos
configuraciones de firma, identificador de paquete, ID de equipo y perfiles de provisión
extensiones de aplicación, archivos nativos Swift, archivos Objective-C o frameworks incorporados

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

Usa la asistente de migración

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

npx cap spm-migration-assistant

Correlo desde la raíz de tu proyecto Capacitor. El asistente elimina la integración de CocoaPods, crea el local CapApp-SPM paquete, genera referencias de paquete para dependencias nativas instaladas y agrega la configuración generada necesaria para el proyecto de iOS.

Una vez que termine, abra el proyecto de iOS:

npx cap open ios

Lea la salida del asistente antes de cerrar su terminal. Si le pide que complete pasos manuales de Xcode, hágalos antes de sincronizar de nuevo.

Finalice los pasos de Xcode

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

Confirmar CapApp-SPM se agrega como una dependencia de paquete local.
Confirme que el objetivo de la aplicación vincula los productos de paquete generados.
Agregar el generado debug.xcconfig a la configuración del proyecto si el asistente le pide que lo haga.
Resuelva cualquier advertencia de paquete en Xcode.
Compile la aplicación una vez desde Xcode.

If Xcode no puede resolver paquetes, utilice Archivo > Paquetes > Reiniciar cachés de paquetesEntonces, resuelve los paquetes de nuevo.

Sincronice y construye de nuevo

Después de configurar Xcode, regrese a la terminal y sincronice Capacitor:

npx cap sync ios

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

Si la aplicación utiliza notificaciones push, dominios asociados, modos de fondo, grupos de aplicación, Firebase o cualquier configuración nativa SDK, ejecute esas flujos en un simulador o dispositivo después de que la construcción tenga éxito.

Opción alternativa: recrear iOS con SPM

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

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

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

Luego restaure sus archivos y ajustes de la aplicación nativos. Este camino le da un proyecto de SPM limpio, pero es más fácil perder cambios personalizados de Xcode si no los inventarió primero.

For nuevos Capacitor apps, Capacitor 8 crea proyectos de iOS con SPM por defecto:

npx cap add ios

Podrás ser explícito:

npx cap add ios --packagemanager SPM

Elimina los residuos de CocoaPods

Después de que la aplicación de SPM se compile, elimina las suposiciones de CocoaPods de los scripts locales y de CI.

Elimina pasos como:

pod install

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

ios/App/Pods
ios/App/Podfile.lock
Repositorios de especificaciones de CocoaPods
Claves de caché de CI basadas en el archivo Podfile

Un flujo de CI básico después de la migración debería instalar 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 del espacio de trabajo que existe después de la migración. No mantengas rutas de CocoaPods obsoletas solo porque la antigua tarea las utilizaba.

Solución de problemas

The asistente advierte sobre una dependencia incompatible

Actualice la dependencia primero y ejecute el asistente de nuevo. Si no existe una versión compatible con SPM, mantenga la aplicación en CocoaPods hasta que reemplace esa dependencia o el mantenedor agregue soporte para SPM.

Xcode no puede resolver paquetes

Reinicie las cachés de paquetes en Xcode, compruebe que CapApp-SPM esté presente como paquete local, y ejecute npx cap sync ios de nuevo.

La aplicación compila localmente pero falla en CI

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

Se han cambiado la firma o las autorizaciones

Compare el objetivo migrado de Xcode con el proyecto previo a la migración. Restaure el identificador de la aplicación, el equipo, el perfil de provisión, el archivo de autorizaciones, las capacidades y los 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 se compila correctamente.
Comitar el estado de trabajo.
Inventariar archivos nativos personalizados y ajustes de firma.
Actualizar 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:

Construir la aplicación desde Xcode.
Probar capacidades nativas en un simulador o dispositivo.
Eliminar comandos de CocoaPods de CI.
Eliminar cachés solo de CocoaPods.
Verificar firmado de archivo y lanzamiento.

Usar Capgo habilidades para la migración

Si utiliza agentes de inteligencia artificial para manejar la migración, comience desde Habilidades Capgo 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 y seguimiento de Xcode.
capacitor-ci-cd para eliminar suposiciones de CocoaPods de las líneas de compilación.
debugging-capacitor y ios-android-logs para investigar problemas de dispositivo solo después de la migración.

Utilícelas 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 Capacitor aplicación al Gestor de Paquetes de Swift es principalmente un cambio de gestión de dependencias de iOS. El camino más seguro es comenzar 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 Gestor de Paquetes de Swift