Cómo Migrar su Aplicación Capacitor a Gestor de Paquetes de Swift

Gestor de Paquetes de Swift 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 tener que reconstruir su proyecto de JavaScript code, proyecto de Android o flujo de liberación desde cero.

Esta guía es para equipos de aplicaciones. Explica cómo migrar una aplicación de iOS Capacitor de CocoaPods a SPM, qué cambia 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 construye.

¿Qué cambia en la aplicación

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

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

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, Capacitor creates a local package named 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 archiva la aplicación. La principal diferencia es que CocoaPods ya no controla 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é archivos y configuraciones personalizadas tiene tu aplicación en ios/App/Archivos y configuraciones comunes a preservar incluyen:

• App/Info.plist
• App/AppDelegate.swift
• App/SceneDelegate.swiftsi está presente
• 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 perfiles de provisión
• extensiones de la aplicación, archivos Swift nativos, archivos Objective-C o marcos incorporados

También compruebe sus dependencias Capacitor y de 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 con SPM. Actualice esos paquetes antes de migrar cuando sea posible.

Utilice el asistente de migración

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

npx cap spm-migration-assistant

Ejecute el asistente desde la raíz de su proyecto 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, abra el proyecto de iOS:

Lee el resultado del asistente antes de cerrar su terminal. Si le pide que complete pasos manuales de Xcode, hágalo antes de sincronizar de nuevo.

npx cap open ios

Completa los pasos de Xcode

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

Confirmar

1. Confirme CapApp-SPM se agrega como una dependencia de paquete local.
2. Confirme que los enlaces de destino de la aplicación vinculen los productos de paquete generados.
3. Agregue el generado debug.xcconfig a la configuración del proyecto si el asistente le pide que lo haga.
4. Resuelva cualquier advertencia de paquete en Xcode.
5. 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 a la 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 autorizaciones, las extensiones de la aplicación y la resolución de paquetes se validan allí.

If the app uses push notifications, associated domains, background modes, app groups, Firebase, or any native SDK configuration, run those flows on a simulator or device after the build succeeds.

Opción alternativa: recrear iOS con SPM

If your ios/ folder is close to the default Capacitor template, it can be faster to recreate it with SPM instead of migrating in place.

Only use this path after committing or backing up every native file and signing setting you need:

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

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

For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

npx cap add ios

Restaure luego los archivos nativos y ajustes específicos de la aplicación. Este camino te da un proyecto SPM limpio, pero es más fácil perder cambios personalizados de Xcode si no los inventariaste primero.

npx cap add ios --packagemanager SPM

For new __CAPGO_KEEP_0__ apps, __CAPGO_KEEP_1__ 8 creates iOS projects with SPM by default:

Para nuevas aplicaciones __CAPGO_KEEP_0__, __CAPGO_KEEP_1__ 8 crea proyectos de iOS con SPM por defecto:

You can still be explicit:

pod install

Todavía puede ser explícito: Clean up CocoaPods leftovers After the SPM app builds, remove leftover CocoaPods assumptions from local scripts and CI. Remove steps like: Also remove caches that only existed for CocoaPods:

• ios/App/Pods
• ios/App/Podfile.lock
• CocoaPods repositorios de especificaciones
• 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 su CI sigue construyendo App.xcworkspace, actualice a la ruta del proyecto o espacio de trabajo que existe después de la migración. No mantenga rutas de CocoaPods obsoletas solo porque la antigua tarea las utilizaba.

Solución de problemas

contexto: Página/área: Página de soporte o sección de soporte de la página de soporte premium. Rol: Título de sección o página. Visto en: página support-policy.astro. Clave de mensaje `support_policy_troubleshooting_title` (Título de solución de problemas de soporte)

El 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 CapApp-SPM Reinicie las cachés de paquetes en Xcode, compruebe que npx cap sync ios está presente como un paquete local, y ejecute

La aplicación se 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 apuntan a un archivo eliminado .xcworkspace.

Se cambiaron la firma o permisos

Compare el objetivo de Xcode migrado con el proyecto previo a la migración. Restaure el identificador de paquete, equipo, perfil de provisión, archivo de permisos, capacidades y ajustes de extensión.

Lista de verificación de migración

Antes de la migración:

• Crear una rama.
• Confirmar que la aplicación iOS actual se compila.
• Comitar el estado de trabajo.
• Inventariar archivos nativos personalizados y ajustes de firma.
• Actualice las 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 de CocoaPods solo.
• Verifica la firma de archivo y de lanzamiento.

Utiliza Capgo habilidades para la migración.

Si utiliza 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 cambiarla. 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 construcción.
• debugging-capacitor y ios-android-logs Migrar una aplicación __CAPGO_KEEP_0__ a Swift Package Manager es principalmente un cambio en la gestión de dependencias de iOS. El camino más seguro es comenzar desde una rama limpia, ejecutar

Usa estos 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.

Conclusiones

Migrar una aplicación Capacitor a Swift Package Manager es principalmente un cambio en la gestión de dependencias de iOS. El camino más seguro es comenzar desde una rama limpia, ejecutar npx cap spm-migration-assistantSi tu proyecto de iOS está muy personalizado, migra en lugar. Si está cerca del modelo de plantilla __CAPGO_KEEP_0__ predeterminado, recrear

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ Recursos npx cap add ios --packagemanager SPM Documentación de Swift Package Manager de __CAPGO_KEEP_0__

Guía de actualización 8 de __CAPGO_KEEP_0__

• Capacitor Swift Package Manager documentation
• Capacitor 8 update guide
• Usa estos 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.
• Capgo actualizaciones en vivo para Capacitor aplicaciones