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

Capacitor 8 は、Swift Package Manager (SPM) を使用してデフォルトで新しい iOS プロジェクトを作成します。まだ CocoaPods を使用している既存のアプリは、もちろん移行することもできますが、ネイティブ iOS カスタマイズの度合いによっては、最も安全なパスは異なります。

This guide explains what changes, what to back up, and the two practical migration paths: using the Capacitor migration assistant or re-scaffolding the iOS project with SPM.

Why migrate now

CocoaPods は、読み取り専用のトランクに移行しています。現在の計画では、CocoaPods トランクは 2026 年 12 月 2 日以降、新しい podspecs を受け付けなくなります。既存のビルドは正常に動作するはずですが、トランクを切り替えた後、新しいリリースや依存関係の更新がトランクに依存している場合、そこから公開されなくなります。SPM は、__CAPGO_KEEP_0__ もその方向に進んでいます。__CAPGO_KEEP_1__ は、__CAPGO_KEEP_2__ 6 以来、CocoaPods または SPM を選択する機能をサポートしており、__CAPGO_KEEP_3__ 8 は iOS SPM プロジェクトを作成するデフォルトのテンプレートとしています。

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.

CocoaPods から SPM に移行すると、iOS の依存関係層が置き換えられます。ウェブアプリ、Android プロジェクト、およびほとんどの Capacitor ワークフローコマンドは同じままです。

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

CocoaPods アプリでは、iOS の依存関係は "、"、および " によって接続されます。

生成された ios/App/Podfile, Podfile.lock, Pods/__CAPGO_KEEP_1__ 8 は、Swift Package Manager (SPM) を使用してデフォルトで新しい iOS プロジェクトを作成します。既存のアプリがまだ CocoaPods を使用している場合、もちろん移行することもできますが、ネイティブ iOS カスタマイズの度合いによっては、最も安全なパスは異なります。 .xcworkspace.

SPMアプリ内で、Capacitorはローカルパッケージを生成し、その名前は CapApp-SPM. このパッケージは、CapacitorがiOSネイティブプラグイン依存関係を参照する中心となる場所になります。 Capacitor CLIはプラグインを同期するたびに CapApp-SPM を更新します。したがって、手動で編集しないでください。

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

migrationアシスタントは生成された debug.xcconfigファイルも作成します。このファイルには、CocoaPodsが生成したxcconfigファイルから提供していたビルド設定が含まれます。

migration後、migrationアシスタントが指示したように、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.

SPMをサポートしていないプラグインがあれば、プラグインを更新する、またはプラグインを置き換える、またはプラグインを先にmigrationする必要があります。 capacitor-plugin-converter簡単なSwiftプラグインは、Ionicの

最初にバックアップするもの

iOS プロジェクトに触る前に、クリーンな Git ブランチから現在の状態をコミットしてください。次に、アプリが依存するネイティブファイルをリストアップしてください。

保存する共通ファイル ios/App/ include: __CAPGO_KEEP_0__

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 ファイル
署名設定、バンドル識別子、チーム ID、プロビジョニングプロファイル設定

標準の Capacitor テンプレート外で追加したネイティブの Swift、Objective-C、フレームワーク、拡張子、または SDK ファイルもすべて保存してください。

オプション 1: Capacitor マイグレーションアシスタントを使用する

iOS プロジェクトがカスタムのネイティブ編集を含んでおり、失うことを避きたい場合に使用してください。

Run the assistant from the root of your Capacitor project:

bunx cap spm-migration-assistant

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

次に、アシスタントによって印刷されたマニュアルXcodeステップに従ってください。ほとんどのプロジェクトでは、これは次のことを意味します:

bunx cap open ios

ローカルパッケージ依存として

アプリの構成に追加します。 CapApp-SPM プラグインがSPMに変換できなかったことによる警告を解決します。
CIを更新する前に、Xcodeからアプリをビルドしてください。 debug.xcconfig Xcodeプロジェクトがビルドされた後、再度Syncしてください。
Add
generated

package

bunx cap sync ios

Option 2: iOSプロジェクトをSPMで再構築する

このパスを使用する場合、__CAPGO_KEEP_0__のデフォルトテンプレートと近いディレクトリにある場合、安全にカスタムファイルを復元できる場合 ios/ Capacitorのデフォルトテンプレートと近いディレクトリにある場合、安全にカスタムファイルを復元できる場合

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

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

必要なネイティブファイルを復元し、プロジェクトを開く

bunx cap open ios

このパスは、Capacitorの8つのiOSテンプレートを提供するため、インプレースマイグレーションよりも綺麗な場合があります。ただし、署名、エンタイトルメント、Firebaseファイル、ネイティブソース変更、カスタムXcode設定などを慎重に再適用する必要があります。

新しいCapacitorアプリ

Capacitor 8では、iOSを追加するときにデフォルトでSPMを使用します。

bunx cap add ios

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

bunx cap add ios --packagemanager SPM

CIをアップデート

アプリがローカルでビルドされるまでに、CocoaPodsを想定していないようにCI/CDをアップデートする

CocoaPodsを使用するステップを削除する

pod install

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

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs リポジトリ、開発プロセスでこのアプリにのみキャッシュした場合

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

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

移行チェックリスト

移行前の作業:

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

移行中:

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

移行後:

Xcode でアプリをビルドおよび実行
残った CocoaPods ファイルを削除
削除 pod install CI から削除
リリース署名の検証が正常に動作することを確認します。
アプリを少なくとも 1 つのシミュレーターと 1 つの実機デバイスで実行して、配信する前にテストしてください。

トラブルシューティング

__CAPGO_KEEP_0__ アプリを Swift Package Manager に移行することは、ほとんど iOS の依存関係のワイヤリングを置き換えることです。 bunx cap sync ios Xcode がパッケージを解決できない場合、Xcode からパッケージキャッシュをリセットし、再度実行してください。

プラグインの更新が必要な場合、プラグインが SPM のサポートを備えた最新のリリースを確認し、プラグインを維持している場合はプラグインパッケージを先に移行し、再びアプリの移行に戻ってください。

アプリがローカルでビルドされるが CI が失敗する場合、古い CocoaPods の仮定を確認してください。一般的な原因は、強制されたビルドパス、古いコマンド、または前のビルドからキャッシュされたものです。 .xcworkspace 結論 pod install If Xcode cannot resolve packages, reset package caches from Xcode and run again. Pods/ If the migration fails because of a plugin, check whether the plugin has a newer release with SPM support. For plugins you maintain, migrate the plugin package first and then return to the app migration.

When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced build path, a stale command, or caching from previous builds.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 依存関係の参照を取得し、 debug.xcconfig 生成されたCocoaPodsビルド構成を置き換え、CIはもう必要ない pod install.

カスタマイズされたiOSプロジェクトの場合、 bunx cap spm-migration-assistant. デフォルトのテンプレートに近いプロジェクトの場合、クリーンなSPMリースケルトンは、より簡単に推論できることが多い

リソース

How to Migrate a Capacitor App to Swift Package Managerから続けてください

Capgoを使用している場合 How to Migrate a Capacitor App to Swift Package Manager ビジネス移行とエンタープライズオペレーションを計画するには、 Capgo エンタープライズ Capgo エンタープライズの製品ワークフロー向けに Ionic エンタープライズプラグインの代替 Ionic エンタープライズプラグインの代替の製品ワークフロー向けに Capgo の代替 Capgo の代替の製品ワークフロー向けに Capgo コンサルティング Capgo コンサルティングの製品ワークフロー向けに Capgo プレミアムサポート Capgo プレミアムサポートの製品ワークフロー向けに

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