How to Migrate Your Capacitor App to Swift Package Manager

Swift Package Managerは、Capacitor iOSプロジェクトのデフォルトの方向です。アプリがまだCocoaPodsを使用している場合、JavaScript code、Androidプロジェクト、またはリリースワークフローをゼロから構築することなく、アプリ自体をSPMに移行できます。

This guide is for app teams. It explains how to migrate a Capacitor iOS app from CocoaPods to SPM, what the migration assistant changes, what you still need to check in Xcode, and how to clean up CI after the app builds.

アプリ内での変更

CapacitorアプリをSPMに移行する方法 A CocoaPods-based Capacitor app depends on files such as:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, Capacitor creates a local package named CapApp-SPM and uses it to connect the app target with Capacitor and installed native dependencies.

The web build still works the same way. You still run a web build, sync Capacitor, open Xcode, and archive the app. The main difference is that CocoaPods no longer owns the iOS dependency graph.

Capacitorがローカルパッケージを作成し、

を使用してアプリターゲットとCapacitorを接続し、インストール済みネイティブ依存関係を使用します。

git status
npm run build
npx cap sync ios

Webビルドは同じように動作します。Webビルドを実行し、CapacitorをSyncし、Xcodeを開き、アプリをアーカイブします。主な違いは、CocoaPodsがiOS依存グラフを管理しないことです。

移行する前に ios/App/クリーンなブランチから始め、現在のアプリがビルドされることを確認してください。依存関係マネージャーを変更する前に依存関係を変更しません。

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift次に、コミットします。生成されたiOSプロジェクトファイルに影響を与えるため、ロールバックポイントをクリーンに保つことが重要です。
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist次に、を確認します。
保管する一般的なファイルと設定を含みます。 .xcconfig 、もし存在する場合
署名設定、バンドル識別子、チームID、およびプロビジョニングプロファイル
アプリ拡張、ネイティブSwiftファイル、Objective-Cファイル、または埋め込まれたフレームワーク

また、インストールされているCapacitorとCordova依存関係も確認してください。アプリレベルSPM移行は、SPM互換パスがないネイティブ依存関係によってブロックされる可能性があります。可能な場合は、更新する前にパッケージを更新してください。

migrationアシスタントを使用する

ほとんどの既存のアプリでは、公式のCapacitormigrationアシスタントから始めてください:

npx cap spm-migration-assistant

Run it from the root of your Capacitor project. The assistant removes CocoaPods integration, creates the local CapApp-SPM アシスタントが終了したら、iOSプロジェクトを開きます:

アシスタントの出力は終了する前にターミナルを閉じないでください。アシスタントが手動でXcodeのステップを実行するように求める場合は、そのステップを実行して再度Syncする前に実行してください。

npx cap open ios

Xcodeのステップを完了する

Xcodeでアプリプロジェクトとターゲットの構成を確認します:

確認する

確認する CapApp-SPM CapacitorアプリをSPMに移行する方法
生成されたパッケージ製品がアプリのターゲットにリンクされていることを確認します。
生成された debug.xcconfig プロジェクト設定に生成された
Xcodeでパッケージ警告を解決します。
Xcodeからアプリを一度ビルドします。

Xcodeがパッケージを解決できない場合は、 File > Packages > Reset Package Cachesを実行し、パッケージを再度解決してください。

Xcodeが設定されると、ターミナルに戻り、__CAPGO_KEEP_0__をSyncしてください。

After Xcode is configured, return to the terminal and sync Capacitor:

npx cap sync ios

Then build from Xcode again. Do not treat the migration as done until a clean build works from Xcode, because release signing, entitlements, app extensions, and package resolution are validated there.

アプリがプッシュ通知、関連ドメイン、バックグラウンドモード、アプリグループ、Firebase、または任意のネイティブ SDK 設定を使用している場合、ビルドが成功した後は、シミュレーターまたはデバイス上でそれらのフローを実行してください。

代替: iOS を SPM で再作成

あなたの ios/ フォルダがデフォルト Capacitor テンプレートに近い場合は、代わりにインプレースで移行するのではなく、SPM で再作成する方が速い可能性があります。

コミットまたはバックアップしたあとに、必要なネイティブファイルと署名設定のみを使用して、このパスを実行してください:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

