Capacitor iOS の問題の多くは、ツールチェーンの誤り、依存関係の解決（SPM または CocoaPods）、プラグインによるコンパイルエラー、code の署名、「plugin is not implemented」や WebView が真っ白になるといったランタイムの問題の5つに分類されます。まずは bunx cap doctor、Xcode 26 が選択されていることを確認してから、 bunx cap sync ios、そして最後ではなく、Xcodeのビルドログの最初のエラーを確認してください。
このガイドでは、Capacitor 8のプロジェクトで頻繁に発生するエラーの原因と解決策をまとめています。Androidについては、以下を参照してください： Capacitor Androidトラブルシューティングガイド.
クイックトリアージチェックリスト
特定のエラーを追う前に、これらを実行してください：
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メジャーバージョンが一致している必要があります。不一致があると、妙なコンパイルエラーやランタイムエラーの原因となります。詳細は Capacitor のバージョン不一致エラーを修正する方法. - Xcodeを1つに：複数のXcodeバージョンがある場合、
xcode-select -pCLI がどれを使うかを決めます。修正するには：sudo xcode-select -s /Applications/Xcode.app. - どのパッケージマネージャーか：
ios/App/CapApp-SPMが存在すれば、プロジェクトはSPMを使用しています。ios/App/Podfileが存在すれば、CocoaPodsを使用しています。
ツールチェーンエラー
XcodeまたはSDKが古すぎる
症状: value of type 'WKWebView' has no member 'isInspectable'、内部のSwift構文エラー Capacitor、または 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 必ずしも最新の Xcode を含むイメージを指すとは限りません。Xcode 26 を含むイメージを固定し、明示的に選択してください:
- run: sudo xcode-select -s /Applications/Xcode_26.0.app正確なパスについてはランナーイメージのドキュメントを確認してください。モジュールの最低要件エラーの場合、アプリのデプロイメントターゲットをプラグインの最低要件以上に引き上げるか、古いバージョンのプラグインを使用してください。
ITMS-90725: SDK version issue アップロード時
ビルドに使用された SDK が、Apple が現在受け入れているバージョンより古いです。2026年4月28日以降、アップロードには Xcode 26 と iOS 26 SDK でのビルドが必須です。詳細は Appleによる Capacitor アプリ向けのXcode 26要件. Capgo のビルド Macランナーのメンテナンスを避けたい場合、Xcode 26でビルド可能です。
Swift Package Manager エラー
Missing package product 'CapApp-SPM'
Xcode がローカルパッケージを解決していないか、キャッシュが古くなっています。
- File > Packages > Reset Package Caches.
- File > Packages > Resolve Package Versions を.
- アプリが CocoaPods から移行された場合は、
CapApp-SPMがプロジェクトの パッケージの依存関係 タブに追加され、App ターゲットにリンクされていることを確認してください。
product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found
プラグインの Package.swift が、npm 名から Capacitor CLI が生成したパッケージ名またはプロダクト名と一致しません。これはプラグインのバグです。プラグインをアップデートするか、 パッチを適用してください。プラグイン作成者は命名規則を Capacitor プラグインを SPM に移行する.
「インストール済みの Capacitor プラグインの一部が SPM と互換性がない」
この警告は cap sync 中に少なくとも 1 つのプラグインに Package.swift. アプリに含まれないため、呼び出すと「not implemented」で失敗します。プラグインをアップグレードするか、SPM対応のプラグインに置き換えるか、 当面は CocoaPods を使用してください.
パッケージ識別子またはターゲット名の重複
2つのプラグインがパッケージ識別子またはターゲット名を共有しています（多くの場合、次のような汎用的な名前 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 その依存関係で競合しているモジュール名を変更します。この競合は upstream にも報告してください。
編集しないでください CapApp-SPM/Package.swift
CLI は sync のたびにそれを書き換えます。ローカルでの編集は消えます。代わりに experimental.ios.spm 設定オプションを使用してください。
CocoaPods のエラー
No such module 'Capacitor'
開いた App.xcodeproj の代わりに App.xcworkspace. 入力が不正な場合は、 bunx cap open ios。ワークスペースが開いていてエラーが続く場合は、実行してください bunx cap sync ios pods を再インストールします。
CocoaPods could not find compatible versions for pod "X"
原因は2つ:
- 古い spec リポジトリ: 実行
cd ios/App && pod install --repo-update. - 競合するピン留め: 2つのプラグインが同じ pod の互換性のないバージョンを必要としています。エラーにチェーンが表示されます。厳密なピン留めをしているプラグインをアップグレードし、バージョンを揃えます（Firebase の場合は、すべての Firebase プラグインを同じ SDK バージョンに保ちます）、または podspec をパッチします。
それでも失敗が続く場合は、削除してください ios/App/Podfile.lock と ios/App/Pods、その後再度同期します。これによりすべての pod がアップグレードされるため、その後テストしてください。
The sandbox is not in sync with the Podfile.lock
実行 bunx cap sync ios。ブランチの切り替えや部分的なインストールの後に発生します。
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 のフレームワーク埋め込みスクリプトをブロックしています。 ビルド設定 > ユーザースクリプトのサンドボックス まで いいえ を App ターゲットで設定してください。
could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'
シミュレータのビルドが Intel 向けに実行されています。Apple Silicon では、Xcode が Rosetta 経由で実行されているか、古い EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 この設定は過去のワークアラウンドの名残です。Xcode をネイティブで実行し、App ターゲットおよびすべての post_install フックからその設定を削除してから、クリーンして再ビルドしてください。
コンパイルエラー
Command PhaseScriptExecution failed with a nonzero exit code
これはラッパーです。レポートナビゲータで失敗している Build Phase を展開し、スクリプトの出力を確認してください。Capacitor アプリでよくある原因は次のとおりです：
- Run Script には
nodeが必要ですが、Xcode はシェルプロファイルを読み込まないため、nvm、fnm、Volta でインストールした Node を見つけられません。スクリプト内でnodeのフルパスを使うか、スクリプトの先頭でPATHを export してください。 - クラッシュレポートのアップロードスクリプト（Sentry、Crashlytics）に CI の認証情報が設定されていません。
- User Script Sandboxing により CocoaPods の embed スクリプトがブロックされています（上記参照）。
'X' is only available in iOS 16.0 or newer
プラグインがデプロイターゲットより高い API を使用しています。Xcode で、CocoaPods を使っている場合は Podfile（platform :ios, '16.0'）でもターゲットを上げ、プラグインの README で最小要件を確認してください。
プラグインでの Swift 6 並行処理エラー
次のようなメッセージが表示されるのは、 Sending 'x' risks causing data races プラグインやアプリのターゲットが Swift 6 言語モードを使っている場合です。Capacitor 8 は Swift 6 を正式にサポートしていません。プラグインが更新されるまで、App ターゲットは Swift 5 言語モードのままにしてください。
Code の署名
Signing for "App" requires a development team
開く App target > Signing & Capabilities チームを選択します。CIでは、次を渡します DEVELOPMENT_TEAM まで xcodebuild または署名ツールを使用します。エラーがAppではなくPodのリソースバンドルを指している場合は、Podfileでバンドルターゲットの署名を無効にします。 post_install hook。
Provisioning profile "X" doesn't include the ... entitlement
プロファイルを再生成せずにCapability（Push Notifications, Associated Domains, Sign in with Apple）を追加しました。Apple DeveloperポータルのApp IDで有効にしてから、プロファイルを更新してください。当社の iOS証明書ジェネレーター Mac のキーチェーン操作なしで証明書を作成でき、 UDID 検索ツール テストデバイスの登録を支援します。
Unable to install "App" デバイス上
デバイスで開発者モードを有効にし（設定 > プライバシーとセキュリティ > 開発者モード）、開発者証明書に信頼を設定し、開発ビルド用のプロビジョニングプロファイルにデバイスの UDID が含まれていることを確認してください。
ランタイムエラー
"X" plugin is not implemented on ios
JavaScript 側でネイティブ実装が見つかりませんでした。以下の順で確認してください：
- プラグインが
package.jsonにあり、インストール後にbunx cap sync iosを実行しました。 - SPM の場合、プラグインが
ios/App/CapApp-SPM/Package.swiftに表示されます。表示されない場合は、Package.swift. - CocoaPods の場合: プラグインは
capacitor_podsの Podfile のブロックに存在し、pod install警告は出力されていませんでした。 - 同じJS名を登録しているプラグインが2つないこと（例：プッシュ通知プラグインが2つなど）。
WKAppBoundDomainsに含まれていませんInfo.plist、または含まれている場合、limitsNavigationsToAppBoundDomainsが設定されており、localhostがリストされている。そうでない場合、App-bound domains がプラグインのスクリプト注入をブロックします。- ビルドフォルダをクリーンして再ビルドしてください。古いビルドが残っていると、古いプラグイン登録も残ります。
起動時に画面が真っ白になる
まずSafari Web InspectorでWebViewを確認してください。真っ白な画面の多くはJavaScriptエラーが原因です。
- 誤り
webDir:capacitor.config.tsが、…を含まないフォルダを指していますindex.htmlを確認してください。ios/App/App/public. - ビルドターゲットが新しすぎる: バンドラーが古い WebKit ではサポートされない構文を出力しています。Capacitor 8 の最小要件は iOS 15 なので、Vite/esbuild の target を iOS 15
safari15以降に設定し、以下を確認してください：browserslist. - アセットの絶対パス：
baseバンドラー設定で CDN やサブパスに設定すると、ローカルでの読み込みが失敗します。 - Live reload に接続できない: 開発サーバーが LAN IP (
--host 0.0.0.0）で待機している必要があります。また、スマホが同じネットワークに接続されている必要があり、アプリに ローカルネットワーク の権限（設定 > プライバシーとセキュリティ > ローカルネットワーク）が必要です。リリースビルドの前に config からserver.url削除してください。 - Live update bundle が壊れている：アプリがOTA更新を使用している場合、不良なバンドルが画面を白くすることがあります。Capgo のアップデーターは、
notifyAppReady()が間に合わず呼び出されない場合です。 updater のドキュメント.
ノッチやホームインジケーターの下にコンテンツが重なる
追加 viewport-fit=cover をビューポートメタタグに追加し、 env(safe-area-inset-top) と env(safe-area-inset-bottom)。Capacitor 8 の System Bars プラグインは、両プラットフォームでステータスバーのスタイルと表示を制御します。
キーボードが入力フィールドを覆う
次の Keyboard プラグイン resize モード (native, body, ionic または none)、実機でテストしてください。シミュレーターではキーボードの挙動が異なります。
App Store Connect のエラー
ITMS-91053: Missing API declaration: アプリまたはプラグインが、プライバシーマニフェストに記載のない required-reason の API を使用しています。次を追加:PrivacyInfo.xcprivacyApp ターゲットに理由とともに追加し、独自のマニフェストを同梱するプラグインを更新してください。ITMS-90725: SDK version issue: Xcode 26 で再ビルドしてください。Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': フレームワークが extension または別のフレームワーク内に埋め込まれています。次を確認してください: 埋め込み app extension の設定。
エラーが一覧にない場合のデバッグ方法
- Safari Web Inspector JS エラーやネットワーク通信の確認に。デバッグビルドは iOS 16.4 以降で検査可能です。リリースビルドの場合は次を設定:
ios.webContentsDebuggingEnabled: true一時的に。 - Xcode コンソール ネイティブログ（Capacitor のログを含む）
⚡️各プラグイン呼び出しを表示するブリッジメッセージ。 - Console.app デバイスを選択して、クラッシュログやシステムログを確認します。
- 切り分ける：で新しいアプリを作成します
bun create @capacitor/app、疑わしいプラグインのみを追加して、エラーが再現するか確認します。
この Capacitor アプリのデバッグ完全ガイドで紹介しています。 各ツールを詳しく掘り下げます。根本原因がプラグインのバグなら、 パッチ は通常、リリースを待つ間の最速の打開策です。
