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

Capacitor iOSプロジェクトのデフォルトの方向はSwift Package Managerです。アプリがまだCocoaPodsを使用している場合、JavaScript code、Androidプロジェクト、リリースワークフローをゼロから再構築することなく、App自体を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アプリは、Swift Package ManagerにiOS依存性のワイヤリングを移動します。移行中、Capacitorはローカルパッケージ名を生成し、 CapApp-SPM を使用してアプリターゲットとCapacitor、インストール済みネイティブ依存性を接続します。

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

移行する前に

__CAPGO_KEEP_0__から始めて、現在のアプリが依存関係管理者を変更する前に、clean branchから始めてビルドされることを確認してください。

git status
npm run build
npx cap sync ios

次に、作業状態をコミットしてください。マイグレーションは生成されたiOSプロジェクトファイルを触るので、clean rollback pointが必要です。

次に、レビューしてください。アプリがカスタマイズしたものは次のとおりです。 ios/App/. 共通ファイルと設定を保存するには、次のとおりです:

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、プロビジョニングプロファイル
アプリ拡張、ネイティブSwiftファイル、Objective-Cファイル、または埋め込まれたフレームワーク

また、インストール済みのCapacitorとCordova依存関係も確認してください。ネイティブ依存関係がSPM互換パスを持たない場合、App-level SPMマイグレーションはブロックされる可能性があります。可能な場合は、更新する前にパッケージを更新してください。

マイグレーションアシスタントを使用してください

Capacitorの公式の移行アシスタントから始めましょう。

npx cap spm-migration-assistant

Capacitorプロジェクトのルートディレクトリから実行してください。アシスタントはCocoaPodsの統合を削除し、ローカルパッケージを作成し、インストール済みネイティブ依存関係のパッケージ参照を生成し、iOSプロジェクトに必要な生成された構成を追加します。 CapApp-SPM アシスタントが終了したら、iOSプロジェクトを開いてください。

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

npx cap open ios

Xcodeのステップを完了

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

確認

ローカルパッケージ依存関係として__CAPGO_KEEP_0__が追加されます。 CapApp-SPM アシスタントがターゲットが生成されたパッケージ製品をリンクしていることを確認してください。
アシスタントが追加する__CAPGO_KEEP_0__をプロジェクト構成に追加するように求められた場合は、追加してください。
確認 debug.xcconfig to the project configuration if the assistant asks for it.
Xcodeでパッケージ警告を解決します。
Xcodeからアプリを一度ビルドします。

Xcodeがパッケージを解決できない場合、 ファイル > パッケージ > パッケージキャッシュをリセット、パッケージを再度解決してください。

Syncとビルドをもう一度

Xcodeが設定された後、ターミナルに戻り、Capacitor:をSyncし

npx cap sync ios

次に、Xcodeからビルドを実行してください。migrationが完了したと判断するには、Xcodeからクリーンビルドが正常に動作するまで待ちます。リリース署名、特権、拡張機能、アプリケーションパッケージ解決はすべてXcodeで検証されます。

アプリがプッシュ通知、関連ドメイン、バックグラウンドモード、アプリグループ、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のスペックリポジトリ
Podfileに基づくCIキャッシュキー

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

npm ci
npm run build
npx cap sync ios

CIがまだビルドしている場合 App.xcworkspace, またはプロジェクトまたはワークスペースのパスを、移行後のものに更新します。古いジョブが使用していた古い CocoaPods のパスを維持するのではなく。

トラブルシューティング

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

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

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

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

再度実行してください。

アプリはローカルでビルドできるが、CI で失敗します pod install, Pods/ 古い CocoaPods の仮定を探してください: Podfile.lock キャッシュ、 .xcworkspace.

__CAPGO_KEEP_0__が変更された

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

移行チェックリスト

移行前:

ブランチを作成します。
現在のiOSアプリがビルドされることを確認します。
ワーキングステートをコミットします。
カスタムネイティブファイルと署名設定をインベントリします。
既に新しいSPM互換リリースを持つネイティブ依存関係を更新します。

移行中:

Run npx cap spm-migration-assistant.
プロジェクトを開きます npx cap open ios.
Add CapApp-SPM Xcodeに必要な場合に追加してください。
Add debug.xcconfig Xcodeに必要な場合に追加してください。
パッケージ警告を解決する。
Run npx cap sync ios.

移行後：

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

Capgoスキルを、移行用に使用してください。

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

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

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

結論

Swift Package Managerに移行するCapacitorアプリは、主にiOS依存性管理の変更です。最も安全なパスは、クリーンブランチから始めて、 npx cap spm-migration-assistant手動でXcodeの手順を完了し、再度Syncし、CIのみでCocoaPodsを削除する。

iOSプロジェクトが高度にカスタマイズされている場合は、インプレースで移行する。デフォルトのCapacitorテンプレートに近い場合は、再作成 ios/ が綺麗である。 npx cap add ios --packagemanager SPM リソース