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

Capacitor 8は、デフォルトでSwift Package Manager (SPM)を使用して新しいiOSプロジェクトを作成します。まだCocoaPodsを使用している既存のアプリも移行できますが、ネイティブiOSのカスタマイズが多くある場合は、安全な移行方法は依然として依存します。

このガイドでは、変更点、バックアップする必要があるもの、2つの実用的な移行方法: Capacitorの移行アシスタントを使用するか、SPMでiOSプロジェクトを再構築する方法について説明します。

なぜ今すぐ移行するか

CocoaPodsは、現在の計画では、CocoaPodsのトランクが新しいpodspecを受け付けなくなる予定です。 2026年12月2日. 既存のビルドは機能し続けるはずですが、Switch後はTrunkに依存する新しいリリースや依存性の更新は、そこに公開されません。

SPM is also the direction Capacitor is moving. Capacitor has supported choosing CocoaPods or SPM since Capacitor 6, and Capacitor 8 now creates iOS SPM projects as the default template.

What changes in a Capacitor SPM project

Migrating from CocoaPods to SPM replaces the iOS dependency layer. The web app, Android project, and most Capacitor workflow commands stay the same.

CapApp-SPMはPodfileを置き換えます

CocoaPodsアプリでは、iOS依存性は ios/App/Podfile, Podfile.lock, Pods/、で接続されます。生成された .xcworkspace.

In an SPM app, Capacitor creates a local package named CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM が更新されるので、手動で編集しないでください。

debug.xcconfigはPods設定を置き換えます

マイグレーションアシスタントは、生成された debug.xcconfig生成されたファイルには、CocoaPodsが生成されたxcconfigファイルを通じて提供していたビルド設定が含まれます。

マイグレーション後、助言に従って、Xcodeプロジェクト設定に debug.xcconfig を追加する必要があるかもしれません。

SPMをサポートする必要があります。

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

を確認し、Cordovaプラグインも含めて、すべての capacitor-plugin-converterがSPMをサポートしていることを確認してください。

SPMをサポートしていないプラグインがあれば、

をアップデート、置き換え、またはプラグインを先にマイグレーションする必要があります。シンプルなSwiftプラグインは、

を使用して簡単に変換できますが、複雑なObjective-CとSwiftレイアウトを持つプラグインには手動で作業する必要があります。 ios/App/ 何をバックアップするかを判断する

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift、あなたのアプリが1つ
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist、あなたがFirebaseを使用している場合
カスタム .xcconfig ページ/エリア: Capgoのマーケティングウェブサイト。役割: 短いUIラベルまたはナビゲーションアイテム。メッセージキー `custom` (カスタム)
ファイル

Also preserve any native Swift, Objective-C, framework, extension, or SDK files you added outside the standard Capacitor template.

また、標準の__CAPGO_KEEP_1__テンプレート外で追加したネイティブのSwift、Objective-C、フレームワーク、拡張、またはCapacitorファイルを保存することもお勧めします。

オプション 1: __CAPGO_KEEP_0__の移行アシスタントを使用する

Run the assistant from the root of your Capacitor project:

bunx cap spm-migration-assistant

アシスタントを、__CAPGO_KEEP_0__プロジェクトのルートから実行してください: CapApp-SPM アシスタントは、CocoaPodsのインフラを削除し、ローカルパッケージを作成し、インストール済みのプラグインからパッケージ参照を生成し、生成されたSPM構成ファイルを作成します。

完了すると、プロジェクトを開いてください:

bunx cap open ios

Then follow the manual Xcode steps printed by the assistant. In most projects this means:

を追加します。 CapApp-SPM をローカルパッケージ依存関係として追加します。
をアプリ設定に追加します。 debug.xcconfig プラグインがSPMに変換できなかったことについての警告を解決します。
CIを更新する前に、アプリをXcodeからビルドしてください。
Xcodeプロジェクトがビルドされた後、再度Syncしてください:

オプション2：iOSプロジェクトをSPMで再構築する

bunx cap sync ios

このパスを使用する場合は、ディレクトリがデフォルトの__CAPGO_KEEP_0__テンプレートに近く、安全にカスタムファイルを復元できる場合のみです。

最初に、バックアップセクションにリストされているファイルがコミットまたは安全な場所にコピーされていることを確認してください。次に、iOSプロジェクトをSPMで削除して再作成してください。 ios/ Capacitor

