How to Migrate Your Capacitor App to Swift Package Manager

Swift Package ManagerはCapacitoriOSプロジェクトの標準的な方向です。アプリがまだCocoaPodsを使用している場合、JavaScriptcode、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.

アプリ内の変更点

CocoaPodsベースのCapacitorアプリは、以下のようなファイルに依存しています:

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

SPMベースのCapacitorアプリでは、iOS依存性のワイヤリングをSwift Package Managerに移行します。移行時、Capacitorはローカルパッケージを生成し、その名前でCapacitorとインストール済みネイティブ依存性を接続します。 CapApp-SPM ウェブビルドは同じように動作します。ウェブビルドを実行し、Capacitorを同期し、Xcodeを開き、アプリをアーカイブします。主な違いは、CocoaPodsがiOS依存性グラフを管理することからなくなったことです。

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.

クリーンなブランチから始め、現在のアプリがビルドされることを確認してください。依存性マネージャーを変更する前に、依存性マネージャーを変更することによる影響を理解する必要があります。

次に、__CAPGO_KEEP_0__の下にあるアプリがカスタマイズした内容を確認します。

git status
npm run build
npx cap sync ios

保管する必要がある共通のファイルと設定には

移行アシスタントは__CAPGO_KEEP_0__の下に生成されたiOSプロジェクトファイルを変更します。ロールバックポイントをクリーンに保つことは重要です。 ios/App/移行アシスタントは__CAPGO_KEEP_0__の下に生成されたiOSプロジェクトファイルを変更します。ロールバックポイントをクリーンに保つことは重要です。

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift、もし存在する場合
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist、もしFirebaseを使用している場合
カスタム .xcconfig ファイル
署名設定、バンドルID、チーム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プロジェクトを開いてください:

After it finishes, open the iOS project:

npx cap open ios

ターミナルを閉じる前にアシスタントの出力を読みましょう。アシスタントが手動のXcodeステップを完了するように求めている場合は、それを実行してから再度同期してください。

Xcodeステップを完了してください。

Xcodeでアプリのプロジェクトとターゲットの設定を確認してください:

確認 CapApp-SPM Capacitorがローカルパッケージ依存関係として追加されていることを確認してください。
アプリターゲットが生成されたパッケージ製品をリンクしていることを確認してください。
アシスタントがそれを要求する場合は、プロジェクト設定に生成された debug.xcconfig Xcodeでパッケージ警告を解決してください。
アプリをXcodeから一度ビルドしてください。
Xcodeがパッケージを解決できない場合は、

ファイル > パッケージ > パッケージキャッシュをリセット File > Packages > Reset Package Caches次に、パッケージを再度解決します。

Sync と Build を再度実行します。

Xcode が設定されたら、ターミナルに戻り、Capacitor を sync してください:

npx cap sync ios

次に、Xcode から再度ビルドしてください。migration を完了したと判断するには、clean build が Xcode から正常に動作するまで待ちます。なぜなら、リリース署名、特権、App Extensions、パッケージ解決は Xcode で検証されるからです。

アプリがプッシュ通知、関連ドメイン、バックグラウンドモード、App Groups、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

次のキャッシュも削除してください:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs リポジトリ
Podfileに基づくCIキャッシュキー

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

npm ci
npm run build
npx cap sync ios

CIがまだビルドしている場合 App.xcworkspaceプロジェクトまたはワークスペースのパスを更新してください。マイグレーション後の存在するパスを維持する必要はありません。

トラブルシューティング

コンテキスト: サポート/プレミアムサポートページまたはフッターのサポートセクション。役割: セクションまたはページヘッダー。見られる場所: サポートポリシーページ。メッセージキー `support_policy_troubleshooting_title` (サポートポリシートラブルシューティングタイトル)。

アシスタントが不互換の依存関係を警告する場合

Xcodeはパッケージを解決できません

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

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

古いCocoaPodsの仮定を探してください: pod install, Pods/ キャッシュ Podfile.lock キャッシュキー、またはビルドコマンドが削除された .xcworkspace.

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

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

移行チェックリスト

移行前に:

バランチを作成
現在のiOSアプリのビルドを確認
作業状態をコミット
カスタムネイティブファイルと署名設定をインベントリ
既にSPM互換のリリースが存在するネイティブ依存関係をアップデート

移行中:

実行 npx cap spm-migration-assistant.
プロジェクトを開く npx cap open ios.
Xcodeに追加 CapApp-SPM Xcodeに追加
Xcodeに追加 debug.xcconfig Xcodeに追加
パッケージ警告を解決する。
Run npx cap sync ios.

移行後:

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

この移行に使用するスキルはCapgoです。

AIエージェントを使用して移行を実行する場合、__CAPGO_KEEP_0__スキルから始めてください。 Capgo Skills Build the app from Xcode.

capacitor-best-practices 変更前にアプリ構造を確認する ios/.
cocoapods-to-spm SPM移行とXcodeの後続ステップを計画する
capacitor-ci-cd CocoaPodsの仮定をビルドパイプラインから削除する
debugging-capacitor そして ios-android-logs 移行後、デバイスのみの問題を調査する

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

まとめ

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-assistant手動のXcodeステップを完了し、再度syncし、CIからCocoaPodsを削除する

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ 再作成する npx cap add ios --packagemanager SPM と