Capacitor iOS-Problembehandlung: Häufige Fehler und Lösungen

Die meisten Capacitor iOS-Probleme gehören zu fünf Gruppen: falsche Werkzeuge, Abhängigkeitsauflösung (SPM oder CocoaPods), Kompilierfehler von Plugins, code Signierung und Laufzeitprobleme wie „Plugin ist nicht implementiert“ oder ein leerer WebView. Beginnen Sie mit bunx cap doctor, bestätigen Sie, dass Xcode 26 ausgewählt ist, führen Sie bunx cap sync ios, und lesen Sie die erste Fehlermeldung im Xcode-Build-Protokoll, nicht die letzte.

Dieses Leitfaden listet die Fehler auf, die wir am häufigsten in Capacitor 8-Projekten sehen, ihre Ursachen und die Lösungen. Für Android siehe das Capacitor Android-Fehlersuchleitfaden.

Schnellprüfcheckliste

Laufen Sie diese vor der Verfolgung eines bestimmten Fehlers:

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

• Versions: @capacitor/core, @capacitor/ios und @capacitor/cli müssen dieselbe Hauptversion haben. Andernfalls treten ungewöhnliche Kompilations- und Laufzeitfehler auf. Siehe fixen Sie Capacitor Versionsmangelsfehler.
• Einer Xcode: wenn Sie mehrere Xcode-Versionen haben, xcode-select -p entscheidet, welches der CLI verwendet. Korrigieren Sie es mit sudo xcode-select -s /Applications/Xcode.app.
• Welcher Paketmanager: wenn ios/App/CapApp-SPM existiert, verwendet das Projekt SPM. Wenn ios/App/Podfile existiert, verwendet es CocoaPods.

Fehler im Toolchain

Xcode oder SDK zu alt

Symptome: value of type 'WKWebView' has no member 'isInspectable', Fehler in der Swift-Syntax innerhalb Capacitor, oder compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 erfordert Xcode 26. In GitHub Actions macos-latest Dein Runner-Image zeigt nicht immer die neueste Xcode-Version an. Pinne ein Bild, das Xcode 26 enthält, und wähle es explizit aus:

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

Überprüfe die Dokumentation zum Runner-Image für den genauen Pfad. Für das Modul-Minimum-Fehler, hebe die Zielplattform deiner App auf die des Plugins an, oder verwende eine ältere Plugin-Version.

ITMS-90725: SDK version issue bei der Upload

Die App wurde mit einem SDK erstellt, das Apple nicht mehr akzeptiert. Seit dem 28. April 2026 müssen Uploads mit Xcode 26 und dem iOS 26 SDK erstellt werden. Siehe Apple's Xcode 26-Anforderung für Capacitor-Apps. Capgo-Build bereits mit Xcode 26 baut, wenn du Mac-Runner nicht pflegen möchtest

Swift Package Manager Fehler

Missing package product 'CapApp-SPM'

Xcode konnte die lokale Pakete nicht auflösen oder sein Cache ist veraltet.

1. Datei > Pakete > Paket-Caches zurücksetzen.
2. Datei > Pakete > Paketversionen auflösen.
3. Wenn die App von CocoaPods migriert wurde, überprüfen Sie, ob CapApp-SPM wird unter dem Projekt hinzugefügt Paketabhängigkeiten Kachel ist und auf die App-Ziel verlinkt ist.

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

Eine Plugin- Package.swift verwendet ein Paket oder Produktname, der nicht mit dem, was Capacitor CLI aus seinem npm-Name generiert hat, übereinstimmt. Dies ist ein Plugin-Bug. Aktualisieren Sie das Plugin oder es patchen. Plugin-Autoren finden die Namensregel in einen Capacitor-Plugin auf SPM umstellen.

“Einige installierte Capacitor-Plugins sind nicht mit SPM kompatibel”

Dieser Warnhinweis während cap sync bedeutet, dass mindestens ein Plugin keine 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 nutzen Sie CocoaPods für den Moment.

Doppelte Paketidentität oder Zielname

