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

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

このガイドでは、変更点、バックアップすべき内容、そして 2 つの実用的な移行パス（Capacitor 移行アシスタントの使用、または SPM による iOS プロジェクトの再スキャフォールディング）について説明します。

今移行すべき理由

CocoaPods は読み取り専用 trunk へ移行しています。現在の計画では、CocoaPods trunk は以下の日にちに新しい podspec の受け入れを停止します 2026 年 12 月 2 日。既存のビルドは引き続き動作しますが、切り替え後、trunk に依存する新しいリリースや依存関係の更新はそこで公開されなくなります。

SPM は Capacitor が向かっている方向でもあります。Capacitor は Capacitor 6 から CocoaPods または SPM の選択をサポートしており、Capacitor 8 では iOS SPM プロジェクトがデフォルトのテンプレートになりました。

Capacitor SPMプロジェクトで変わること

CocoaPods から SPM への移行は、iOS の依存関係レイヤーを置き換えます。Web アプリ、Android プロジェクト、およびほとんどの Capacitor ワークフローコマンドは同じままです。

CapApp-SPMがPodfileを置き換える

CocoaPods アプリでは、iOS の依存関係は以下を通じて接続されます ios/App/Podfile, Podfile.lock, Pods/、および生成された .xcworkspace.

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

debug.xcconfigがPods設定を置き換える

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

移行後、アシスタントの指示がある場合は、Xcode プロジェクトの設定に debug.xcconfig を追加する必要がある場合があります。

すべてのプラグインがSPM対応必須

CocoaPods と SPM を同じ Capacitor iOS プロジェクトで混在させることはできません。移行前に、すべての Capacitor と Cordova プラグインを確認してください package.json.

プラグインがまだ SPM に対応していない場合は、更新するか、置き換えるか、そのプラグインを先に移行してください。シンプルな Swift プラグインなら、Ionic の capacitor-plugin-converter、ただし Objective-C や Swift のレイアウトがより複雑なプラグインは、手動での作業が必要になる場合があります。

最初にバックアップすべきもの

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

〜から保持すべき一般的なファイル 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 ファイル
Signing設定、bundle identifier、team ID、provisioning profile設定

標準の Capacitor テンプレート以外に追加した、ネイティブのSwift、Objective-C、framework、extension、または SDK ファイルもすべて保持してください。

オプション1: Capacitor migration assistantを使う

iOSプロジェクトに失いたくないカスタムのネイティブ編集がある場合は、この方法を使ってください。

Capacitor プロジェクトのルートからassistantを実行します：

bunx cap spm-migration-assistant

assistantはCocoaPodsのインフラを削除し、ローカルの CapApp-SPM packageを作成し、インストール済みのpluginからpackage referencesを生成して、SPM設定ファイルを生成します。

完了したら、プロジェクトを開きます：

bunx cap open ios

次に、アシスタントが表示するXcodeの手動ステップに従ってください。ほとんどのプロジェクトでは、以下の手順になります：

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

Xcodeプロジェクトのビルドが完了したら、再度同期します：

bunx cap sync ios

オプション2: SPMでiOSプロジェクトを再作成

次の場合にこのパスを使用してください： 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を更新する

アプリがローカルでビルドできるようになったら、CI/CD を更新して CocoaPods を前提としないようにしてください。

以下のステップを削除します:

pod install

また、以下のキャッシュも削除します:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods の specs リポジトリ（このアプリ専用でキャッシュしていた場合）

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

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

移行チェックリスト

移行前:

新しい git ブランチを作成します。
現在の動作するアプリをコミットします。
インストール済みのすべてのプラグインが SPM をサポートしていることを確認します。
カスタム iOS ファイルと署名設定を記録します。
移行前にアプリが正常に build できることを確認します。

移行中:

実行 bunx cap spm-migration-assistant または再スキャフォールド ios/.
追加 CapApp-SPM 必要に応じてXcodeで行います。
追加 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 コマンド、またはキャッシュ Pods/ が以前のビルドから残っている場合です。

まとめ

Capacitor アプリをSwift Package Managerへ移行する作業の大部分は、iOSの依存関係の構成を置き換えることです。 CapApp-SPM が依存関係の参照を引き継ぎ、 debug.xcconfig 生成されたCocoaPodsのビルド構成を置き換え、CIではCocoaPodsが不要になります。 pod install.

カスタマイズされたiOSプロジェクトの場合は、まず bunx cap spm-migration-assistantこちらから始めてください。デフォルトのテンプレートに近いプロジェクトであれば、SPMでクリーンに再スキャフォールドする方が、手早く、かつ挙動の把握もしやすくなります。

リソース

「Capacitor AppをSwift Package Managerへ移行する方法」の続きを読む

使用している場合 Capacitor アプリを Swift Package Manager へ移行する方法 移行とエンタープライズ運用を計画するには、次と連携してください Capgo エンタープライズ Capgo Enterprise のプロダクトワークフロー向けに、 Ionic Enterprise プラグインの代替案 Ionic Enterprise Plugin Alternatives のプロダクトワークフロー向けに、 Capgo の代替案 Capgo Alternatives でのプロダクトワークフロー向け、 Capgo コンサルティング Capgo Consulting でのプロダクトワークフロー向け、および Capgo プレミアムサポート Capgo Premium Support でのプロダクトワークフロー向け。