CapacitorアプリをSwift Package Managerに移行する方法

Capacitor 8 は、Swift Package Manager (SPM) を使用してデフォルトで新しい iOS プロジェクトを作成します。まだ CocoaPods を使用している既存のアプリも移行できますが、安全なパスはアプリのネイティブ iOS カスタマイズの量に依存します。

This guide explains the changes, what to back up, and the two practical migration paths: using the Capacitor migration assistant or re-scaffolding the iOS project with SPM.

Why migrate now

CocoaPods は、読み取り専用のトランクに移行しています。現在の計画では、CocoaPods トランクは 2026 年 12 月 2 日以降、新しい podspecs を受け付けなくなります。 。既存のビルドは正常に動作するはずですが、トランクを切り替えた後、新しいリリースや依存関係の更新がトランクに依存している場合、そこから公開されなくなります。SPM も __CAPGO_KEEP_0__ の方向性です。 __CAPGO_KEEP_1__ は、__CAPGO_KEEP_2__ 6 から CocoaPods または SPM を選択する機能をサポートし、__CAPGO_KEEP_3__ 8 は iOS SPM プロジェクトを作成するデフォルトのテンプレートとしています。

SPM is also the direction Capacitor is moving. Capacitor has supported choosing CocoaPods or SPM since Capacitor 6, and Capacitor 8 now creates iOS SPM projects as the default template.

CocoaPods から SPM に移行すると、iOS の依存関係層が置き換えられます。ウェブアプリ、Android プロジェクト、およびほとんどの Capacitor ワークフロー コマンドは同じままです。

Migrating from CocoaPods to SPM replaces the iOS dependency layer. The web app, Android project, and most Capacitor workflow commands stay the same.

CocoaPods アプリでは、iOS の依存関係は

、でワイヤードされています。生成された ios/App/Podfile, Podfile.lock, Pods/__CAPGO_KEEP_0__ 8 は、Swift Package Manager (SPM) を使用してデフォルトで新しい iOS プロジェクトを作成します。まだ CocoaPods を使用している既存のアプリも移行できますが、安全なパスはアプリのネイティブ iOS カスタマイズの量に依存します。 .xcworkspace.

In SPM アプリでは、Capacitor がローカル パッケージを生成し、その名前は CapApp-SPM. このパッケージは、Capacitor がネイティブ iOS プラグイン依存関係を参照する中心となる場所になります。 Capacitor CLI は、プラグインを同期するたびに自動的に更新されるため、手動で編集しないでください。 CapApp-SPM debug.xcconfig は Pods 設定を置き換えます。

マイグレーション アシスタントは、生成された

ファイルも作成します。このファイルには、CocoaPods が生成した xcconfig ファイルから提供されていたビルド設定が含まれます。 debug.xcconfigマイグレーション後、開発者は Xcode プロジェクトの設定に

を追加する必要がある場合があります。アシスタントがこのように指示した場合にのみ追加してください。 debug.xcconfig すべてのプラグインは SPM をサポートする必要があります。

SPM と CocoaPods を組み合わせた iOS プロジェクトは作成できません。マイグレーションする前に、すべてのプラグインと Cordova プラグインを確認し、SPM をサポートしていないプラグインが存在する場合は、プラグインをアップデート、置き換え、またはプラグインを先にマイグレーションする必要があります。シンプルな Swift プラグインは、Ionic の

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

__CAPGO_KEEP_0__ capacitor-plugin-converter__CAPGO_KEEP_1__

バックアップするものを優先して

iOS プロジェクトに触れる前、クリーンな Git ブランチから始めて、現在の状態をコミットしてください。次に、依存しているネイティブファイルをリストアップしてください。

共通のファイルを保存する ios/App/ include:

• App/Info.plist
• App/AppDelegate.swift
• App/SceneDelegate.swiftFirebase を使用している場合
• App/Assets.xcassets/
• App/Base.lproj/
• App/App.entitlements
• App/GoogleService-Info.plistカスタム
• ファイル .xcconfig 署名設定、バンドル識別子、チーム ID、プロビジョニング プロファイル設定
• 標準の __CAPGO_KEEP_1__ テンプレート外で追加したネイティブの Swift、Objective-C、フレームワーク、拡張子、または __CAPGO_KEEP_0__ ファイルも保存してください。

Also preserve any native Swift, Objective-C, framework, extension, or SDK files you added outside the standard Capacitor template.

Option 1: Use the Capacitor migration assistant

__CAPGO_KEEP_0__

Run the assistant from the root of your Capacitor project:

bunx cap spm-migration-assistant

アシスタントはCocoaPodsのインフラを削除し、ローカルパッケージを作成し、インストールされているプラグインからパッケージ参照を生成し、生成されたSPM構成ファイルを作成します。 CapApp-SPM アシスタントが完了したら、プロジェクトを開いてください:

次に、アシスタントによって印刷されたマニュアルのXcodeステップに従ってください。ほとんどのプロジェクトでは、次の手順になります:

bunx cap open ios

Add

