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

Swift Package Manager は Capacitor iOS プロジェクトにおける標準的な方向性です。アプリがまだ CocoaPods を使用している場合でも、JavaScript code や Android プロジェクト、リリースワークフローをゼロから作り直すことなく、アプリ自体を SPM へ移行できます。

このガイドはアプリ開発チーム向けです。Capacitor iOS アプリを CocoaPods から SPM へ移行する方法、移行アシスタントによる変更点、Xcode で確認すべき事項、そしてアプリのビルド後に CI をクリーンアップする方法について解説します。

アプリにおける変更点

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とインストール済みのネイティブ依存関係に接続します。

Webビルドの仕組みは変わりません。従来どおりWebビルドを実行し、CapacitorをsyncしてXcodeを開き、アプリをarchiveします。主な違いは、CocoaPodsがiOSの依存関係グラフを管理しなくなる点です。

移行を始める前に

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

git status
npm run build
npx cap sync ios

その後、動作している状態をcommitしてください。移行では生成された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
app extensions、native Swiftファイル、Objective-Cファイル、embedded frameworks

インストール済みのCapacitorとCordovaの依存関係も確認してください。SPM互換のパスを持たないネイティブ依存関係があると、アプリレベルのSPM移行がブロックされることがあります。可能であれば、移行前にそれらのパッケージを更新してください。

migration assistantを使う

ほとんどの既存アプリでは、公式のCapacitor migration assistantから始めてください：

npx cap spm-migration-assistant

Capacitorプロジェクトのルートから実行してください。このassistantはCocoaPodsの統合を削除し、ローカルの CapApp-SPM packageを作成し、インストール済みのネイティブ依存関係に対するpackage referencesを生成し、iOSプロジェクトに必要な生成済み設定を追加します。

完了後、iOSプロジェクトを開きます：

npx cap open ios

ターミナルを閉じる前にassistantの出力を確認してください。手動でのXcode手順を求められた場合は、再度syncする前にそれらを完了してください。

Xcodeの手順を完了する

Xcodeで、アプリのプロジェクトとtargetの設定を確認します：

確認 CapApp-SPM がローカルのパッケージ依存関係として追加されます。
アプリのターゲットが生成されたパッケージ製品にリンクされていることを確認します。
生成された debug.xcconfig アシスタントから要求された場合は、プロジェクト設定に追加してください。
Xcodeでパッケージに関する警告を解消します。
Xcodeからアプリを一度ビルドします。

Xcodeでパッケージを解決できない場合は、以下を使用してください： File > Packages > Reset Package Caches、その後、再度パッケージを解決します。

同期して再度ビルドする

Xcodeの設定が完了したら、ターミナルに戻って Capacitor を同期します：

npx cap sync ios

その後、Xcodeから再度ビルドしてください。リリース用の署名、entitlements、app extensions、パッケージの解決などはXcodeで検証されるため、Xcodeでのクリーンビルドが成功するまでは、移行が完了したと判断しないでください。

アプリでプッシュ通知、associated domains、background modes、app groups、Firebase、またはその他のネイティブな SDK 設定を使用している場合は、ビルド成功後にシミュレーターまたは実機でそれらのフローを実行してください。

代替案：SPMを使用してiOSプロジェクトを再作成する

もしあなたの ios/ フォルダがデフォルトの Capacitor テンプレートに近い場合は、既存のプロジェクトを移行するよりも、SPMを使用して再作成する方が早い場合があります。

この方法は、必要なすべてのネイティブファイルと署名設定をコミットまたはバックアップした後にのみ実行してください：

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

その後、アプリ固有のネイティブファイルと設定を復元します。この方法ではクリーンなSPMプロジェクトが得られますが、事前に内容を把握していないと、カスタムしたXcodeの設定を失いやすくなります。

新しい Capacitor アプリの場合、Capacitor 8 ではデフォルトでSPMを使用したiOSプロジェクトが作成されます：

npx cap add ios

明示的に行うことも可能です：

npx cap add ios --packagemanager SPM

CocoaPodsの残骸をクリーンアップする

SPMでのビルド完了後、ローカルスクリプトやCIからCocoaPodsを前提とした記述を削除します。

以下のようなステップを削除してください：

pod install

また、CocoaPods専用のキャッシュも削除してください：

ios/App/Pods
ios/App/Podfile.lock
CocoaPodsのspecsリポジトリ
Podfileに基づくCIキャッシュキー

移行後の基本的なCIフローでは、JavaScriptの依存関係をインストールし、Webアプリをビルドし、Capacitorをsyncして、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.

Signingまたはentitlementsの変更

移行後のXcode targetを移行前のプロジェクトと比較してください。bundle identifier、team、provisioning profile、entitlements file、capabilities、およびextensionの設定を元に戻します。

移行チェックリスト

移行前の準備:

ブランチを作成します。
現在のiOSアプリのビルドを確認します。
動作している状態をコミットします。
カスタムネイティブファイルと署名設定を洗い出します。
すでにSPM対応の新しいリリースがあるネイティブ依存関係を更新します。

移行作業中:

実行 npx cap spm-migration-assistant.
プロジェクトを以下で開きます: npx cap open ios.
追加 CapApp-SPM 必要に応じてXcodeで行います。
追加 debug.xcconfig 必要に応じてXcodeで行います。
パッケージの警告を解消する。
実行 npx cap sync ios.

移行後：

Xcodeからアプリをビルドする。
シミュレーターまたは実機でネイティブ機能をテストする。
CIからCocoaPodsのコマンドを削除する。
CocoaPods専用のキャッシュを削除する。
アーカイブとリリース署名を確認する。

移行には Capgo Skills を活用する

AIエージェントを使って移行を行う場合は、以下から開始してください Capgo のスキル空のプロンプトではなく、この作業で最も役立つスキルは次のとおりです：

capacitor-best-practices 変更前にアプリの構造をレビューする ios/.
cocoapods-to-spm SPMへの移行とXcodeでの後続ステップを計画する
capacitor-ci-cd ビルドパイプラインからCocoaPods前提を排除する
debugging-capacitor と ios-android-logs 移行後に実機でのみ発生する問題を調査する

iOSプロジェクトを変更する前にこれらを使ってください。そうすることで、エージェントは移行コマンドを実行するだけでなく、ネイティブファイル、CI、依存関係の互換性をチェックできます。

まとめ

Capacitor アプリをSwift Package Managerへ移行するのは、主にiOSの依存関係管理の変更です。最も安全な方法は、クリーンなブランチから始めて実行し npx cap spm-migration-assistant、Xcodeでの手動ステップを完了し、再度同期し、アプリがビルドできてから初めてCIからCocoaPodsを削除することです。

iOSプロジェクトが高度にカスタマイズされている場合は、そのまま移行してください。デフォルトのCapacitorテンプレートに近い場合は、作り直す ios/ を使用して npx cap add ios --packagemanager SPM よりクリーンになります。