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

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

このガイドでは、変更点、バックアップする必要があるもの、2つの実用的な移行パス（Capacitorの移行アシスタントを使用するか、SPMでiOSプロジェクトを再構築するか）について説明します。

なぜ今すぐ移行するか

CocoaPodsは、読み取り専用のトランクに移行しています。現在の計画では、CocoaPodsのトランクは新しいpodspecを受け付けなくなります。 2026年12月2日新しいリリースと依存関係の更新は、トランクに依存しているため、Switch後はそこに公開されません。

SPMはCapacitorの方向性です。Capacitorは、Capacitor6からCapacitor8まで、CocoaPodsまたはSPMを選択する機能をサポートしています。

CapacitorのSPMプロジェクトで何が変わりますか

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

CapApp-SPMはPodfileを置き換えます

CocoaPodsアプリでは、iOS依存関係は、 ios/App/Podfile, Podfile.lock, Pods/、でワイヤードされています。 .xcworkspace.

In an SPM app, Capacitor creates a local package named CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM SPMアプリでは、__CAPGO_KEEP_0__はローカルパッケージ名として

を生成します。このパッケージは、__CAPGO_KEEP_0がnative iOS プラグイン依存関係を参照する中心的な場所になります。CAPGO_KEEP_1 CAPGO_KEEP_2__は、プラグインを同期するときに更新されるため、手動で編集しないでください。

マイグレーションアシスタントは、自動生成された debug.xcconfigこのファイルは、CocoaPodsが生成したxcconfigファイルを通じて提供していたビルド設定を含んでいます。

移行後、追加する必要がある可能性があります debug.xcconfig Xcode プロジェクト設定に追加するようにアシスタントが指示した場合は、Xcode プロジェクト設定に追加するようにします。

すべてのプラグインはSPMをサポートする必要があります。

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

SPMに対応していないプラグインがあれば、更新するか置き換えるか、プラグインを移行することを検討してください。シンプルなSwiftプラグインは、Ionicのプラグインを簡単に変換できます。 capacitor-plugin-converter、しかし、より複雑なObjective-CとSwiftレイアウトを持つプラグインには、手動作業が必要になる場合があります。

最初にバックアップするもの

Git ブランチをクリーンにし、現在の状態をコミットして iOS プロジェクトに触れる前に、依存しているネイティブファイルをリストする。

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

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, アプリが1つしかない場合
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, Firebaseを使用する場合
カスタム .xcconfig ファイル
署名設定、バンドル識別子、チームID、プロビジョニングプロファイル設定

Capgoの標準Capacitorテンプレート外で追加した任意のネイティブSwift、Objective-C、フレームワーク、拡張、またはSDKファイルも保存します。

オプション 1: Capacitor マイグレーションアシスタントを使用します

iOS プロジェクトがカスタムネイティブ編集を含み、失うことを避きたい場合に使用します。

Capacitor プロジェクトのルートからアシスタントを実行します:

bunx cap spm-migration-assistant

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

アシスタントは、__CAPGO_KEEP_0__ プロジェクトのルートから実行します。

bunx cap open ios

Then follow the manual Xcode steps printed by the assistant. In most projects this means:

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

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

bunx cap sync ios

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

最初に、バックアップセクションにリストされているファイルがコミットまたは安全にコピーされていることを確認してください。次に、iOSプロジェクトをSPMで削除して再作成してください。 ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

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

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

アプリが必要とするネイティブファイルを復元し、プロジェクトを開きます:

bunx cap open ios

This path is often cleaner than an in-place migration because it gives you a fresh Capacitor 8 iOS template. The tradeoff is that you must carefully reapply signing, entitlements, Firebase files, native source changes, and any custom Xcode settings.

新しいCapacitorアプリ

新しいアプリの場合、Capacitor 8はiOSの追加時にSPMをデフォルトで使用します。

bunx cap add ios

必要に応じて、パッケージマネージャーオプションを明示的に指定することもできます。

bunx cap add ios --packagemanager SPM

CIの更新

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

実行するステップを削除する

pod install

また、次のキャッシュを削除することも必要です:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs リポジトリ、キャッシュがこのアプリのみに使用されていた場合

通常のWebビルドとCapacitorの同期ステップを維持してください。iOSジョブは、JavaScript依存関係をインストールし、Webアセットをビルドし、Capacitorを同期し、最後にXcodeでビルドすることが一般的です:

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

マイグレーションチェックリスト

移行前:

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

移行中:

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

移行後:

Xcode でアプリをビルドして実行する。
残った CocoaPods ファイルを削除する。
削除 pod install CI から。
リリース署名がまだ機能することを確認する。
少なくとも 1 つのシミュレータと 1 つの実機でアプリを実行して、配信する前にテストする。

トラブルシューティング

Xcode がパッケージを解決できない場合、Xcode からパッケージキャッシュをリセットして実行する。 bunx cap sync ios 再度。

migrationが失敗した場合、プラグインが原因である場合、SPMサポートを備えた最新のリリースがあるかどうかを確認してください。

プラグインを管理している場合、まずプラグインパッケージを移行し、次にアプリケーション移行に戻ります。 .xcworkspace CIが失敗するが、ローカルでアプリがビルドされる場合、古いCocoaPodsの仮定を確認してください。 pod install 原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。 Pods/ 結論

Swift Package Managerへの__CAPGO_KEEP_0__アプリの移行は、主にiOS依存性のワイヤリングを置き換えることです。

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM CIは依存性の参照を取得し、生成されたCocoaPodsのビルド構成を置き換えます。 debug.xcconfig カスタマイズされたiOSプロジェクトの場合は、最初に pod install.

を実行してください。 bunx cap spm-migration-assistantデフォルトテンプレートに近いプロジェクトの場合、クリーンなSPMリースケルトンは、より簡単に推論できることが多いため、速く簡単に実行できます。

リソース