Capacitor: Resolución de problemas de iOS: Errores y soluciones comunes

La mayoría de los problemas Capacitor iOS se dividen en cinco grupos: herramienta de cadena incorrecta, resolución de dependencias (SPM o CocoaPods), errores de compilación de plugins, code firmado, y problemas de tiempo de ejecución como “plugin no implementado” o una WebView en blanco. Comience con bunx cap doctorconfirmar que ha seleccionado Xcode 26, ejecute bunx cap sync iosy lea el primer error en el registro de compilación de Xcode, no el último.

Esta guía enumera los errores que más vemos en Capacitor 8 proyectos, sus causas y la solución. Para Android, consulte la Capacitor Android troubleshooting guide.

Lista de verificación de triaje rápido

Ejecuta estos antes de perseguir un error específico:

bunx cap doctor            # Capacitor, CLI and plugin versions should match
node -v                    # 22 or later for Capacitor 8
xcodebuild -version        # 26.x
xcode-select -p            # should point to the Xcode you expect
bun run build && bunx cap sync ios

• Versiones: @capacitor/core, @capacitor/ios y @capacitor/cli deben compartir el mismo número mayor. Los desacuerdos causan errores de compilación y ejecución extraños. Consulte corregir errores de versión de Capacitor.
• Un Xcode: si tiene varias versiones de Xcode xcode-select -p decide cuál utiliza el CLI. Solucione con sudo xcode-select -s /Applications/Xcode.app.
• ¿Cuál gestor de paquetes?: si ios/App/CapApp-SPM existe, el proyecto utiliza SPM. Si ios/App/Podfile existe, utiliza CocoaPods.

Errores de herramienta

Xcode o SDK demasiado antiguo

Síntomas: value of type 'WKWebView' has no member 'isInspectable', errores de sintaxis de Swift dentro de Capacitor, o compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 requiere Xcode 26. En GitHub Acciones, macos-latest no siempre apunta a la imagen con la versión más nueva de Xcode. Pin una imagen que incluya Xcode 26 y selecciónela explícitamente:

- run: sudo xcode-select -s /Applications/Xcode_26.0.app

Consulte la documentación de la imagen del ejecutor para el camino exacto. Para el error de módulo mínimo, aumente el objetivo de despliegue de la aplicación al mínimo del plugin, o utilice una versión del plugin más antigua.

ITMS-90725: SDK version issue en la carga

La compilación se realizó con un SDK más antiguo de lo que acepta actualmente Apple. Desde el 28 de abril de 2026, las subidas deben ser compiladas con Xcode 26 y el iOS 26 SDK. Consulte Requisito de Xcode 26 para Capacitor de Apple. Capgo Construcción Ya que construye en Xcode 26 si no deseas mantener ejecutores de Mac.

Errores del Gestor de Paquetes de Swift

Missing package product 'CapApp-SPM'

Xcode no ha resuelto el paquete local, o su caché está obsoleto.

1. Archivo > Paquetes > Restablecer Cachés de Paquetes.
2. Archivo > Paquetes > Resolver Versión de Paquete.
3. Si la aplicación se migró desde CocoaPods, compruebe que CapApp-SPM se ha agregado bajo la pestaña Dependencias de Paquetes y está vinculado a la meta de la aplicación.

product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found

Un plugin Package.swift usa un paquete o nombre de producto que no coincide con lo que Capacitor CLI generó a partir de su nombre de npm. Esto es un error de plugin. Actualice el plugin o corrija corrijapuede encontrar la regla de nombrado en migrar un plugin de Capacitor a SPM.

“Algunos plugins instalados Capacitor no son compatibles con SPM”

Esta advertencia durante cap sync indica que al menos un plugin no tiene Package.swift. Se omite en la aplicación, por lo que las llamadas a él fallan con ‘no implementado’. Actualice el plugin, reemplácelo con uno que admita SPM o usa CocoaPods por ahora.

identidad de paquete duplicada o nombre de destino

