Capacitor Risoluzione Problemi iOS: Errori Comuni e Soluzioni

La maggior parte dei problemi Capacitor iOS appartiene a cinque categorie: toolchain errato, risoluzione delle dipendenze (SPM o CocoaPods), errori di compilazione dei plugin, code firma, e problemi di esecuzione come “plugin non implementato” o una schermata WebView vuota. Inizia con bunx cap doctorconferma di aver selezionato Xcode 26, esegui bunx cap sync iose leggi il primo errore nel log di compilazione Xcode, non l'ultimo.

Questo guide elenca gli errori più comuni che incontriamo in Capacitor 8 progetti, le cause di ciascuno e la soluzione. Per Android, vedere il Capacitor guida di troubleshooting per Android.

Elenco di controllo rapido diagnostico

Esegui questi prima di iniziare a cercare un errore specifico:

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

• Versioni: @capacitor/core, @capacitor/ios e @capacitor/cli Deve condividere lo stesso major. Le incoerenze causano errori di compilazione e di esecuzione strani. Vedi fix Capacitor version mismatch errors.
• Una Xcode: se hai più versioni di Xcode xcode-select -p decide quale versione utilizzare il CLI. Risolvi il problema con sudo xcode-select -s /Applications/Xcode.app.
• Quale gestore di pacchetti: if ios/App/CapApp-SPM esiste, utilizza CocoaPods. ios/App/Podfile Errori di toolchain

Xcode o __CAPGO_KEEP_0__ troppo vecchio

Xcode o SDK troppo vecchio

Symptoms: value of type 'WKWebView' has no member 'isInspectable', errori di sintassi Swift all'interno Capacitor, or compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 richiede Xcode 26. In GitHub Azioni, macos-latest Non sempre punta all'immagine con la versione più recente di Xcode. Seleziona esplicitamente un'immagine che includa Xcode 26.

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

Check the runner image docs for the exact path. For the module-minimum error, raise your app’s deployment target to the plugin’s minimum, or use an older plugin version.

ITMS-90725: SDK version issue caricamento

Il build è stato eseguito con un SDK più vecchio di quanto accettato da Apple. Dalla data del 28 aprile 2026, gli upload devono essere costruiti con Xcode 26 e l'SDK iOS 26. Vedi La richiesta di Xcode 26 per le Capacitor app. Capgo Build costruisce già su Xcode 26 se non desiderate mantenere i runner Mac.

Error di gestione del pacchetto Swift

Missing package product 'CapApp-SPM'

Xcode non ha risolto il pacchetto locale, o il suo cache è datato.

1. File > Pacchetti > Reset Cache dei Pacchetti.
2. File > Pacchetti > Reset Cache dei Pacchetti.
3. File > Pacchetti > Risolvi le Versioni dei Pacchetti CapApp-SPM è aggiunto sotto il progetto's sia aggiunto sotto la cartella Dipendenze dei Pacchetti del Progetto

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

Un plugin Package.swift uses a package or product name that doesn’t match what the Capacitor CLI generated from its npm name. This is a plugin bug. Update the plugin, or Riparalomigrare un plugin __CAPGO_KEEP_0__ a SPM migrare un Capacitor plugin in SPM.

Alcuni plugin Capacitor installati non sono compatibili con SPM

Questo avviso durante cap sync ha almeno un plugin senza Package.swift. It’s left out of the app, so calls to it fail with “not implemented”. Upgrade the plugin, replace it with one that supports SPM, or Usa CocoaPods per ora.

Identità di pacchetto o nome di destinazione duplicati

Due a due plugin condividono un'identità di pacchetto o un nome di destinazione (spesso un nome generico come Plugin. Dal CLI 8.4 puoi risolverlo dalla Capacitor configurazione:

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

symlink rende il CLI un riferimento al plugin attraverso un cartella simbolica con un percorso unico. moduleAliases rinomina un modulo in conflitto per quella dipendenza. Segnala il conflitto anche su GitHub.

Distruggi CapApp-SPM/Package.swift

Il CLI lo riscrive ogni volta che sincronizza. Le modifiche locali scompaiono. Utilizzare il experimental.ios.spm Errori di CocoaPods

