Troubleshooting Capacitor su iOS: errori comuni e soluzioni

La maggior parte dei problemi Capacitor su iOS rientra in cinque gruppi: toolchain errata, risoluzione delle dipendenze (SPM o CocoaPods), errori di compilazione dei plugin, signing di code e problemi a runtime come “plugin is not implemented” o una WebView bianca. Inizia con bunx cap doctor, conferma di aver selezionato Xcode 26 ed esegui bunx cap sync ios, e leggi il primo errore nel log di build di Xcode, non l'ultimo.

Questa guida elenca gli errori che vediamo più spesso nei progetti Capacitor 8, le cause di ciascuno e la soluzione. Per Android, consulta la guida alla risoluzione dei problemi di Capacitor Android.

Checklist rapida di triage

Esegui questi prima di indagare su 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 devono condividere la stessa versione major. Le discrepanze causano errori di compilazione e runtime insoliti. Vedi risolvere errori di mismatch di versione Capacitor.
• Un solo Xcode: se hai più versioni di Xcode, xcode-select -p decide quale versione usa CLI. Risolvilo con sudo xcode-select -s /Applications/Xcode.app.
• Quale package manager: se ios/App/CapApp-SPM esiste, il progetto usa SPM. Se ios/App/Podfile esiste, usa CocoaPods.

Errori della toolchain

Xcode o SDK troppo vecchi

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

Capacitor 8 richiede Xcode 26. In GitHub Actions, macos-latest non punta sempre all'immagine con la versione più recente di Xcode. Fissa un'immagine che includa Xcode 26 e selezionala esplicitamente:

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

Consulta la documentazione delle immagini runner per il percorso esatto. Per l'errore di modulo minimo, aumenta il deployment target della tua app al minimo richiesto dal plugin, oppure usa una versione precedente del plugin.

ITMS-90725: SDK version issue al caricamento

La build è stata creata con un SDK più vecchio di quello attualmente accettato da Apple. Dal 28 aprile 2026, gli upload devono essere costruiti con Xcode 26 e l'iOS 26 SDK. Vedi Il requisito Xcode 26 di Apple per le app Capacitor. Build Capgo effettua già le build su Xcode 26 se non vuoi gestire runner Mac.

Errori di Swift Package Manager

Missing package product 'CapApp-SPM'

Xcode non ha risolto il pacchetto locale, oppure la sua cache è obsoleta.

1. File > Package > Reset Package Caches.
2. File > Pacchetti > Risolvi versioni pacchetti.
3. Se l'app è stata migrata da CocoaPods, verifica che CapApp-SPM viene aggiunto sotto il Dipendenze del pacchetto tab e collegata al target dell'App.

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

Di un plugin, Package.swift utilizza un nome di package o prodotto che non corrisponde a quello che Capacitor CLI ha generato dal suo nome npm. Si tratta di un bug del plugin. Aggiorna il plugin, oppure correggilo. Gli autori dei plugin possono trovare la regola di naming in migrare un plugin Capacitor a SPM.

“Alcuni plugin Capacitor installati non sono compatibili con SPM”

Questo warning durante cap sync significa che almeno un plugin non ha Package.swift. Viene escluso dall'app, quindi le chiamate falliscono con “not implemented”. Aggiorna il plugin, sostituiscilo con uno che supporti SPM, oppure usa CocoaPods per ora.

Identità del package o nome del target duplicati

Due plugin condividono un'identità di pacchetto o un nome di destinazione (spesso un nome generico come Plugin). Da CLI 8.4 in poi puoi risolvere il problema dalla configurazione Capacitor:

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

symlink fa sì che CLI faccia riferimento al plugin tramite una cartella symlink con un percorso univoco. moduleAliases rinomina un modulo in conflitto per quella dipendenza. Segnala anche il conflitto upstream.

Non modificare CapApp-SPM/Package.swift

CLI lo riscrive a ogni sync. Le modifiche locali vengono perse. Usa le experimental.ios.spm opzioni di configurazione invece.

Errori di CocoaPods

No such module 'Capacitor'

Hai aperto App.xcodeproj invece di App.xcworkspace. Usa bunx cap open ios. Se lo workspace è aperto e l'errore persiste, esegui bunx cap sync ios per reinstallare i pods.

CocoaPods could not find compatible versions for pod "X"

Due cause:

1. Spec repo obsoleto: esegui cd ios/App && pod install --repo-update.
2. Pins in conflitto: due plugin richiedono versioni incompatibili dello stesso pod. L'errore mostra la catena. Aggiorna il plugin con il pin rigido, allinea le versioni (per Firebase, mantieni tutti i plugin Firebase sulla stessa versione SDK) o modifica il podspec.

Se continua a fallire, elimina ios/App/Podfile.lock e ios/App/Pods, poi sincronizza di nuovo. Questo aggiorna anche tutti i pods, quindi testa dopo.

The sandbox is not in sync with the Podfile.lock

Esegui bunx cap sync ios. Succede dopo cambi di branch o installazioni parziali.

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

Il tuo project.pbxproj usa un formato non leggibile dalla tua versione di CocoaPods. Aggiorna CocoaPods (brew upgrade cocoapods o aumentalo nel tuo Gemfile). Come ultima risorsa, fai backup del file e abbassa objectVersion.

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

Lo script sandbox di Xcode blocca lo script di embed dei framework CocoaPods. Imposta Impostazioni di build > Sandbox degli script utente a No sull'App target.

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

La build del simulatore è in esecuzione per Intel. Su Apple Silicon di solito significa che Xcode gira sotto Rosetta o una versione EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 l'impostazione è un residuo di una soluzione temporanea passata. Esegui Xcode nativamente, rimuovi quell'impostazione dal target App e da qualsiasi post_install hook, poi pulisci e ricompila.

