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

Capacitor iOSプロジェクトのデフォルト方向はSwift Package Managerです。アプリがまだ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.

アプリ内の変更

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

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

SPMベースのCapacitorアプリは、iOS依存関係をSwift Package Managerに移行します。移行中、Capacitorはローカルパッケージ名を生成し CapApp-SPM アプリターゲットとCapacitor、インストール済みネイティブ依存関係を接続します。

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

依存管理者を変更する前に、以下の手順に従ってください。

クリーンブランチから始め、現在のアプリがビルドされることを確認してください。

git status
npm run build
npx cap sync ios

次に、作業状態をコミットします。移行は生成されたiOSプロジェクトファイルを変更するため、ロールバックポイントがクリーンであることが重要です。

次に、以下のファイルと設定を確認します。 ios/App/、もし存在する場合

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift、もしFirebaseを使用している場合
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistカスタマイズ
ファイル .xcconfig ファイル
署名設定、バンドルID、チームID、およびプロビジョニングプロファイル
アプリ拡張、ネイティブSwiftファイル、Objective-Cファイル、または埋め込まれたフレームワーク

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

移行アシスタントを使用する

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

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ステップを実行するように求めると、Xcodeステップを実行してください。

npx cap open ios

Xcodeステップを完了する

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

確認する

確認する CapApp-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

Sync and build again

アプリがプッシュ通知、関連するドメイン、バックグラウンドモード、アプリグループ、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リポジトリ
Podfileに基づいてCIキャッシュキーを設定

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

npm ci
npm run build
npx cap sync ios

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

トラブルシューティング

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

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

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

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

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

古いCocoaPodsの仮定を探してください: pod install, Pods/ キャッシュ Podfile.lock キャッシュキー .xcworkspace.

ビルドコマンドが削除された

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

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

移行チェックリスト

移行前:
ブランチを作成してください。
現在のiOSアプリがビルドされることを確認してください。
コミット可能な状態をコミットしてください。
__CAPGO_KEEP_0__が既に最新のSPM互換バージョンを使用している場合のネイティブ依存性を更新します。

移行中:

__CAPGO_KEEP_0__ npx cap spm-migration-assistant.
プロジェクトを開く npx cap open ios.
__CAPGO_KEEP_0__が必要な場合にXcodeで CapApp-SPM __CAPGO_KEEP_0__が必要な場合にXcodeで
パッケージ警告を解決します。 debug.xcconfig __CAPGO_KEEP_0__
移行後:
Xcodeからアプリをビルドします。 npx cap sync ios.

__CAPGO_KEEP_0__が必要な場合にXcodeで

__CAPGO_KEEP_0__が必要な場合にXcodeで
__CAPGO_KEEP_0__
シミュレーターまたはデバイスでネイティブ機能をテストします。
CIからCocoaPodsコマンドを削除します。
CocoaPodsのみのキャッシュを削除します。

Use Capgo Skills for the migration

__CAPGO_KEEP_0__スキルを、移行に使用します。 Capgoスキルから始めて、AIエージェントを使用して移行を実行します。 __CAPGO_KEEP_0__スキル

capacitor-best-practices アプリ構造を変更する前にアプリ構造をレビューするスキル ios/.
cocoapods-to-spm SPM移行とXcodeのフォローアップステップを計画するスキル
capacitor-ci-cd ビルドパイプラインからCocoaPodsの仮定を削除するスキル
debugging-capacitor and ios-android-logs デバイスのみの問題を調査するには、移行後に実行する必要があります。

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

まとめ

Capacitor アプリをSwift Package Managerに移行することは、ほとんどiOS依存関係管理の変更です。安全なパスは、clean branchから始めて、 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/ iOSプロジェクトが高度にカスタマイズされている場合、インプレースで移行することをお勧めします。デフォルトの__CAPGO_KEEP_0__テンプレートに近い場合は、 npx cap add ios --packagemanager SPM 再作成することが綺麗です。

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