Zwei Plugins teilen eine Paketidentität oder einen Zielnamen (oft einen allgemeinen Namen wie PluginSeit CLI 8.4 können Sie es von der Capacitor-Konfiguration aus beheben:

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

symlink macht den CLI-Verweis auf das Plugin durch einen Symbolverweis auf einen eindeutigen Pfad. moduleAliases umbenennen Sie einen konfligierenden Modul für diese Abhängigkeit. Melden Sie den Konflikt auch upstream.

Bearbeiten nicht CapApp-SPM/Package.swift

Die CLI übernimmt es bei jedem Synchronisieren neu. Lokale Änderungen verschwinden. Verwenden Sie experimental.ios.spm Konfigurationsoptionen anstelle.

CocoaPods-Fehler

No such module 'Capacitor'

Sie haben geöffnet App.xcodeproj anstatt von App.xcworkspace. Use bunx cap open iosWenn das Workspace geöffnet ist und das Problem weiterhin besteht, führen Sie bunx cap sync ios Zwei Ursachen:

CocoaPods could not find compatible versions for pod "X"

Zwei Ursachen:

1. : führen Sie : run cd ios/App && pod install --repo-update.
2. Konkurrierende Pins: zwei Plugins benötigen inkompatible Versionen des gleichen Pods. Die Fehlermeldung gibt die Kette an. Aktualisieren Sie das Plugin mit strenger Pin-Option, passen Sie die Versionen an (für Firebase, halten Sie alle Firebase-Plugins auf der gleichen SDK-Version), oder patchen Sie die Podspec.

Wenn es weiterhin scheitert, löschen Sie ios/App/Podfile.lock und ios/App/Pods, dann synchronisiere erneut. Dies aktualisiert auch alle Pods, teste daher danach.

The sandbox is not in sync with the Podfile.lock

Laufen bunx cap sync iosEs tritt nach Switches von Branchen oder teilweisen Installationen auf.

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

Your project.pbxproj benutzt eine Formatierung, die Ihre CocoaPods-Version nicht lesen kann. Aktualisieren Sie CocoaPodsbrew upgrade cocoapods bump es in deinem GemfileAls letzte Möglichkeit das Datei sichern und auf niedrigem Level objectVersion.

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

Xcode-Skript-Sandboxing blockiert das CocoaPods-Framework-embed-Skript. Setze Einstellungen > Benutzerskript-Isolierung zu Nein auf dem App-Ziel.

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

Die Simulator-Build-Ausführung läuft für Intel. Auf Apple Silicon bedeutet dies normalerweise, dass Xcode unter Rosetta oder einem alten EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 Die Einstellung wurde von einer alten Workaround übernommen. Führen Sie Xcode natively aus, entfernen Sie diese Einstellung aus dem App-Ziel und aus post_install Hook, dann bereinigen und neu erstellen.

Kompilierungsfehler

Command PhaseScriptExecution failed with a nonzero exit code

Dies ist ein Wrapper. Erweitern Sie die fehlgeschlagene Build-Phase im Report-Navigator und lesen Sie die Skriptausgabe. Häufige Ursachen in Capacitor-Apps:

• Eine Ausführung von Skripten benötigt node und Xcode kann es nicht finden, weil Xcode Ihr Shell-Profil nicht lädt und Node mit nvm, fnm oder Volta installiert ist. Geben Sie den vollständigen Pfad zu node im Skript an oder exportieren Sie PATH am Anfang von ihm.
• Ein Upload-Script für Fehlerberichte (Sentry, Crashlytics) fehlt in CI die Anmeldeinformationen.
• CocoaPods-Embed-Script wird durch Benutzerskript-Sandboxing blockiert (siehe oben).

'X' is only available in iOS 16.0 or newer

Eine Erweiterung verwendet ein API über Ihrer Zielplattform. Erhöhen Sie die Zielplattform in Xcode, in der Podfile (platform :ios, '16.0') wenn Sie CocoaPods verwenden, und überprüfen Sie die README der Erweiterung für ihr Minimum.

Swift 6-Konkurrenzfehler in einer Erweiterung

Nachrichten wie Sending 'x' risks causing data races erscheinen, wenn eine Erweiterung oder Ihr App-Ziel die Swift 6-Sprachmodus verwendet. Capacitor 8 unterstützt Swift 6 nicht offiziell. Halten Sie die App-Ziel auf Swift 5-Sprachmodus, bis die Erweiterung aktualisiert ist.

Code-Signierung

Signing for "App" requires a development team

Öffnen App-Ziel > Signierung und -Fähigkeiten und wählen Sie ein Team. In CI, übergeben Sie DEVELOPMENT_TEAM zu xcodebuild oder verwenden Sie ein Signierungstool. Wenn der Fehler einen Pod-Ressourcen-Bundle anstatt App erwähnt, deaktivieren Sie die Signierung für Bundle-Ziele im Podfile. post_install Hook.

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

Sie haben eine Fähigkeit (Push-Benachrichtigungen, verbundene Domains, Anmeldung mit Apple) ohne Regeneration des Profils hinzugefügt. Aktivieren Sie sie im Apple-Entwickler-Portal auf der App-ID, dann aktualisieren Sie die Profile. Unser iOS-Zertifikatsgenerator hilft Zertifikate ohne Mac-Schüsselkette-Tanz zu erstellen, und der UDID-Finder hilft Testgeräte zu registrieren.

Unable to install "App" auf dem Gerät

Aktivieren Sie den Entwicklermodus auf dem Gerät (Einstellungen > Privatsphäre & Sicherheit > Entwicklermodus), vertrauen Sie dem Entwicklerzertifikat und stellen Sie sicher, dass die Geräte-UDID im Entwicklungsprofil für Entwicklungsbuilds enthalten ist.

Laufzeitfehler

"X" plugin is not implemented on ios

Die JavaScript-Seite fand keine native Implementierung. Überprüfen Sie in dieser Reihenfolge:

1. Der Plugin ist in package.json and you ran bunx cap sync ios nachdem Sie es installiert haben.
2. Für SPM: Der Plugin erscheint in ios/App/CapApp-SPM/Package.swift Wenn nicht, hat es keine Package.swift.
3. Für CocoaPods: Der Plugin erscheint in der capacitor_pods Block der Podfile und pod install keine Warnungen gedruckt wurden.
4. Sie haben keine zwei Plugins, die denselben JS-Namen registrieren (zum Beispiel zwei Push-Benachrichtigungs-Plugins).
5. WKAppBoundDomains ist nicht in Info.plist, oder wenn es ist, limitsNavigationsToAppBoundDomains ist gesetzt und localhost ist aufgelistet. App-grenzennde Domains blockieren die Plugin-Script-Injektion ansonsten.
6. Reinige das Build-Ordner und baue neu. Veraltete Builds speichern alte Plugin-Registrierungen.

Leeres weißes Bildschirmfenster bei Start

Überprüfe den WebView mit Safari Web Inspector zuerst. Die meisten leeren Bildschirme sind ein JavaScript-Fehler.

• Falsch webDir: capacitor.config.ts zeigt auf ein Verzeichnis, das nicht enthält index.htmlÜberprüfe ios/App/App/public.
• Ziel Build zu neu: Ihr Bundler emittiert Syntax, die älterer WebKit nicht unterstützt. iOS 15 ist das Minimum für Capacitor 8, also Ziel safari15 oder später in Vite/esbuild und überprüfe Ihren browserslist.
• Absolute Asset-Pfade: ein base Setze auf einen CDN oder Unterpfad in deiner Bundler-Konfiguration, um lokale Laden zu brechen.
• Live reload nicht erreichbar: Der Entwicklungs-Server muss auf Ihrer LAN-IP lauschen (--host 0.0.0.0), das Telefon muss sich auf derselben Netzwerk befinden und die App benötigt die Lokaler Netzwerk Zugriffsrechte (Einstellungen > Datenschutz & Sicherheit > Netzwerkzugriff). Entfernen Sie server.url aus der Konfiguration vor der Veröffentlichung.
• Live update Paket ist beschädigt: Wenn die App OTA-Updates verwendet, kann ein beschädigtes Paket den Bildschirm leer lassen. Capgo’s Updater rollt automatisch zurück, wenn notifyAppReady() nicht rechtzeitig aufgerufen wird. Siehe die Updater-Dokumentation.

Inhalt unter der Notch oder dem Home-Indikator

Hinzufügen viewport-fit=cover in Ihre Ansichts-Metatag und füllen Sie mit env(safe-area-inset-top) und env(safe-area-inset-bottom). Capacitor 8's System Bars-Plugin steuert die Statusleisten-Stil und -Sichtbarkeit auf beiden Plattformen.

Tastatur bedeckt Eingaben

Konfigurieren Sie die Tastatur-Plugin resize Modus (native, body, ionic oder none) und testen Sie auf einem echten Gerät. Simulatoren behandeln die Tastatur anders.

App Store Connect-Fehler

• ITMS-91053: Missing API declaration: Ihr App oder ein Plugin verwendet ein erforderliches API ohne eine Eintragung in der Datenschutzmanifest. Fügen Sie ein PrivacyInfo.xcprivacy zur App-Ziel mit den Gründen hinzu und aktualisieren Sie Plugins, die ihre eigenen Manifeste liefern.
• ITMS-90725: SDK version issue: mit Xcode 26 neu erstellen.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': Ein Framework ist in einer Erweiterung oder einem anderen Framework eingebettet. Überprüfen Sie Einbetten Einstellungen für App-Erweiterungen.

Wie man debuggt, wenn der Fehler nicht aufgelistet ist

1. Safari Web-Inspector für JS-Fehler und Netzwerkaufrufe. Debug-Builds sind auf iOS 16.4+ überprüfbar. Für Release-Builds setzen Sie ios.webContentsDebuggingEnabled: true temporär.
2. Xcode-Konsolen für native Logs, einschließlich Capacitor’s ⚡️ Brückenmeldungen, die jede Pluginaufruf anzeigt.
3. Terminal mit dem ausgewählten Gerät für Crash und Systemprotokollen.
4. Isolieren: Erstellen Sie eine frische App mit bun create @capacitor/app, fügen Sie nur den verdächtigen Plugin hinzu und sehen Sie, ob der Fehler reproduziert wird.

Das Ultimative Führer zum Debuggen von Capacitor Apps geht tiefer in jeden Tool ein. Wenn die Ursache ein Plugin-Bug ist, ist ein Patch wird normalerweise am schnellsten gelöst, während Sie auf eine neue Version warten.