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

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

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

なぜ今すぐ移行するか

CocoaPodsは、読み取り専用のトランクに移行しています。現在の計画では、CocoaPodsトランクは2026年12月2日に新しいpodspecを受け付けなくなります。 既存のビルドは正常に動作するはずですが、新しいリリースや依存関係の更新がトランクに依存している場合、トランクに公開されなくなります。SPMは、__CAPGO_KEEP_0__も同様に進んでいます。__CAPGO_KEEP_1__は、__CAPGO_KEEP_2__ 6からCocoaPodsまたはSPMを選択する機能をサポートしてきました。__CAPGO_KEEP_3__ 8では、iOS SPMプロジェクトを作成するデフォルトのテンプレートとして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.

What changes in a Capacitor SPM project

Migrating from CocoaPods to SPMを実行すると、iOS依存関係層が置き換えられます。ウェブアプリ、Androidプロジェクト、および大部分のCapacitorワークフローコマンドは同じままです。

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

CocoaPodsアプリでは、iOS依存関係は、 ios/App/Podfile, Podfile.lock, Pods/、および生成された .xcworkspace.

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

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

も生成します。このファイルには、CocoaPodsが生成したxcconfigファイルを通じて提供していたビルド設定が含まれます。 debug.xcconfigマイグレーション後、必要に応じて、

をXcodeプロジェクト構成に追加する必要があるかもしれません。アシスタントがそう指示した場合 debug.xcconfig to the Xcode project configuration if the assistant tells you to do so.

すべてのプラグインは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レイアウトを持つプラグインには、手動作業が必要になる場合があります。

何をバックアップするか

clean git branchから始め、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、およびプロビジョニングプロファイル設定

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

オプション 1: Capacitorの移行アシスタントを使用します。

iOSプロジェクトがカスタムネイティブ編集を持つ場合に使用するパスです。

Capacitorプロジェクトのルートディレクトリからアシスタントを実行してください。

bunx cap spm-migration-assistant

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

次に、手動でアシスタントによって印刷されたXcodeステップに従ってください。ほとんどのプロジェクトでは次のことを行います。

bunx cap open ios

ローカルパッケージ依存としてを追加します。

生成された CapApp-SPM を追加します。
を追加します。 debug.xcconfig アプリ設定に追加します。
プラグインが SPM に変換できない可能性のある警告を解決します。
CI を更新する前に、Xcode からアプリをビルドしてください。

Xcode プロジェクトがビルドされた後、再度 Sync してください:

bunx cap sync ios

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

このパスを使用する場合、ディレクトリがデフォルトの __CAPGO_KEEP_0__ テンプレートに近く、安全にカスタムファイルを復元できる場合です。 ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

ネイティブファイルを復元して、アプリが必要なものを追加してください。プロジェクトを開いてください。

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

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

bunx cap open ios

新しい Capacitor アプリ

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

Capacitor 8 は iOS を追加するときに SPM をデフォルトで使用します。

bunx cap add ios

__CAPGO_KEEP_0__を明示的に指定する場合は、パッケージマネージャーオプションを引き続き指定できます:

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に必要な場合にXcodeに追加します。
追加 debug.xcconfig Xcodeに必要な場合にXcodeに追加します。
アプリ固有のネイティブファイルを復元します。
Run bunx cap sync ios.

移行後：

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

トラブルシューティング

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

プラグインの更新が原因でマイグレーションが失敗した場合、プラグインがSPMサポートを含む最新のリリースを持っているかどうかを確認します。

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

まとめ

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

デフォルトのテンプレートに近いプロジェクトの場合は、クリーンなSPMリースケルトンがよく、推論することが簡単です。 bunx cap spm-migration-assistantリソース

Capgo Swift Package Managerドキュメント