First, make sure the files listed in the backup section are committed or copied somewhere safe. Then remove and recreate the iOS project with SPM:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

iOS SPM と CocoaPods の Capgo 移行ガイド

bunx cap open ios

This path is often cleaner than an in-place migration because it gives you a fresh Capacitor 8 iOS template. The tradeoff is that you must carefully reapply signing, entitlements, Firebase files, native source changes, and any custom Xcode settings.

このパスは、ネイティブファイルを復元し、プロジェクトを開くことによって、より綺麗な移行が実現します。ただし、8 の iOS テンプレートを使用することにより、 Capacitor の新しいプロジェクトが作成されます。

新しい Capacitor アプリ

bunx cap add ios

新しいアプリの場合、 __CAPGO_KEEP_0__ 8 は iOS に SPM を使用することをデフォルトで設定します。

bunx cap add ios --packagemanager SPM

必要に応じて、パッケージマネージャーを明示的に指定することもできます。

CI の更新

ローカルでアプリがビルドされたら、CocoaPods を使用しないように CI/CD を更新してください。

pod install

実行するステップを削除してください:

ios/App/Pods
ios/App/Podfile.lock
また、次のキャッシュを削除してください:

Keep your regular web build and Capacitor sync steps. A typical iOS job should install JavaScript dependencies, build the web assets, sync Capacitor, and then build with Xcode:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

通常の Web ビルドと __CAPGO_KEEP_1 の Sync ステップを維持してください。iOS ジョブは、JavaScript の依存関係をインストールし、Web アセットをビルドし、 CAPGO_KEEP_1__ を Sync して、最後に Xcode でビルドすることが一般的です。

移行前の準備:

新しいGitブランチを作成します。
現在の作業アプリをコミットします。
すべてのプラグインがSPMをサポートしていることを確認します。
カスタムiOSファイルと署名設定を記録します。
移行前のアプリがビルドされることを確認します。

移行中:

Run bunx cap spm-migration-assistant または再構築 ios/.
Add CapApp-SPM Xcodeで必要に応じて
Add debug.xcconfig Xcodeで必要な場合。
アプリ固有のネイティブファイルを復元する。
実行 bunx cap sync ios.

移行後:

Xcodeでアプリをビルドして実行する。
CocoaPodsの残りファイルを削除する。
削除 pod install CIから。
リリース署名がまだ機能することを確認する。
少なくとも1台のシミュレータと1台の実機でアプリを実行して、配信する前にテストする。

トラブルシューティング

ページ/エリア: サポート / プレミアムサポートページまたはサポートフッター部。役割: セクションまたはページヘッダー。見られる場所: page support-policy.astro。メッセージキー `support_policy_troubleshooting_title` (サポートポリシートラブルシューティングタイトル)。 bunx cap sync ios 再び。

プラグインの問題で移行が失敗した場合、プラグインがSPMサポートを含む新しいリリースを持っているかどうかを確認してください。管理しているプラグインの場合、まずプラグインパッケージを移行し、次にアプリケーション移行に戻ります。

アプリがローカルでビルドされるがCIが失敗する場合、古いCocoaPodsの仮定を確認してください。一般的な原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。 .xcworkspace 結論 pod install Swift Package Managerにアプリケーションを移行することは、ほとんどがiOS依存性のワイヤリングを置き換えることです。 Pods/ 依存性の参照を取得し、生成されたCocoaPodsのビルド構成を置き換え、CIは依存性の参照を取得し、生成されたCocoaPodsのビルド構成を置き換える必要がなくなります。

カスタマイズされたiOSプロジェクトの場合、最初に

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM __CAPGO_KEEP_0__ debug.xcconfig __CAPGO_KEEP_0__ pod install.

__CAPGO_KEEP_0__ bunx cap spm-migration-assistant__CAPGO_KEEP_0__

リソース

Keep going from How to Migrate a Capacitor App to Swift Package Manager

Capgo を使用している場合 How to Migrate a Capacitor App to Swift Package Manager 移行計画とエンタープライズオペレーションを計画するには、__CAPGO_KEEP_0__ Enterprise と接続します。 Capgo Enterprise for the product workflow in Capgo Enterprise, Capgo エンタープライズの製品ワークフローイオニックエンタープライズプラグイン代替 Capgo 代替 for the product workflow in Capgo Alternatives, Capgo コンサルティング for the product workflow in Capgo Consulting, and Capgo プレミアムサポート for the product workflow in Capgo Premium Support.