Error di CocoaPods

No such module 'Capacitor'

piuttosto che App.xcodeproj Utilizza App.xcworkspace. Use bunx cap open iosSe il workspace è aperto e l'errore persiste, esegui bunx cap sync ios riinstallare i pods.

CocoaPods could not find compatible versions for pod "X"

Due a due cause:

1. Repo spec obsoleto: esegui cd ios/App && pod install --repo-update.
2. Pini in conflitto: due plugin richiedono versioni incompatibili dello stesso pod. L'errore stampa la catena. Aggiorna il plugin con la pin rigida, allinea le versioni (per Firebase, mantieni tutte le plugin Firebase sulla stessa versione SDK), o patch il podspec.

Se continua a fallire, cancella ios/App/Podfile.lock e ios/App/Podspoi sincronizza nuovamente. Ciò aggiorna anche ogni pod, quindi testa dopo.

The sandbox is not in sync with the Podfile.lock

Esegui bunx cap sync iosSi verifica dopo gli switch di branch o le installazioni parziali.

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

Il tuo project.pbxproj utilizza un formato che la tua versione di CocoaPods non può leggere. Aggiorna CocoaPods (brew upgrade cocoapods o aumenta in tuo Gemfile. Come ultima risorsa, salva il file e abbassa objectVersion.

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

Xcode's sandboxing dei script utente blocca lo script di embed del framework CocoaPods. Imposta Impostazioni di compilazione > Sandbox dei script utente su No sul target App.

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

Il build del simulatore sta eseguendo per Intel. Su Apple Silicon ciò significa generalmente che Xcode esegue sotto Rosetta o un vecchio EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 La compilazione del simulatore sta eseguendo per Intel. Su Apple Silicon ciò significa che Xcode esegue sotto Rosetta o un vecchio post_install configura l'hook, poi pulisci e ricostruisci.

hook, quindi pulisci e ricompila.

Command PhaseScriptExecution failed with a nonzero exit code

Questo è un wrapper. Espandi la fase di costruzione fallita nel navigatore di Report e leggi l'output del script. Le cause comuni nei Capacitor app sono:

• A Run Script richiede node e Xcode non lo trova, perché Xcode non carica il tuo profilo shell e Node è installato con nvm, fnm o Volta. Utilizza la strada completa al node in lo script, o esporta PATH all'inizio di esso.
• A uno script di caricamento di crash report (Sentry, Crashlytics) mancano le credenziali in CI.
• CocoaPods embed script bloccato dalla sandboxing degli script dell'utente (vedi sopra).

'X' is only available in iOS 16.0 or newer

Uno plugin utilizza un API sopra la tua versione di rilascio. Innalza la versione in Xcode, nel Podfile (platform :ios, '16.0'se utilizzi CocoaPods, e controlla la README del plugin per la sua minima.

Errori di concorrenza in Swift 6 in un plugin

Messaggi come Sending 'x' risks causing data races si presentano quando un plugin o il tuo target di app utilizza il linguaggio di Swift 6. Capacitor 8 non supporta ufficialmente Swift 6. Mantieni il target di app sul linguaggio di Swift 5 fino a quando il plugin non viene aggiornato.

Code firma

Signing for "App" requires a development team

Apri App target > Firmato e Capacità e seleziona un team. In CI, passa DEVELOPMENT_TEAM a xcodebuild o utilizza uno strumento di firma. Se l'errore nomina un bundle di risorse pod al posto di App, disabilita la firma per i target bundle nel Podfile post_install hook

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

Hai aggiunto una capacità (Notifiche Push, Domini Associati, Accedi con Apple) senza rigenerare il profilo. Abilita la funzione sul ID App nel portale dello sviluppatore Apple, quindi aggiorna i profili. Il nostro generatore di certificati iOS aiuta a creare certificati senza dover ballare con la chiave di accesso Mac. trovatore di UDID aiuta a registrare dispositivi di test

Unable to install "App" su dispositivo

Abilita il Modo Sviluppatore sul dispositivo (Impostazioni > Privacy & Sicurezza > Modo Sviluppatore), fidati del certificato del developer e assicurati che l'ID dispositivo sia presente nel profilo di provisioning per le build di sviluppo.

Errori di esecuzione

"X" plugin is not implemented on ios

Il lato JavaScript non ha trovato alcuna implementazione nativa. Controlla in questo ordine:

1. La plugin è in package.json e hai eseguito bunx cap sync ios dopo aver installato.
2. Per SPM: la plugin appare in ios/App/CapApp-SPM/Package.swift. Se non, non ha Package.swift.
3. Per CocoaPods: la plugin appare nel capacitor_pods blocco del Podfile e pod install non ha stampato alcun avviso.
4. Non hai due plugin che registrano lo stesso nome JS (ad esempio due plugin di notifiche push).
5. WKAppBoundDomains non è presente Info.plist, oppure se lo è, limitsNavigationsToAppBoundDomains è impostato e localhost è elencato. I domini app-bound bloccano l'iniezione di script di plugin altrimenti.
6. Pulisci la cartella di build e ricostruisci. I build obsoleti conservano le registrazioni dei plugin vecchi.

Schermo bianco vuoto al lancio

Ispeziona il WebView con Safari Web Inspector prima. La maggior parte delle schermate bianche è un errore di JavaScript.

• sbagliato webDir: capacitor.config.ts si riferisce a una cartella che non contiene index.html. Controlla ios/App/App/public.
• Target di costruzione troppo nuovo: il tuo bundler emette sintassi più vecchia che non supporta WebKit. L'iOS 15 è il minimo per Capacitor 8, quindi impostalo safari15 o più recente in Vite/esbuild e controlla il tuo browserslist.
• Perimetri assoluti degli asset: a base set to a CDN or subpath in your bundler config breaks local loading.
• Live reload non raggiungibile: il server di sviluppo deve ascoltare sulla tua IP del LAN (--host 0.0.0.0), il telefono deve essere sulla stessa rete e l'app necessita della Permessi di rete locale permesso (Impostazioni > Privacy e sicurezza > Rete locale). Elimina server.url : rimuovi dalla configurazione prima delle release build.
• Live update bundle rotto: se l'app utilizza gli aggiornamenti OTA, un bundle danneggiato può rendere lo schermo bianco. Capgo's updater torna indietro automaticamente quando notifyAppReady() non viene chiamato in tempo. Vedi i documenti dell'aggiornatore.

il contenuto sotto la notch o l'indicatore di casa

Aggiungi viewport-fit=cover aggiungi al tuo tag meta viewport e riempilo con env(safe-area-inset-top) e env(safe-area-inset-bottom). Capacitor 8's System Bars plugin controlla lo stile e la visibilità della barra di stato su entrambe le piattaforme.

Tastiera copre gli input

Configura il plugin del tastierino resize modalità (native, body, ionic o nonee testa su un dispositivo reale. I simulatori gestiscono la tastiera in modo diverso.

Errori di App Store Connect

• ITMS-91053: Missing API declaration: la tua app o un plugin utilizza un API richiesto senza una voce di manifesto di privacy. Aggiungi un PrivacyInfo.xcprivacy alla destinazione App con le ragioni e aggiorna i plugin che inviano il proprio manifesto.
• ITMS-90725: SDK version issue: ricostruisci con Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': un framework è incorporato all'interno di un'estensione o di un altro framework. Controlla Embed impostazioni per le estensioni dell'app.

Come debuggare quando l'errore non è elencato

1. Safari Web Inspector per gli errori JS e le chiamate di rete. I build di debug sono ispezionabili su iOS 16.4+. Per i build di rilascio impostare ios.webContentsDebuggingEnabled: true temporaneamente.
2. Console Xcode per registri nativi, compresi quelli di Capacitor ⚡️ messaggi di ponte che mostrano ogni chiamata del plugin.
3. Console.app con il dispositivo selezionato per il crash e i log del sistema.
4. IsolateCrea un'app nuova con bun create @capacitor/appAggiungi solo il plugin sospetto e controlla se l'errore si riproduce.

The ultimate guide to debugging Capacitor apps Esplora ulteriormente ogni strumento. Se la causa radice è un bug di un plugin, Xcode console E' di solito il modo più veloce per sbloccare mentre aspetti una versione.