次に、アプリ固有のネイティブファイルと設定を復元してください。このパスは、SPM プロジェクトをクリーンにしますが、カスタム Xcode 変更を失う可能性が高いため、最初にその変更をインベントリに記録することをお勧めします。

新しい Capacitor アプリの場合、Capacitor 8 は iOS プロジェクトを SPM で作成します:

npx cap add ios

明示的に指定することもできます:

npx cap add ios --packagemanager SPM

CocoaPods の残骸をクリーンアップ

SPM アプリがビルドされた後、ローカルスクリプトと CI から CocoaPods の仮定を削除してください。

次のステップを削除してください:

pod install

また、CocoaPods のみに存在していたキャッシュも削除してください:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs repositories
CI cache keys based on the Podfile

migration後の基本的なCIフローは、JavaScriptの依存関係をインストールし、Webアプリをビルドし、CapacitorをSyncし、Xcodeでビルドすることです。

npm ci
npm run build
npx cap sync ios

CIがまだビルドしている場合 App.xcworkspaceCIをプロジェクトまたはワークスペースのパスに更新してください。マイグレーション後も存在する古いCocoaPodsのパスを残すのを避けましょう。

トラブルシューティング

アシスタントは不互換の依存関係を警告します

依存関係をアップデートし、アシスタントを再実行してください。SPM互換のバージョンが存在しない場合は、依存関係を置き換えるか、メンテナーがSPMサポートを追加するまで、CocoaPodsでアプリを維持してください。

Xcodeがパッケージを解決できない場合

Xcodeのパッケージキャッシュをリセットし、 CapApp-SPM がローカルパッケージとして存在することを確認し、 npx cap sync ios を再実行してください。

ローカルではアプリがビルドされるがCIは失敗する

古いCocoaPodsの仮定を探す pod install, Pods/ キャッシュ Podfile.lock キャッシュキー、または削除されたビルドコマンドへの参照 .xcworkspace.

署名または特権が変更された

移行したXcodeターゲットを、移行前のプロジェクトと比較する。バンドルID、チーム、プロビジョニングプロファイル、特権ファイル、機能、拡張設定を復元する。

移行チェックリスト

移行する前に

ブランチを作成する
現在のiOSアプリがビルドされることを確認する
作業中の状態をコミットする
カスタムネイティブファイルと署名設定をインベントリする
CapacitorアプリをSPMに移行する方法

移行中:

Run npx cap spm-migration-assistant.
Xcodeでプロジェクトを開く npx cap open ios.
Xcodeで必要に応じて CapApp-SPM Xcodeで必要に応じて
パッケージ警告を解決する debug.xcconfig Run
移行後:
Xcodeでアプリをビルドする npx cap sync ios.

targetLanguage

pagePath
シミュレーターまたはデバイスでネイティブ機能をテストする。
CIからCocoaPodsコマンドを削除する。
CocoaPodsのみのキャッシュを削除する。
アーカイブとリリース署名を検証する。

Capgoスキルを使用して移行を行う。

AIエージェントを使用して移行を管理する場合、__CAPGO_KEEP_0__スキルから始めてください。空のプロンプトではなく、Capgoスキルから始めてください。この作業に最も役立つスキルは次のとおりです。

capacitor-best-practices アプリ構造を変更する前にアプリ構造をレビューする。 ios/.
cocoapods-to-spm SPM移行とXcodeのフォローアップステップを計画する。
capacitor-ci-cd ビルドパイプラインからCocoaPodsの仮定を削除する。
debugging-capacitor そして ios-android-logs Migrate __CAPGO_KEEP_0__ app to Swift Package Manager

migration の後、デバイスのみの問題を調査するために使用します。

iOS プロジェクトを変更する前に、エージェントがネイティブファイル、CI、依存性の互換性をチェックするように使用してください。migration コマンドを実行するのではなく。

Migrating a Capacitor app to Swift Package Manager is mostly an iOS dependency-management change. The safest path is to start from a clean branch, run npx cap spm-migration-assistantSwift Package Manager への __CAPGO_KEEP_0__ アプリの移行は、主に iOS の依存関係管理の変更です。安全なパスは、clean branch から始めて、run

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ iOS プロジェクトが高度にカスタマイズされている場合は、インプレースで移行することをお勧めします。デフォルトの __CAPGO_KEEP_0__ テンプレートに近い場合は、再作成 npx cap add ios --packagemanager SPM with