Capacitor iOSのトラブルシューティング: 一般的なエラーと修正

Capacitor iOSの問題の多くは、5つのグループに分類されます: 不正なツールチェーン、依存関係の解決 (SPMまたはCocoaPods)、プラグインからのコンパイルエラー、code署名、実行時エラーである「プラグインが実装されていない」または白いWebView。 bunx cap doctor最初に bunx cap sync ios確認してください。Xcode 26が選択されていることを確認し、

This guide lists the errors we see most in Capacitor 8 projects, what causes each one, and the fix. For Android, see the Capacitor Androidのトラブルシューティングガイド.

Quick triageチェックリスト

以下のステップを実行して、特定のエラーを追跡する前に行ってみましょう:

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

• バージョン: @capacitor/core, @capacitor/ios そして @capacitor/cli バージョンが同じメジャーである必要があります。バージョンが一致しないと、コンパイルや実行時エラーが発生することがあります。詳細は fix Capacitor version mismatch errors.
• Xcode: Xcodeのバージョンが複数ある場合、 xcode-select -p CapacitorのiOSビルドエラーを解決するには、CapacitorがどのCLIを使用するかを決定する必要があります。 sudo xcode-select -s /Applications/Xcode.app.
• パッケージマネージャー: if ios/App/CapApp-SPM SPMが存在する場合、プロジェクトはSPMを使用します。SPMが存在しない場合、CocoaPodsを使用します。 ios/App/Podfile Toolchainエラー

Xcodeまたは__CAPGO_KEEP_0__が古すぎる

XcodeもSDKも古い

, Swiftの構文エラー value of type 'WKWebView' has no member 'isInspectable', または Capacitor, or compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 は Xcode 26 が必要です。 GitHub Actions で、 macos-latest アップロード時

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

__CAPGO_KEEP_0__

ITMS-90725: SDK version issue __CAPGO_KEEP_1__

The build was made with an SDK older than Apple currently accepts. Since April 28, 2026, uploads must be built with Xcode 26 and the iOS 26 SDK. See AppleのXcode 26の要件は、Capacitorアプリに適用されます。. Capgo ビルド __CAPGO_KEEP_0__

__CAPGO_KEEP_0__はすでにXcode 26でビルドされているので、Macランナーの維持を避ける場合は、Macランナーを維持する必要はありません。

Missing package product 'CapApp-SPM'

Swift Package Managerエラー

1. Xcodeはローカルパッケージを解決できません、またはキャッシュが古くなっています。.
2. ファイル>パッケージ>キャッシュをリセット.
3. ファイル>パッケージ>パッケージバージョンを解決 CapApp-SPM アプリがCocoaPodsからマイグレーションされた場合、プロジェクトの パッケージ依存関係 タブに追加して、アプリターゲットにリンクされていることを確認してください。

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

プラグインの 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 がプラグイン作者は、命名規則はここで確認できます。 migrate a Capacitor plugin to SPM.

「インストール済みの Capacitor プラグインは一部SPMに非互換です」

プラグインの作者は、 cap sync に記載されている名前付けルールを確認してください。 Package.swiftを参照してください。 “Some installed __CAPGO_KEEP_0__ plugins are not compatible with SPM”.

この警告が表示される場合、少なくとも1つのプラグインが

が含まれていないことを意味します。 Plugin. CLI 8.4 から、Capacitor の設定から修正できます。

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

symlink CLI をシンボリックリンクフォルダに置き換え、ユニークなパスを使用します。 moduleAliases 依存関係のモジュールを再定義します。上流に問題を報告することもできます。

編集しないでください。 CapApp-SPM/Package.swift

CLI は、毎回の同期時に再書き込みされます。ローカル編集は失われます。代わりに、 experimental.ios.spm 設定オプションを使用してください。

CocoaPods エラー

No such module 'Capacitor'

をオープンした App.xcodeproj の代わりに App.xcworkspace. Use bunx cap open iosを実行して、モジュールを再インストールしてください。 bunx cap sync ios __CAPGO_KEEP_0__

CocoaPods could not find compatible versions for pod "X"

