SwiftパッケージマネージャーへのCapacitorアプリの移行方法

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

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

なぜ今すぐ移行するか

CocoaPodsは、読み取り専用のトランクに移行しています。現在の計画では、2026年12月2日以降、CocoaPodsのトランクは新しいpodspecを受け付けなくなります。 2026年12月2日. Existing builds should keep working, but new releases and dependency updates that rely on trunk will not be published there after the switch.

SPMはまた、Capacitorが向かっている方向です。CapacitorはCapacitor 6から、Capacitor 8からCocoaPodsまたはSPMを選択する機能をサポートしており、Capacitor 8ではiOS SPMプロジェクトを作成するデフォルトテンプレートとしています。

SPMプロジェクトのCapacitorの変更点は何ですか

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 を生成します。このパッケージは、__CAPGO_KEEP_0__がnative iOSプラグイン依存関係を参照する中心的な場所になります。__CAPGO_KEEP_1__ __CAPGO_KEEP_2__は

を更新しますので、プラグインを同期するときに更新されるので、手動で編集しないでください。

debug.xcconfigはPods設定を置き換えます debug.xcconfig. このファイルには、CocoaPodsが生成した xcconfig ファイルを通じて提供していたビルド設定が含まれます。

マイグレーション後、助手が変更を求める場合、Xcode プロジェクトの構成に追加する必要がある場合があります。 debug.xcconfig SPM をサポートする必要があります。

CocoaPods と SPM を同じ __CAPGO_KEEP_0 iOS プロジェクトで組み合わせることはできません。マイグレーションする前に、すべての CAPGO_KEEP_1__ と Cordova プラグインを確認してください。

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

が使用して簡単に変換できることが多いですが、複雑な Objective-C と Swift のレイアウトを持つプラグインには手動で作業する必要がある場合があります。 capacitor-plugin-converter最初にバックアップするもの

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

保存する共通ファイル

include: ios/App/ 、アプリが 1 つあれば

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftinclude:、
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 完了すると、プロジェクトを開いてください:

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

bunx cap open ios

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

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

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

bunx cap sync ios

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

まず、バックアップセクションにリストされているファイルがコミットまたは安全な場所にコピーされていることを確認してください。次に、SPMでiOSプロジェクトを削除して再作成してください。 ios/ Capacitorディレクトリが近いデフォルトのテンプレートの場合、安全にカスタムファイルを復元できる場合は、このパスを使用してください。

カスタムファイルを復元することができる場合は、このパスを使用してください。

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はデフォルトで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のSyncステップを維持してください。iOSジョブは、JavaScriptの依存関係をインストールし、Webアセットをビルドし、CapacitorをSyncし、最後にXcodeでビルドすることができます。

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

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

マイグレーション前:

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

移行中:

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

移行後:

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

トラブルシューティング

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

プラグインの更新が必要な場合は、SPM対応の最新バージョンを確認してください。管理しているプラグインの場合、まずプラグインパッケージを移行し、次にアプリケーション移行に戻ります。

ローカルでアプリがビルドされるがCIが失敗する場合、古いCocoaPodsの仮定を確認してください。一般的な原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。 .xcworkspace まとめ pod install Swift Package Managerへのアプリの移行は、iOS依存性のワイヤリングを置き換えることにほぼ関係しています。SPMが依存性の参照を取り扱い、生成されたCocoaPodsのビルド構成を置き換え、CIは依存性の参照を取り扱う必要がなくなります。 Pods/ CIが必要なくなります。

カスタマイズされたiOSプロジェクトの場合は、

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM リソース debug.xcconfig __CAPGO_KEEP_0__ pod install.

__CAPGO_KEEP_0__ bunx cap spm-migration-assistant__CAPGO_KEEP_0__

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