バートショナにいるCapacitorアイルにSwift Package Managerのバートショナを定义にした

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

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

なぜ今すぐ移行するか

CocoaPodsは、読み取り専用のトランクに移行しています。現在の計画では、CocoaPodsトランクは新しいpodspecを受け付けなくなります。 2026年12月2日既存のビルドは機能し続けるはずですが、トランクに依存する新しいリリースや依存関係の更新は、切り替え後はそこに公開されません。

SPMはCapacitorもその方向に進んでいる。CapacitorはCapacitor 6からCapacitor 8ではiOS SPMプロジェクトを作成するデフォルトのテンプレートとしている。

Capacitor SPMプロジェクトで何が変わるか

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

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

ココアポッズアプリでは、iOS依存関係は ios/App/Podfile, Podfile.lock, Pods/、と生成される .xcworkspace.

SPMアプリでは、Capacitorはローカルパッケージ CapApp-SPMを生成します。このパッケージは、Capacitorがnative iOSプラグイン依存関係を参照する中心的な場所になります。Capacitor CLIは CapApp-SPM を更新しますので、プラグインを同期するときは、生成された出力として扱い、手動で編集しないでください。

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

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

移行後、assistantが指示するように、Xcodeプロジェクト設定に"を追加する必要がある場合があります。 debug.xcconfig SPMをサポートする必要があります。

CocoaPodsとSPMを同一の__CAPGO_KEEP_0 iOSプロジェクトに組み合わせることはできません。移行する前に、assistantが指示するように、すべてのCAPGO_KEEP_1__とCordovaプラグインを確認する必要があります。

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

で簡単に変換できますが、複雑なObjective-CとSwiftレイアウトを持つプラグインには、手動で作業する必要があります。 capacitor-plugin-converter最初にバックアップするもの

clean git branchから始め、iOSプロジェクトに触れる前に、現在の状態をコミットしてください。そのあと、依存しているネイティブファイルをリストアップしてください。

保存する必要がある共通ファイル

include: ios/App/ include:

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、プロビジョニングプロファイル設定

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

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

iOS プロジェクトがカスタムネイティブ編集を持つ場合に使用するパス

Capacitor プロジェクトのルートからアシスタントを実行します:

bunx cap spm-migration-assistant

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

Option 2: Use the __CAPGO_KEEP_1__ template

bunx cap open ios

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

追加 CapApp-SPM __CAPGO_KEEP_0__テンプレートのデフォルトのディレクトリとあなたのカスタムファイルを安全に復元できる場合にのみ、
をアプリの構成に追加します。 debug.xcconfig SPMに変換できないプラグインについての警告を解決します。
CIを更新する前に、アプリをXcodeからビルドしてください。
Xcodeプロジェクトがビルドされた後、再度Syncしてください:

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

bunx cap sync ios

あなたの__CAPGO_KEEP_0__ディレクトリがデフォルトのテンプレートと近くで、カスタムファイルを安全に復元できる場合にのみ、このパスを使用してください。

まず、バックアップセクションにリストされているファイルがコミットまたは安全な場所にコピーされていることを確認してください。次に、SPMでiOSプロジェクトを削除して再作成してください。 ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

Add the generated to the app configuration.

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

アプリが必要とするネイティブファイルを復元し、プロジェクトを開きます:

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.

New Capacitor apps

For a new app, Capacitor 8 uses SPM by default when adding iOS:

bunx cap add ios

明示的に指定する必要がある場合は、パッケージマネージャーオプションを渡すことができます。

bunx cap add ios --packagemanager SPM

マイグレーション後、CIを更新します。

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

実行するステップを削除します。

pod install

また、次のキャッシュを削除します。

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs リポジトリ、キャッシュがこのアプリのみに限られている場合

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

マイグレーションチェックリスト

__CAPGO_KEEP_0__:

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

__CAPGO_KEEP_0__:

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

移行後:

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

トラブルシューティング

Xcode がパッケージを解決できない場合、Xcode からパッケージキャッシュをリセットし、実行する。 bunx cap sync ios 再度。

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

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

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

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 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. debug.xcconfig Conclusion pod install.

Migrating a __CAPGO_KEEP_0__ app to Swift Package Manager is mostly about replacing the iOS dependency wiring. bunx cap spm-migration-assistanttakes over the dependency references,

リソース

How to Migrate a Capacitor App to Swift Package Manager から続けて

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

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