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

Die meisten Capacitor-iOS-Probleme gehören zu fünf Gruppen: falsche Werkzeuge, Abhängigkeitslö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 doctorBestätigen Sie, dass Xcode 26 ausgewählt ist, ausführen bunx cap sync iosund lesen Sie die erste Fehlermeldung im Xcode-Build-Log, nicht die letzte.

Diese Anleitung listet die häufigsten Fehler in Capacitor 8 Projekten auf, ihre Ursachen und die Lösung. Für Android siehe die Capacitor Android-Fehlersuche-Anleitung.

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

• Versionen: @capacitor/core, @capacitor/ios und @capacitor/cli Müssen dieselbe Hauptversion haben. Ungleichheiten führen zu ungewöhnlichen Kompilations- und Laufzeitfehlern. Siehe fix Capacitor Versionsungleichheit-Fehler.
• Eines Xcode: Wenn Sie mehrere Xcode-Versionen haben, xcode-select -p entscheidet, welches der CLI verwendet. Stellen 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 Werkzeugkette

Xcode oder SDK ist 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 zeigt nicht immer auf das Bild mit der neuesten Xcode-Version. Pinnen Sie ein Bild, das Xcode 26 enthält, und wählen Sie es ausdrücklich aus.

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

Überprüfen Sie die Dokumentation der Runner-Bilder für den genauen Pfad. Für das Modul-Minimum-Fehler heben Sie die Zielplattform Ihres Apps auf die des Plugins an oder verwenden Sie eine ältere Plugin-Version.

ITMS-90725: SDK version issue bei der Upload

Die Veröffentlichung wurde mit einem älteren SDK erstellt, das Apple derzeit 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 baut bereits auf Xcode 26, wenn Sie Mac-Runner nicht aufrechterhalten möchten.

Swift Package Manager-Fehler

Missing package product 'CapApp-SPM'

Xcode hat die lokale Paketdatei nicht gelöst oder ihr 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 in der Projekt-Einstellungen Paketabhängigkeiten Tab und verknüpft mit dem Ziel App.

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

A Plugin verwendet Package.swift verwendet ein Paket oder Produktname, der nicht mit dem von Capacitor CLI generierten Namen aus seinem npm-Namen übereinstimmt. Dies ist ein Pluginfehler. Aktualisieren Sie das Plugin oder patchen Sie es. Plugin-Autoren finden die Namensregel in migrieren Sie ein Capacitor-Plugin in SPM.

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

Diese Warnung während cap sync bedeutet, dass mindestens ein Plugin keine Package.swifthat. Es wird aus der App ausgelassen, sodass Aufrufe an es mit „nicht implementiert“ fehlschlagen. Aktualisieren Sie das Plugin, ersetzen Sie es durch eines, das SPM unterstützt, oder nutzen Sie CocoaPods für den Moment.

Duplicate Paket-Identität oder Zielname

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

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

symlink stellt die CLI-Referenz auf den Plugin über einen Symbolverweisordner mit einem eindeutigen Pfad her. moduleAliases umbenennen Sie einen konkurrierenden Modul für diese Abhängigkeit. Melden Sie den Konflikt auch upstream.

Klicken Sie nicht CapApp-SPM/Package.swift

Die CLI überarbeitet es bei jeder Synchronisierung. Lokale Änderungen verschwinden. Verwenden Sie experimental.ios.spm Konfigurationsoptionen anstelle.

CocoaPods-Fehler

No such module 'Capacitor'

anstatt App.xcodeproj Verwenden Sie App.xcworkspace. Use bunx cap open iosWenn das Workspace geöffnet ist und das Problem weiterhin besteht, führen Sie bunx cap sync ios wiederherstellen Sie die Pods.

CocoaPods could not find compatible versions for pod "X"

Zwei Ursachen:

1. Veralteter Spezifikations-Repo: ausführen 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. Stellen Sie den Plugin mit dem strengen Pin auf den neuesten Stand, passen Sie die Versionen an (für Firebase, halten Sie alle Firebase-Plugins auf der gleichen SDK-Version) oder patchen Sie den Podspec.

Wenn es weiterhin fehlschlägt, löschen Sie ios/App/Podfile.lock und ios/App/Podssynchronisieren Sie dann erneut. Dies aktualisiert auch jeden Pod, daher sollten Sie danach testen.

The sandbox is not in sync with the Podfile.lock

Ausführen bunx cap sync iosEs tritt nach Branch-Umstellungen oder Teilinstallationen auf.

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

Ihr project.pbxproj benutzt eine Formatierung, die Ihre CocoaPods-Version nicht lesen kann. Aktualisieren Sie CocoaPodsbrew upgrade cocoapods oder erhöhen Sie es in Ihrem Gemfile. Als letztes Mittel, sichern Sie die Datei und verringern Sie objectVersion.

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

Xcode-Skript-Sandboxing blockiert das CocoaPods-Framework-embed-Skript. Setze Build Einstellungen > Benutzer-Script-Sandboxing 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. Bei Apple Silicon bedeutet dies normalerweise, dass Xcode unter Rosetta läuft oder ein altes EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 Die Einstellung ist von einem alten Workaround übrig geblieben. Führen Sie Xcode natively aus, entfernen Sie diese Einstellung aus dem App-Ziel und aus jedem post_install Haken, dann bereinigen und neu bauen.

