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

Capacitor iOSプロジェクトのデフォルト方向はSwift Package Managerです。アプリがまだ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はローカルパッケージ名を生成し、 CapApp-SPM アプリターゲットとCapacitor、インストール済みネイティブ依存関係を__CAPGO_KEEP_1__で接続します。

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

移行する前に

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

git status
npm run build
npx cap sync ios

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

次に、__CAPGO_KEEP_1__を確認します。一般的なファイルと設定を保存するには、 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、およびプロビジョニングプロファイル
アプリ拡張、ネイティブ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がパッケージを解決できない場合、 ファイル > パッケージ > パッケージキャッシュをリセットを選択し、パッケージを再度解決します。

Xcodeが再び構成されたら、ターミナルに戻り、__CAPGO_KEEP_0__:をSyncし

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

npx cap sync ios

__CAPGO_KEEP_0__

If the app uses push notifications, associated domains, background modes, app groups, Firebase, or any native SDK configuration, run those flows on a simulator or device after the build succeeds.

iOSの再構築: SPMを使用

If your ios/ folder is close to the default Capacitor template, it can be faster to recreate it with SPM instead of migrating in place.

SPMでプロジェクトを再構築する

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

Only use this path after committing or backing up every native file and signing setting you need:

For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

npx cap add ios

Then restore your app-specific native files and settings. This path gives you a clean SPM project, but it is easier to lose custom Xcode changes if you did not inventory them first.

npx cap add ios --packagemanager SPM

SPMプロジェクトの作成

For new __CAPGO_KEEP_0__ apps, __CAPGO_KEEP_1__ 8 creates iOS projects with SPM by default:

SPMを使用する

pod install

You can still be explicit: "Clean up CocoaPods leftovers" and "Remove steps like: "Also remove caches that only existed for CocoaPods: "

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specsリポジトリ
Podfileに基づいてCIキャッシュキーを設定する

Capgoの移行後、基本的なCIフローは、JavaScript依存関係をインストールし、Webアプリケーションをビルドし、Capacitorを同期し、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アプリがビルドされることを確認する。
作業中の状態をコミットする。
既に最新のSPM互換バージョンを搭載しているネイティブ依存性を更新します。

移行中:

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

Update native dependencies that already have newer SPM-compatible releases.__CAPGO_KEEP_0__.

During migration:__CAPGO_KEEP_0__.
Test native capabilities on a simulator or device.
Remove CocoaPods commands from CI.
Remove CocoaPods-only caches.
Verify archive and release signing.

Capgoスキルを、移行に使用します。

__CAPGO_KEEP_0__スキルを使用し、 Capgoスキル instead of a blank prompt. The most useful skills for this work are:

capacitor-best-practices to review the app structure before changing ios/.
cocoapods-to-spm to plan the SPM migration and Xcode follow-up steps.
capacitor-ci-cd to remove CocoaPods assumptions from build pipelines.
debugging-capacitor and ios-android-logs __CAPGO_KEEP_0__のデバイスのみの問題を調査するには、移行後に。

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

まとめ

Swift Package ManagerにCapacitorアプリを移行することは、ほとんどiOS依存性管理の変更です。安全なパスは、clean branchから始めて、 npx cap spm-migration-assistantマニュアルXcodeステップを完了し、再度syncし、CIからCocoaPodsを削除するのは、__CAPGO_KEEP_0__アプリがビルドされるまで待ってから行うことです。

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