Swift Package Manager への Capacitor アプリの移行方法

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

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

なぜ今すぐ移行するか

CocoaPodsは、読み取り専用のトランクに移行しています。現在の計画では、CocoaPodsのトランクは 2026年12月2日既存のビルドは機能し続けるはずですが、新しいリリースと依存関係の更新がトランクに依存している場合、それらはトランクに公開されなくなります。

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

CapacitorのSPMプロジェクトで何が変更されるか

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

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

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

SPMアプリ内で、Capacitorはローカルパッケージを生成し、その名前は 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__がiOSプラグインのネイティブ依存関係を参照する中心的な場所となります。__CAPGO_KEEP_1__ __CAPGO_KEEP_2__はプラグインを同期するたびに更新されるため、手動で編集しないでください。

debug.xcconfigはPodsの設定を置き換えます

マイグレーションアシスタントは、生成された debug.xcconfigファイルも作成します。このファイルには、CocoaPodsが生成したxcconfigファイルから提供していたビルド設定が含まれます。

マイグレーション後、開発者はアシスタントが指示したように、Xcodeプロジェクトの設定に debug.xcconfig を追加する必要がある場合があります。

SPMをサポートする必要があります

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

単純なSwiftプラグインは、Ionicの capacitor-plugin-converterを使用して簡単に変換できますが、複雑なObjective-CとSwiftレイアウトを持つプラグインには手動で作業する必要があります。

What to back up first

iOSプロジェクトに触れる前に、clean git branchから始めて現在の状態をコミットし、nativeファイルをリストアップしてください。アプリが依存しているnativeファイルをリストアップしてください。

Common files to preserve from ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, アプリがFirebaseを使用している場合
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, アプリがFirebaseを使用している場合
Custom .xcconfig ファイル
Signing settings、bundle identifier、team ID、provisioning profile settings

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

iOSプロジェクトにカスタムnativeエディットが含まれている場合に使用してください。

Run the assistant from the root of your Capacitor project:

bunx cap spm-migration-assistant

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

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

bunx cap open ios

ローカルパッケージ依存として

アプリケーション設定に追加します。 CapApp-SPM プラグインがSPMに変換できなかったものについての警告を解決します。
CIを更新する前に、Xcodeからアプリケーションをビルドしてください。 debug.xcconfig Xcodeプロジェクトがビルドされた後、再度Syncしてください:
アシスタントはCocoaPodsのインフラを削除し、ローカルパッケージを作成し、インストール済みのプラグインからパッケージ参照を生成し、生成されたSPM構成ファイルを作成します。
アシスタントによって印刷されたマニュアルXcodeステップに従ってください。

ローカルパッケージ依存として

bunx cap sync ios

Option 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をデフォルトで使用します:

For a new app, Capacitor 8 uses SPM by default when adding iOS:

bunx cap add ios

CIの更新

bunx cap add ios --packagemanager SPM

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

SPMでiOSプロジェクトを削除するステップを削除します:

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ファイルと署名設定を記録する。
移行前にアプリがビルドされることを確認する。

移行中:

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

移行後:

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

トラブルシューティング

__CAPGO_KEEP_0__ アプリを Swift Package Manager に移行することは、主に iOS の依存関係のワイヤリングを置き換えることです。 bunx cap sync ios Xcode がパッケージを解決できない場合、Xcode からパッケージのキャッシュをリセットし、再度実行します。

プラグインの更新が必要な場合、プラグインのパッケージを最初に移行し、次にアプリの移行に戻ります。

アプリがローカルでビルドされるが CI が失敗する場合、古い CocoaPods の仮定を確認します。一般的な原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。 .xcworkspace 結論 pod install Xcode がパッケージを解決できない場合、Xcode からパッケージのキャッシュをリセットし、再度実行します。 Pods/ プラグインの更新が必要な場合、プラグインのパッケージを最初に移行し、次にアプリの移行に戻ります。

アプリがローカルでビルドされるが CI が失敗する場合、古い CocoaPods の仮定を確認します。一般的な原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 依存関係の参照を取得し、 debug.xcconfig 生成されたCocoaPodsのビルド構成を置き換え、CIはもう pod install.

カスタマイズされたiOSプロジェクトの場合は、 bunx cap spm-migration-assistant. デフォルトのテンプレートに近いプロジェクトの場合は、SPMの再構築はより速く、推論が容易です。

リソース

Keep going from How to Migrate a Capacitor App to Swift Package Manager

__CAPGO_KEEP_0__ アプリをSwift Package Managerに移行する方法 How to Migrate a Capacitor App to Swift Package Manager 企業移行とエンタープライズオペレーションを計画するには、 Capgo エンタープライズ Capgo エンタープライズの製品ワークフロー向けに Ionic エンタープライズプラグインの代替 Ionic エンタープライズプラグインの代替の製品ワークフロー向けに Capgo 代替 Capgo 代替の製品ワークフロー向けに Capgo コンサルティング Capgo コンサルティングの製品ワークフロー向けに Capgo プレミアムサポート Capgo プレミアムサポートの製品ワークフロー向けに

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