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

Capacitor 8 crea nuevos proyectos de iOS con Swift Package Manager (SPM) por defecto. Las aplicaciones existentes que aún utilizan CocoaPods pueden migrar también, pero el camino más seguro depende de cuánta personalización nativa de iOS tenga la aplicación.

Esta guía pasa por lo que cambia, qué respaldar y los dos caminos 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 solo lectura. 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 dependan del tronco no se publicarán allí después de la transición.

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

¿Qué cambia en un proyecto de Capacitor SPM

Migrar desde 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 Capacitor permanecen iguales.

CapApp-SPM reemplaza el archivo Podfile

En una aplicación CocoaPods, las dependencias de iOS se cablean a través de ios/App/Podfile, Podfile.lock, Pods/, y el archivo generado .xcworkspace.

In una aplicación SPM, Capacitor crea un paquete local denominado CapApp-SPM. Este paquete se convierte en el lugar central donde Capacitor referencia sus dependencias de plugin nativo de iOS. El Capacitor CLI se actualiza CapApp-SPM cuando sincronices plugins, así 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.xcconfig. Este 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.

Todos los plugins deben soportar SPM

No se pueden mezclar CocoaPods y SPM en el mismo Capacitor proyecto iOS. Antes de migrar, revise cada Capacitor y plugin de Cordova en package.json.

Si un plugin no soporta SPM aún, actualícelo, reemplázelo o migre el plugin primero. Los plugins de Swift simples a menudo pueden convertirse con Ionic’s capacitor-plugin-converter, pero los plugins con diseños de Objective-C y Swift más complejos pueden necesitar trabajo manual.

¿Qué guardar primero

Comience desde una rama de Git limpia y comita su estado actual antes de tocar el proyecto iOS. Luego, liste los archivos nativos en los que su aplicación depende.

Archivos comunes a preservar de ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si su aplicación tiene uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si utiliza Firebase
Personalizado .xcconfig archivos
Configuración de firma, identificador de paquete, ID de equipo y configuración de perfil de provisión

También preserva cualquier archivo nativo de Swift, Objective-C, marco, 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 SPM generados. CapApp-SPM Cuando termine, abre el proyecto:

Luego sigue los pasos manuales de Xcode impresos 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 los generados
Los generados debug.xcconfig To la configuración del aplicación.
Resolver cualquier advertencia sobre plugins que no pudieron ser convertidos a SPM.
Construya la aplicación desde Xcode una vez antes de actualizar CI.

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

bunx cap sync ios

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

Use este camino cuando su ios/ carpeta esté cerca del template predeterminado Capacitor y pueda restaurar archivos personalizados con seguridad después.

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 su aplicación necesita, 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 una 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 la fuente nativa y cualquier ajuste de Xcode personalizado.

Nuevas Capacitor aplicaciones

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

bunx cap add ios

If necesitas ser explícito, puedes 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, actualiza CI/CD para que ya no asuma CocoaPods.

Eliminar pasos que ejecutan:

pod install

También elimina cachés para:

ios/App/Pods
ios/App/Podfile.lock
Repositorios de especificaciones de CocoaPods, si tu flujo de trabajo los cacheó solo para esta aplicación

Mantén tus pasos de construcción web regulares y Capacitor sincronización. Un trabajo de iOS típico debería instalar dependencias de JavaScript, construir 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 de trabajo actual.
Verificar que cada plugin instalado admita SPM.
Grabar archivos iOS personalizados y configuraciones de firma.
Confirmar que la aplicación se construye antes de la migración.

Durante la migración:

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

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

Solución de problemas

Si Xcode no puede resolver paquetes, reinicie las cachés de paquetes desde Xcode y ejecute bunx cap sync ios de nuevo.

Si la migración falla debido a un complemento, compruebe si el complemento tiene una versión más reciente con soporte de SPM. Para los complementos que mantenga, migre el paquete del complemento primero y luego regrese a la migración de la aplicación.

Cuando la aplicación se compila localmente pero CI falla, busque suposiciones CocoaPods antiguas. Las causas comunes son un camino de compilación forzado, una caché .xcworkspace stale pod install comando, o caché Pods/ desde construcciones 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 reemplaza la configuración de construcción generada de CocoaPods, y el CI 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 limpia de SPM a menudo es 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 del Plugin Empresarial de Ionic Para el flujo de trabajo del producto en Alternativas del Plugin Empresarial de Ionic, Alternativas de Capgo Para el flujo de trabajo del producto en Alternativas de Capgo, Capgo Consulting 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