Errori di compilazione

Command PhaseScriptExecution failed with a nonzero exit code

Si tratta di un wrapper. Espandi la fase di build fallita nel Report navigator e leggi l'output dello script. Cause comuni nelle app Capacitor:

• Un 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. Usa il percorso completo di node nello script, oppure esporta PATH in cima ad esso.
• Manca un upload script per il crash reporting (Sentry, Crashlytics) con credenziali in CI.
• Script di embedding di CocoaPods bloccato dal sandboxing degli script utente (vedi sopra).

'X' is only available in iOS 16.0 or newer

Un plugin utilizza un API superiore al tuo deployment target. Aumenta il target in Xcode, nel Podfile (platform :ios, '16.0') se usi CocoaPods, e controlla il README del plugin per il minimo richiesto.

Errori di concorrenza Swift 6 in un plugin

Messaggi come Sending 'x' risks causing data races compaiono quando un plugin o il target della tua app usa la modalità linguaggio Swift 6. Capacitor 8 non supporta ufficialmente Swift 6. Mantieni il target App in modalità linguaggio Swift 5 finché il plugin non viene aggiornato.

Firma di Code

Signing for "App" requires a development team

Apri Target dell'app > Signing & Capabilities e seleziona un team. In CI, passa DEVELOPMENT_TEAM a xcodebuild o usa uno strumento di firma. Se l'errore indica un bundle di risorse di un pod invece dell'App, disabilita la firma per i target bundle nel Podfile post_install hook.

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

Hai aggiunto una capability (Push Notifications, Associated Domains, Sign in with Apple) senza rigenerare il profilo. Abilitala sull'App ID nel portale Apple Developer, poi aggiorna i profili. Il nostro Generatore di certificati iOS aiuta a creare certificati senza impazzire con il keychain del Mac, e il Trova UDID aiuta a registrare i dispositivi di test.

Unable to install "App" sul dispositivo

Attiva la Modalità sviluppatore sul dispositivo (Impostazioni > Privacy e sicurezza > Modalità sviluppatore), considera attendibile il certificato dello sviluppatore e assicurati che l'UDID del dispositivo sia nel provisioning profile per le build di sviluppo.

Errori runtime

"X" plugin is not implemented on ios

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

1. Il plugin è in package.json e hai eseguito bunx cap sync ios dopo averlo installato.
2. Per SPM: il plugin compare in ios/App/CapApp-SPM/Package.swift. Se non compare, non ha Package.swift.
3. Per CocoaPods: il plugin appare nel capacitor_pods blocco del Podfile e pod install non ha stampato avvisi.
4. Non hai due plugin che registrano lo stesso nome JS (ad esempio due plugin di notifica push).
5. WKAppBoundDomains non è in Info.plist, o se lo è, limitsNavigationsToAppBoundDomains è impostato e localhost è elencato. I domini app-bound bloccano altrimenti l'iniezione degli script del plugin.
6. Pulisci la cartella di build e ricompila. Le build vecchie mantengono le registrazioni dei plugin obsoleti.

Schermo bianco vuoto all'avvio

Ispeziona prima il WebView con Safari Web Inspector. La maggior parte degli schermi bianchi è un errore JavaScript.

• Errato webDir: capacitor.config.ts punta a una cartella che non contiene index.html. Controlla ios/App/App/public.
• Target di build troppo recente: il tuo bundler genera sintassi non supportata dalle versioni precedenti di WebKit. iOS 15 è il minimo per Capacitor 8, quindi imposta safari15 o successivo in Vite/esbuild e verifica il tuo browserslist.
• Percorsi assoluti delle risorse: un base impostare un CDN o un sottopercorso nella configurazione del bundler impedisce il caricamento locale.
• Live reload non raggiungibile: il dev server deve ascoltare sull'IP LAN (--host 0.0.0.0), il telefono deve essere sulla stessa rete e l'app richiede l'autorizzazione Rete locale autorizzazione (Impostazioni > Privacy e sicurezza > Rete locale). Rimuovi server.url dalla configurazione prima dei build di rilascio.
• bundle Live update difettoso: se l'app usa aggiornamenti OTA, un bundle difettoso può lasciare lo schermo bianco. L'updater di Capgo esegue il rollback automaticamente se notifyAppReady() non viene chiamato in tempo. Consulta la documentazione dell'updater.

Contenuto sotto il notch o l'indicatore home

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

La tastiera copre gli input

Configura il Plugin della tastiera resize modalità (native, body, ionic oppure none) e 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 obbligatorio senza una voce nel privacy manifest. Aggiungi un PrivacyInfo.xcprivacy al target dell'app con le motivazioni, e aggiorna i plugin che includono il proprio manifest.
• ITMS-90725: SDK version issue: ricompila con Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': un framework è incorporato in un'estensione o in un altro framework. Controlla le Incorpora per le app extension.

Come fare il debug se l'errore non è in elenco

1. Safari Web Inspector per errori JS e chiamate di rete. Le build di debug sono ispezionabili su iOS 16.4+. Per le build di release imposta ios.webContentsDebuggingEnabled: true temporaneamente.
2. Console di Xcode per i log nativi, inclusi quelli di Capacitor ⚡️ messaggi del bridge che mostrano ogni chiamata al plugin.
3. Console.app con il dispositivo selezionato per i log di crash e di sistema.
4. Isola: crea una nuova app con bun create @capacitor/app, aggiungi solo il plugin sospetto e verifica se l'errore si ripresenta.

Il guida definitiva al debugging di app Capacitor approfondisce ogni strumento. Se la causa principale è un bug di un plugin, un patch è di solito il modo più rapido per sbloccarti mentre aspetti un rilascio.