2つの原因:

1. 古いspecリポジトリ:実行 cd ios/App && pod install --repo-update.
2. 競合するピン:2つのプラグインが互いに不相応のバージョンの同じポッドを必要としています。エラーはチェーンを印刷します。プラグインをアップグレードする、バージョンを整合させる（Firebaseの場合、すべてのFirebaseプラグインを同じSDKバージョンに保つ）、またはポッドスペックを修正します。

もしもそれが続いて失敗する場合、削除 ios/App/Podfile.lock そして ios/App/Pods、そしてsyncを再度実行すると、すべてのポッドもアップグレードされるので、後でテストしてください。

The sandbox is not in sync with the Podfile.lock

実行 bunx cap sync iosbranch switch または部分的なインストール後も発生します。

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

実行 project.pbxproj CocoaPodsのバージョンが読み取ることができない形式を使用しています。CocoaPodsをアップデートしてください。brew upgrade cocoapods または、バージョンを上げる Gemfile。最後の手段として、ファイルをバックアップし、 objectVersion.

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

Xcodeのユーザー スクリプトのサンドボックス設定がCocoaPodsフレームワークのエンビデッド スクリプトをブロックしている場合、 設定 > ビルド設定 > ユーザー スクリプトのサンドボックス を に設定します。 に

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

です。 EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 アプリのターゲット上で post_install シミュレータのビルドはIntel用に実行されています。Apple Siliconの場合、通常XcodeはRosettaで実行されますか、または過去のワークアラウンドから残っている設定が残っています。Xcodeを本来の環境で実行し、設定をアプリのターゲットとhookから削除し、クリーンし直してください。

コンパイルエラー

Command PhaseScriptExecution failed with a nonzero exit code

これはラッパーです。レポートナビゲータで失敗したビルドフェーズを展開し、スクリプトの出力を読みます。Capacitorアプリの一般的な原因は:

• A Run Script が必要 node Xcode がそのパスを検索できないため、Xcode はシェルプロファイルを読み込まない。Node は nvm、fnm、または Volta でインストールされている。スクリプト内でフルパスを指定するか、 node export をスクリプトの先頭に追加する。 PATH CI でのクラッシュレポートアップロードスクリプト (Sentry、Crashlytics) が資格情報を欠いている。
• CocoaPods のエンビッドスクリプトがユーザースクリプトサンドボックスによってブロックされている (上記を参照)。
• CocoaPods embed スクリプトがユーザー スクリプト サンドボックスによってブロックされています (上記を参照)。

'X' is only available in iOS 16.0 or newer

プラグインが API を使用しており、デプロイ対象のバージョンより上のバージョンを使用しています。Xcodeのバージョンを上げてください。Podfileも確認してください。platform :ios, '16.0'次のようなメッセージが表示される。

Swift 6 の並行処理エラー

__CAPGO_KEEP_0__ の署名 Sending 'x' risks causing data races show up when a plugin or your app target uses Swift 6 language mode. Capacitor 8 doesn’t officially support Swift 6. Keep the App target on Swift 5 language mode until the plugin is updated.

Code サインイン

Signing for "App" requires a development team

Open App target > Signing & Capabilities とチームを選択してください。CIでは DEVELOPMENT_TEAM に xcodebuild または署名ツールを使用してください。エラーがPodリソースバンドルを指している場合、Podfileでバンドルターゲットの署名を無効にしてください post_install hook

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

Push通知、関連ドメイン、Appleサインイン機能を追加したが、プロファイルを再生成していません。Apple Developer PortalでApp IDに有効にし、プロファイルを更新してください。 iOS証明書生成ツール Macキーチェーンダンスなしで証明書を作成するのに役立ちます。 UDID検索ツール テストデバイスの登録に役立ちます。

Unable to install "App" デバイス上

デバイスで開発者モードを有効にし(設定 > プライバシー & セキュリティ > 開発者モード)、開発者証明書を信頼し、デバイスのUDIDが開発用のプロビジョニングプロファイルに含まれていることを確認します。

ランタイムエラー

"X" plugin is not implemented on ios

