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. Los proyectos 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 tiene su aplicación.

Esta guía pasa por lo que cambia, qué guardar y 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 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 builds 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 Capacitor se está moviendo. Capacitor ha apoyado la elección de CocoaPods o SPM desde Capacitor 6, y Capacitor 8 ahora crea proyectos de iOS SPM como el modelo de 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 el archivo generado .xcworkspace.

In una aplicación de 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.

debug.xcconfig 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-converter, pero los plugins con diseños de Objective-C y Swift más complejos pueden necesitar trabajo manual.

¿Qué respaldar 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.swift, si tu aplicación tiene uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si utilizas Firebase
Personalizado .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 tenga 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 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.
Construye la aplicación desde Xcode una vez antes de actualizar CI.
Después de que el proyecto de Xcode se construye, sincroniza nuevamente:

protectedTokens

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 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 cree 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 suele ser más limpio que una migración en lugar porque le da un modelo Capacitor fresco de iOS 8. El contrapeso es que debe aplicar con cuidado la firma, las autorizaciones, los archivos de Firebase, los cambios en la fuente nativa y cualquier ajuste personalizado de Xcode.

Nuevos Capacitor apps

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

Además, 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 construcción web regulares y Capacitor de sincronización. Un trabajo de iOS típico debería instalar las dependencias de JavaScript, construir los 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 soporte SPM.
Grabar archivos y configuraciones de firmado iOS personalizados.
Confirmar que la aplicación se construya antes de la migración.

Durante la migración:

Correr 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 de CocoaPods sobrantes.
Eliminar pod install de CI.
Verifica que la firma de la versión sigue funcionando.
Ejecuta 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, reinicia las cachés de paquetes desde Xcode y ejecuta bunx cap sync ios de nuevo.

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

Cuando la aplicación compila localmente pero falla en CI, verifica causas de CocoaPods antiguas. Las causas comunes son un camino de compilación forzado, un comando .xcworkspace estancado, o caché pod install de ediciones anteriores. Pods/ Conclusión

Migrar una aplicación __CAPGO_KEEP_0__ a Swift Package Manager es principalmente sobre reemplazar la configuración de dependencias de iOS.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM gestiona las referencias de dependencias debug.xcconfig reemplaza la configuración de compilación de CocoaPods generada y ya no necesita pod install.

Para proyectos de iOS personalizados, comience con bunx cap spm-migration-assistant. Para proyectos cercanos al modelo de plantilla predeterminado, una reestructuración limpia de SPM a menudo es 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 Empresas para el flujo de trabajo del producto en Capgo Empresas Alternativas de Plugins de Ionic Empresas para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Empresas 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