1. をローカルパッケージ依存関係として追加します。 CapApp-SPM をアプリの構成に追加します。
2. プラグインがSPMに変換できなかったものについての警告を解決します。 debug.xcconfig CIを更新する前に、アプリをXcodeからビルドしてください。
3. Xcodeプロジェクトがビルドされた後、再度Syncしてください:
4. __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

bunx cap sync ios

オプション 2: iOS プロジェクトを SPM で再構築する

このパスを使用する場合、 ios/ ディレクトリがデフォルトの Capacitor テンプレートに近い場合、安全にカスタム ファイルを復元できる場合

最初に、バックアップ セクションにリストされているファイルがコミットまたは安全な場所にコピーされていることを確認します。次に、SPM で iOS プロジェクトを削除して再作成します:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

ネイティブ ファイルを復元する必要がある場合は、プロジェクトを開いてください:

bunx cap open ios

このパスは、インプレース マイグレーションよりもクリーンな方法です。 Capacitor 8 の新しい iOS テンプレートを提供します。ただし、署名、エンタイトルメント、Firebase ファイル、ネイティブ ソース変更、カスタム Xcode 設定を慎重に再適用する必要があります。

新しい Capacitor アプリ

新しいアプリの場合、 Capacitor 8 は iOS に SPM を使用することがデフォルトです:

bunx cap add ios

明示的に指定する必要がある場合は、パッケージ マネージャー オプションを渡すことができます:

bunx cap add ios --packagemanager SPM

マイグレーション後、CI を更新する

アプリがローカルでビルドされるまで、CocoaPods を想定しないように CI/CD を更新します。

CocoaPods を使用するステップを削除する

pod install

また、以下のキャッシュを削除してください:

• ios/App/Pods
• ios/App/Podfile.lock
• CocoaPods specs リポジトリ、作業フローがこのアプリのみにキャッシュした場合

通常のウェブビルドと Capacitor の同期手順を維持してください。 iOS ジョブは、JavaScript の依存関係をインストールし、ウェブアセットをビルドし、 Capacitor を同期し、最後に Xcode でビルドすることが予想されます:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

移行チェックリスト

移行前に:

• 新しい Git ブランチを作成してください。
• 現在の作業アプリをコミットしてください。
• すべてのインストールされたプラグインが SPM をサポートしていることを確認してください。
• カスタム iOS ファイルと署名設定を記録してください。
• 移行前にアプリがビルドされることを確認してください。

移行中に:

• 実行 bunx cap spm-migration-assistant または再構築 ios/.
• 追加 CapApp-SPM Xcodeに必要な場合に
• 追加 debug.xcconfig Xcodeに必要な場合に
• アプリ固有のネイティブファイルを復元する
• 実行 bunx cap sync ios.

移行後:

• Xcodeでアプリをビルドおよび実行する
• CocoaPodsの残りファイルを削除する
• CIから削除 pod install CIから削除する
• リリース署名がまだ機能することを確認してください。
• 少なくとも 1 つのシミュレーターと 1 つの実機でアプリを実行してください。

トラブルシューティング

コンテキスト: サポート / プレミアムサポートページまたはフッターのサポートセクション。役割: セクションまたはページヘッダー。見つける場所: page support-policy.astro。メッセージキー `support_policy_troubleshooting_title` (サポートポリシー トラブルシューティング タイトル)。 bunx cap sync ios Xcode がパッケージを解決できない場合、Xcode からパッケージキャッシュをリセットし、再度実行してください。

プラグインの問題でマイグレーションが失敗した場合、プラグインが SPM 対応の新しいリリースを公開しているかどうかを確認してください。管理しているプラグインの場合、まずプラグインパッケージをマイグレートし、次にアプリのマイグレーションに戻ってください。

アプリがローカルでビルドされるが CI が失敗する場合、古い CocoaPods の仮定を確認してください。一般的な原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。 .xcworkspace まとめ pod install Capgo アプリを Swift Package Manager にマイグレートすることは、ほとんど iOS の依存関係を置き換えることです。 Pods/ __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

Capacitor CapApp-SPM 依存関係の参照を引き継ぎます。 debug.xcconfig 生成されたCocoaPodsビルド構成を置き換え、CIはもう必要ありません。 pod install.

カスタマイズされたiOSプロジェクトの場合、最初は bunx cap spm-migration-assistant. ほぼデフォルトのテンプレートに近いプロジェクトの場合、クリーンなSPMリビルドはよく、推論するのに簡単です。

リソース

• Capacitor Swift Package Managerドキュメント
• Capacitor 8のアップデートガイド
• CocoaPods trunk read-only plan
• capacitor-plugin-converter

「Swift Package ManagerへのCapacitorアプリの移行方法」から続けてください。

Capacitorアプリを使用している場合 「Swift Package ManagerへのCapacitorアプリの移行方法」 マイグレーションとエンタープライズオペレーションの計画に、 Capgo エンタープライズ for the product workflow in Capgo Enterprise, 製品ワークフロー用の __CAPGO_KEEP_0__ エンタープライズ Capgo Alternatives for the product workflow in Capgo Alternatives, Capgo 代替 for the product workflow in Capgo Consulting, and Capgo Premium Support Capgo 代替