JavaScript側では、ネイティブ実装が見つかりませんでした。次の順序で確認してください:

1. プラグインが package.json そしてインストールした後 bunx cap sync ios SPMの場合: プラグインは
2. が表示されます。そうでない場合、 ios/App/CapApp-SPM/Package.swiftCocoaPodsの場合: プラグインは Package.swift.
3. のPodfileのブロック内に表示され、 capacitor_pods 警告も出ませんでした。 pod install 2つのプラグインが同じJS名を登録していないことを確認します(例えば、2つのプッシュ通知プラグイン)。
4. 同じJS名を2つのプラグインが登録していることがあります。
5. WKAppBoundDomains ない Info.plistまたは、もし。 limitsNavigationsToAppBoundDomains は設定されています。 localhost iOSアプリのドメインがリストされている場合、プラグインスクリプトのインジェクションはブロックされます。
6. ビルドフォルダをクリーンし、再ビルドしてください。古いビルドは古いプラグインの登録を保持しています。

起動時白い画面

Safari Web インスペクターで WebView を確認してください。ほとんどの白い画面は JavaScript エラーです。

• Wrong webDir: capacitor.config.ts ポイントは、 index.html. Check ios/App/App/public.
• ビルド対象のiOSのバージョンが最新です。iOS 15が最低限のバージョンで、Capacitor 8の場合、ターゲット safari15 Vite/esbuild またはそれ以降で、 browserslist.
• 絶対的なアセットのパス: base CDN またはサブパスを設定した場合、ローカルロードが機能しなくなります。
• Live reload のアクセスが不可能:--host 0.0.0.0開発サーバーはローカルネットワークの IP アドレスで実行する必要があります ( )、電話は同じネットワークに接続している必要があり、そしてアプリには ローカルネットワーク server.url の許可が必要です (設定 > 秘密情報とセキュリティ > ローカルネットワーク)。
• Live update バンドルが破損しています。: アプリがOTA更新を使用している場合、不正なバンドルは画面を白くする可能性があります。Capgoのアップデーターは自動的にロールバックします。 notifyAppReady() タイムアウトされていません。アップデートのドキュメントを参照してください。 アップデータのドキュメント.

ノッチまたはホームインジケータの下のコンテンツ

追加 viewport-fit=cover viewport メタタグに追加して、スペースで埋めます。 env(safe-area-inset-top) and env(safe-area-inset-bottom).Capacitor 8のシステムバー プラグインは、両方のプラットフォームでステータス バーのスタイルと表示を制御します。

モード (

または システムバーのスタイルと表示を制御する8のシステムバー プラグインは、両方のプラットフォームで機能します。 resize mode (native, body, ionic or none実機でテストしてください。シミュレータはキーボードを扱う方法が異なります。

App Store Connectエラー

• ITMS-91053: Missing API declaration:アプリまたはプラグインが必須理由APIを使用しているが、プライバシーマニフェストのエントリが存在しない場合、必須理由APIを追加し、プラグインを更新してください。 PrivacyInfo.xcprivacy :Xcode 26で再構築してください。
• ITMS-90725: SDK version issue:フレームワークが拡張機能または別のフレームワーク内に埋め込まれている場合、確認してください。
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks'埋め込む Embed エラーがリストに表示されていない場合のデバッグ方法

Safari Web インスペクター

1. JSエラーとネットワークコールのデバッグに使用してください。iOS 16.4以降のデバッグビルドはインスペクタブルです。リリースビルドの場合は一時的に設定してください。 一時的に設定してください。 ios.webContentsDebuggingEnabled: true temporarily.
2. Xcodeコンソール ネイティブログのため、Capacitorの ⚡️ ブリッジメッセージが各プラグインコールを表示する
3. コンソールアプリ デバイスを選択してクラッシュとシステムログを表示
4. 分離: 新しいアプリを作成し、 bun create @capacitor/app、疑似プラグインのみを追加し、エラーが再現されるかどうかを確認

The Capacitorアプリの デバッグの究極のガイド patch 通常、リリースを待つ間の最短のブロックです。