dos plugins comparten una identidad de paquete o un nombre de destino (a menudo un nombre genérico como Plugin. Desde CLI 8.4 puedes solucionarlo desde la Capacitor configuración:

const config: CapacitorConfig = {
  // ...
  experimental: {
    ios: {
      spm: {
        packageOptions: {
          '@acme/capacitor-foo': { symlink: true },
          '@acme/capacitor-bar': { moduleAliases: { Plugin: 'AcmeBarPlugin' } },
        },
      },
    },
  },
};

symlink hace que la CLI se refiera al plugin a través de un enlace simbólico con un camino único. moduleAliases renombra un módulo en conflicto para esa dependencia. Informa el conflicto en la fuente también.

No editar CapApp-SPM/Package.swift

La CLI lo reescribe cada vez que se sincroniza. Los cambios locales desaparecen. Utilice el experimental.ios.spm Errores de CocoaPods

Errores de CocoaPods

No such module 'Capacitor'

en lugar de App.xcodeproj . Utiliza App.xcworkspace. Use bunx cap open iosSi el espacio de trabajo está abierto y el error persiste, ejecuta bunx cap sync ios reinstalar pods.

CocoaPods could not find compatible versions for pod "X"

Dos causas:

1. Repo de especificaciones desactualizado: ejecuta cd ios/App && pod install --repo-update.
2. Pines en conflicto: dos plugins necesitan versiones incompatibles del mismo pod. El error imprime la cadena. Actualiza el plugin con la pina estricta, alinea versiones (para Firebase, mantén todos los plugins de Firebase en la misma versión SDK), o parchea el podspec.

Si sigue fallando, elimina ios/App/Podfile.lock y ios/App/PodsLuego, sincronice de nuevo. Esto también actualiza cada pod, así que pruebe después.

The sandbox is not in sync with the Podfile.lock

Run bunx cap sync iosSucede después de cambiar de rama o de realizar instalaciones parciales.

Unable to find compatibility version string for object version '70'

Your project.pbxproj . Esto ocurre después de cambios de rama o instalaciones parciales.brew upgrade cocoapods o aumentarlo en su GemfileComo último recurso, respalda el archivo y baja la versión. objectVersion.

Sandbox: rsync(...) deny(1) file-write-create

Xcode’s sandbox de scripts de usuario bloquea el script de inclusión de CocoaPods. Establezca Ajustes de compilación > Sandbox de scripts de usuario a No en la configuración de la aplicación.

could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'

El simulador de compilación está ejecutándose para Intel. En Apple Silicon esto suele significar que Xcode se ejecuta bajo Rosetta o una versión antigua. EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 La configuración se queda de una solución de trabajo pasada. Corre Xcode nativamente, elimine esa configuración del objetivo de la App y de cualquier post_install Errores de compilación

Errores de compilación

Command PhaseScriptExecution failed with a nonzero exit code

Este es un wrapper. Amplíe la fase de compilación fallida en el navegador de Informes y lea la salida del script. Causas comunes en aplicaciones Capacitor:

• A Run Script necesita node y Xcode no puede encontrarlo, porque Xcode no carga tu perfil de shell y Node se instala con nvm, fnm o Volta. Utiliza la ruta completa a node en el script, o exporta PATH en la parte superior de él.
• Un script de carga de informes de errores (Sentry, Crashlytics) falta de credenciales en CI.
• El script de CocoaPods de inclusión está bloqueado por la sandboxing de usuario (ver arriba).

'X' is only available in iOS 16.0 or newer

Un plugin utiliza un API por encima de tu objetivo de despliegue. Aumenta el objetivo en Xcode, en el archivo Podfile ("platform :ios, '16.0'si utilizas CocoaPods, y revisa el archivo README del plugin para su mínimo.

Errores de concurrencia de Swift 6 en un plugin

Los mensajes como Sending 'x' risks causing data races aparecen cuando un plugin o tu objetivo de aplicación utiliza el modo de lenguaje de Swift 6. Capacitor 8 no oficialmente admite Swift 6. Mantén el objetivo de aplicación en el modo de lenguaje de Swift 5 hasta que el plugin esté actualizado.

Code de firma

Signing for "App" requires a development team

Abre App target > Firmas y Capabilidades y selecciona un equipo. En CI, pasa DEVELOPMENT_TEAM a xcodebuild o use a signing tool. Si el error menciona un recurso de bundle de pods en lugar de App, deshabilite la firma para los objetivos de bundle en el archivo Podfile. post_install hook.

Provisioning profile "X" doesn't include the ... entitlement

Tienes una capacidad (Notificaciones de empuje, Dominios asociados, Iniciar sesión con Apple) sin regenerar el perfil. Actívala en el portal del desarrollador de Apple, luego refresque los perfiles. Nuestro generador de certificados de iOS ayuda a crear certificados sin bailar con la llave de Mac, y el encontrador de UDID ayuda a registrar dispositivos de prueba.

Unable to install "App" en el dispositivo

Habilite el modo de desarrollador en el dispositivo (Configuración > Privacidad y seguridad > Modo de desarrollador), confíe en el certificado del desarrollador y asegúrese de que el ID del dispositivo UDID esté en el perfil de provisión para los builds de desarrollo.

Errores de tiempo de ejecución

"X" plugin is not implemented on ios

La parte JavaScript no encontró implementación nativa. Verifique en este orden:

1. Los errores de tiempo de ejecución package.json y ejecutaste bunx cap sync ios El plugin está en
2. Para SPM: el plugin aparece en ios/App/CapApp-SPM/Package.swiftdespués de instalarlo. Package.swift.
3. Para SPM: el plugin aparece en capacitor_pods bloque del archivo Podfile pod install No se imprimieron advertencias.
4. No tiene dos plugins registrando el mismo nombre de JS (por ejemplo, dos plugins de notificaciones push).
5. WKAppBoundDomains no está en Info.plist, o si lo está, limitsNavigationsToAppBoundDomains está configurado y localhost is listed. App-bound domains block plugin script injection otherwise.
6. Clean build folder and rebuild. Stale builds keep old plugin registrations.

Pantalla blanca en blanco

Inspecte el WebView con el Inspector de Safari primero. La mayoría de pantallas en blanco son un error de JavaScript.

• Incorrecto webDir: capacitor.config.ts apunta a una carpeta que no contiene index.htmlRevisa ios/App/App/public.
• Objetivo de compilación demasiado nuevo: su emisor de paquetes emite sintaxis que no soporta WebKit. iOS 15 es el mínimo para Capacitor 8, por lo que establezca safari15 o posterior en Vite/esbuild y comprueba su browserslist.
• Rutas de activos absolutas: a base establecido en una CDN o subruta en la configuración de su compilador rompe la carga local.
• Recarga en vivo inalcanzable: el servidor de desarrollo debe escuchar en su IP de red LAN (--host 0.0.0.0), el teléfono debe estar en la misma red y la aplicación necesita la Red de Local permiso (Configuración > Privacidad y seguridad > Red local). Elimine server.url from the config before release builds.
• Live update paquete roto: si la aplicación utiliza actualizaciones OTA, un paquete malo puede dejar la pantalla en blanco. Capgo’s actualizador vuelve a cargar automáticamente cuando notifyAppReady() no se llama a tiempo. Consulte los documentación del actualizador.

Contenido debajo de la marca de agua o indicador de inicio

Agregar viewport-fit=cover comparar los pasos de Capacitor env(safe-area-inset-top) and env(safe-area-inset-bottom).Capacitor 8’s plugin de barras de sistema controla el estilo y visibilidad de la barra de estado en ambas plataformas.

Teclado cubre los campos de entrada

Cubrir el teclado Configurar el resize mode (native, body, ionic modo (o noney pruebe en un dispositivo real. Los simuladores manejan el teclado de manera diferente.

errores de App Store Connect

• ITMS-91053: Missing API declaration: su aplicación o un plugin utiliza un API requerido sin una entrada de manifiesto de privacidad. Agregue un PrivacyInfo.xcprivacy para la App con las razones, y actualice los plugins que envían su propio manifiesto.
• ITMS-90725: SDK version issue: reconstruya con Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': un framework está incrustado dentro de una extensión o otro framework. Verifique Embeber configuración de extensiones de la aplicación.

Cómo depurar cuando el error no está listado

1. Inspector de Web de Safari para errores de JS y llamadas de red. Los builds de depuración son inspeccionables en iOS 16.4+. Para builds de liberación establezca ios.webContentsDebuggingEnabled: true temporalmente.
2. Consola de Xcode para registros nativos, incluyendo Capacitor’s ⚡️ mensajes de puente que muestran cada llamada de plugin.
3. Console.app con el dispositivo seleccionado para la falla y registros del sistema.
4. IsolateCrear una aplicación fresca con bun create @capacitor/app, agregue solo el plugin sospechoso y verifique si el error se reproduce.

The ultimate guide to debugging Capacitor apps explora más a fondo cada herramienta. Si la causa raíz es un error de plugin, un patch generalmente es la desbloqueo más rápido mientras esperas una versión.