Kompilierungsfehler

Command PhaseScriptExecution failed with a nonzero exit code

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

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

'X' is only available in iOS 16.0 or newer

Ein Plugin verwendet ein API über deinen Bereitstellungsziel. Erhöhe das Ziel in Xcode, in dem Podfile (platform :ios, '16.0'"), wenn du CocoaPods verwendest, und überprüfe die README des Plugins für sein Minimum.

Eine Swift 6-Konkurrenzfehler in einem Plugin

Botschaften wie Sending 'x' risks causing data races erscheinen, wenn ein Plugin oder dein App-Ziel die Swift 6-Sprachmodus verwendet. Capacitor 8 unterstützt Swift 6 nicht offiziell. Halte das App-Ziel auf Swift 5-Sprachmodus, bis das Plugin aktualisiert ist.

Code Signierung

Signing for "App" requires a development team

Öffnen App-Ziel > Signieren & Fähigkeiten und wählen Sie ein Team. In CI, übergeben Sie DEVELOPMENT_TEAM zu xcodebuild oder verwenden Sie ein Signierungstool. Wenn der Fehler ein Pod-Ressourcen-Bundle anstatt der App erwähnt, deaktivieren Sie das Signieren 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 auf dem App-ID im Apple-Entwicklerportal, dann aktualisieren Sie die Profile. Unsere iOS-Zertifikatsgenerator hilft Zertifikate ohne Mac-Schüssel-Tanz zu erstellen, und der UDID-Finder hilft Testgeräte anzumelden.

Unable to install "App" auf Gerät

Entwicklermodus auf dem Gerät aktivieren (Einstellungen > Datenschutz & Sicherheit > Entwicklermodus), den Entwicklerzertifikat vertrauen und sicherstellen, dass die Geräte-UDID im Entwicklungsprofil für Entwicklungsbau 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 und Sie haben es bunx cap sync ios nach der Installation ausgeführt.
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 im capacitor_pods Block der Podfile und pod install hat keine Warnungen gedruckt.
4. Sie haben keine zwei Plugins, die denselben JS-Namen registrieren (z.B. zwei Push-Benachrichtigungs-Plugins).
5. WKAppBoundDomains ist nicht in Info.plist, oder wenn es ist limitsNavigationsToAppBoundDomains ist gesetzt und localhost wird aufgelistet. App-grenzennde Domains blockieren die Plugin-Script-Injektion andernfalls.
6. Löschen Sie den Build-Ordner und bauen Sie neu. Veraltete Builds halten alte Plugin-Registrierungen.

Blankes weißes Bildschirm auf Start

Überprüfen Sie zunächst die WebView mit Safari Web Inspector. Die meisten leeren Bildschirme sind ein JavaScript-Fehler.

• Falsch webDir: capacitor.config.ts zeigt auf einen Ordner, der keinen index.html. Check ios/App/App/public.
• Build-Ziel zu neuIhr Bundler sendet Syntax, die von älteren WebKit-Versionen nicht unterstützt wird. Für iOS 15 ist mindestens Version 8 von Capacitor erforderlich. safari15 oder später in Vite/esbuild und überprüfen Sie Ihre browserslist.
• Absolute Asset-Pfade: ein base Setze es auf eine CDN oder ein Unterpfad in deiner Bundler-Konfiguration, um lokale Laden zu brechen.
• Live-Reload nicht erreichbar: der Entwicklungs-Server muss auf Ihrer LAN-IP (--host 0.0.0.0), das Telefon muss sich im gleichen Netzwerk befinden und die App benötigt die Lokaler Netzwerk Erlaubnis (Einstellungen > Privatsphäre & Sicherheit > Lokales Netzwerk). Entfernen server.url aus der Konfiguration vor der Veröffentlichungsversion.
• Live update Paket gebrochenWenn die App OTA-Updates verwendet, kann ein defekter Bundle die Bildschirmleiste leer lassen. Capgos Updater fährt automatisch zurück, wenn notifyAppReady() wird nicht rechtzeitig aufgerufen. Siehe die Updater-Dokumentation.

Inhalt unter der Notch oder dem Home-Indikator

Hinzufügen viewport-fit=cover zur Ihrem Viewport-Meta-Tags und füllen Sie mit env(safe-area-inset-top) und env(safe-area-inset-bottom). Capacitor Die 8's System Bars-Plugin steuert die Statusleisten-Stil und -Sichtbarkeit auf beiden Plattformen.

Tastatur bedeckt Eingabefelder

Konfigurieren Sie die Tastatur-Plugin resize Modus (native, body, ionic oder noneund testen Sie es 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 einen erforderlichen Grund API ohne Eintrag im Datenschutzmanifest. Fügen Sie ein PrivacyInfo.xcprivacy zur App-Ziel mit den Gründen hinzu und aktualisieren Sie Plugins, die ihr eigenes Manifest liefern.
• ITMS-90725: SDK version issue: Rebuild mit Xcode 26.
• 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 Sie debuggen, wenn der Fehler nicht aufgeführt wird

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

Das ultimative Handbuch zum Debuggen von Capacitor-Apps geht tiefer in jeden Tool ein. Wenn die Ursache ein Pluginfehler ist, ein Patch ist in der Regel die schnellste Lösung, während Sie auf eine neue Version warten.