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 tu aplicación.

Esta guía te guía a través de los cambios, qué respaldar y los dos métodos prácticos de migración: utilizar la asistente de migración Capacitor o rearmar el proyecto de iOS con SPM.

¿Por qué migrar ahora?

CocoaPods está moviéndose hacia un tronco de solo lectura. El plan actual es que el tronco de CocoaPods deje de aceptar nuevos podspecs 2 de diciembre de 2026Los builds existentes deberían seguir funcionando, pero las nuevas versiones y actualizaciones de dependencias que dependen de la rama principal no se publicarán allí después de la transición.

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

¿Qué cambia en un proyecto de Capacitor SPM

Reemplazar CocoaPods por 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 cablean 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 llamado CapApp-SPMEste 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

The asistente de migración también crea un archivo generado debug.xcconfigEste archivo lleva configuraciones de compilación que CocoaPods utilizaba para proporcionar 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 aún, actualízalo, reemplázalo o migra el plugin primero. Los plugins de Swift simples a menudo se pueden convertir con Ionic’s capacitor-plugin-converterpero los plugins con diseños más complejos de Objective-C y Swift pueden requerir trabajo manual.

¿Qué respaldar primero

Comienza desde una rama de Git limpia y haz un commit de tu estado actual antes de tocar el proyecto iOS. Luego, enumera los archivos nativos en los que tu aplicación depende.

Archivos comunes a preservar de ios/App/ incluyen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftSi tu aplicación tiene uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistSi utilizas 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 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 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:

Usa este camino cuando tu proyecto de iOS tiene ediciones nativas personalizadas que no deseas perder.

bunx cap open ios

Luego, sigue los pasos manuales de Xcode impresos por el asistente.

Agregar CapApp-SPM como una dependencia de paquete local.
Agregar el generado debug.xcconfig a la configuración de la aplicación.
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 construya, sincroniza nuevamente:

bunx cap sync ios

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

Utiliza este camino cuando tu ios/ carpeta está cerca del template predeterminado Capacitor y puedes restaurar archivos personalizados con seguridad después.

Primero, asegúrate de que los archivos listados en la sección de respaldo estén comprometidos o copiados en algún lugar seguro. Luego, elimina y recrea el proyecto de iOS con SPM:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Restablecer los archivos nativos que necesita tu aplicación, luego abre el proyecto:

bunx cap open ios

Esta ruta suele ser más limpia que una migración en lugar porque te da un Capacitor fresco 8 de iOS. El contrapunto es que debes reaplicar con cuidado la firma, las autorizaciones, los archivos de Firebase, los cambios en el código nativo y cualquier ajuste personalizado de Xcode.

Nuevos Capacitor de aplicaciones

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

bunx cap add ios

Si necesitas ser explícito, puedes pasar aún 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 las cachés para:

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

Mantén tus pasos de construcción web regulares y Capacitor sincronizados. Un trabajo de iOS típico debe 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 comprobación de la migración

Antes de la migración:

Crear una nueva rama de Git.
Comitar la aplicación actual.
Verificar que cada plugin instalado admite SPM.
Grabar archivos iOS personalizados y ajustes de firma.
Confirmar que la aplicación se compila 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:

Compilar y ejecutar la aplicación en Xcode.
Eliminar archivos CocoaPods sobrantes.
Eliminar pod install de CI.
Verificar que la firma de lanzamiento sigue funcionando.
Ejecutar la aplicación en al menos un simulador y un dispositivo real antes de enviar.

Solución de problemas

Si Xcode no puede resolver paquetes, reinicie las cachés de paquetes desde Xcode y ejecutar bunx cap sync ios When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced build path, a stale command, or caching from previous builds.

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

Conclusion .xcworkspace Migrar una aplicación __CAPGO_KEEP_0__ a Swift Package Manager es principalmente sobre reemplazar la configuración de dependencias de iOS. pod install La migración de dependencias se realiza automáticamente, reemplaza la configuración de build generada de CocoaPods, y CI ya no necesita Pods/ Para proyectos de iOS personalizados, comienza con

Para proyectos cercanos al template por defecto, una reestructuración de SPM limpia es a menudo más rápida y fácil de razonar.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM When the app builds locally but CI fails, check for old CocoaPods assumptions. debug.xcconfig When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced build path, a stale command, or caching from previous builds. pod install.

When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced build path, a stale command, or caching from previous builds. bunx cap spm-migration-assistantWhen the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced build path, a stale command, or caching from previous builds.

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 de Plugins Empresariales de Ionic Enterprise para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternatives 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.