Capacitor アプリを Capacitor 8 へアップグレードする方法

Capacitor アプリを Capacitor 8 にアップグレードするには、Node.js 22+、Xcode 26+、Android Studio Otter をインストールし、 @capacitor/cli 最新の 8.x にアップデートして、次を実行します bunx cap migrate、次にマイグレーターが報告する内容を修正します。主な破壊的変更は、iOS 15が最小デプロイターゲット、Android SDK 36（minSdk 24）、AGP 8.13とGradle 8.14.3、および adjustMarginsForEdgeToEdge 新しいSystem Barsプラグインへの置き換えに伴う削除です。

このガイドでは、自動化された手順、その裏にあるすべての手動ステップ、アップグレード後によく発生するエラーを順に説明します。アプリではなくプラグインをメンテナンスしている場合は、代わりに Capacitor プラグインを Capacitor 8 へアップグレードする方法 こちらを読んでください。

Capacitor 8 の要件まとめ

プロジェクトに手を加える前に、ツールチェーンを確認してください。アップグレードの失敗の多くは、code 自体ではなく、古いJDK、古いXcode、CI上の古いNodeが原因です。

Xcode 26は単なる Capacitor の要件ではありません。2026年4月28日以降、App Store Connectは古いXcodeでビルドされたアップロードを拒否するため、いずれにせよ必要になります。詳細は Appleによる Capacitor アプリ向けのXcode 26要件 をご確認ください。

開始する前に

1. すべてコミットするか、ブランチを作成してください。移行ツールはネイティブファイルを直接書き換えます。
2. 現時点でアプリが Capacitor 7 でビルドできることを確認してください。壊れたプロジェクトをアップグレードしても、ノイズが増えるだけです。
3. Capacitor 6以前をお使いの場合は、先に前のメジャーバージョンへ移行してください。メジャーバージョンごとに CLI に独自の移行ロジックがあります。
4. 以下のコマンドでプラグインを一覧表示し、 bunx cap ls 各プラグインに Capacitor 8 をサポートするリリースがあるか確認してください。以下を参照してください。 peerDependencies 最新バージョンの:

bun pm view @capgo/capacitor-updater peerDependencies

プラグインが @capacitor/core: ^7.0.0 をpeerとして持つ場合、警告付きでインストールされ、コンパイルに失敗する可能性があります。Capgo プラグインは独自のバージョン番号で Capacitor のメジャーバージョンに従うため、 @capgo/* 8.x リリースは Capacitor 8 をターゲットにしています。

5. ローカルおよびCIツールチェーンを更新してください: Node 22、Xcode 26、JDK 21、Android Studio Otter。GitHub Actions では、Xcode 26 が含まれる macOS イメージを固定し、 actions/setup-java を使用して java-version: '21'.

オプション 1: 以下でアップグレード cap migrate

CLI には、ほとんどの作業を処理する移行コマンドが含まれています。最新の CLI をインストールしてから、実行してください:

bun add -D @capacitor/cli@latest
bunx cap migrate

移行ツールは、新しい Capacitor パッケージをインストールするかどうかを尋ね、npm、Yarn、pnpm、または Bun から選択できます。プロジェクトで Bun を使用している場合は、それを選択してください。 bun.lock。プロンプトはスキップできます bunx cap migrate --noprompt.

変更内容:

• バージョンアップ @capacitor/core, @capacitor/ios, @capacitor/android および公式 @capacitor/* プラグインを8.xへアップグレードします。
• 設定します IPHONEOS_DEPLOYMENT_TARGET = 15.0 Xcodeプロジェクト内および platform :ios, '15.0' Podfile内。
• アップデート variables.gradle、AGPクラスパス、Gradle wrapper、および kotlin_version.
• 追加 density まで android:configChanges における AndroidManifest.xml.

出力全体を確認してください。ファイルがカスタマイズ済みなどの理由でステップを適用できない場合、CLI はファイル名付きのエラーを表示して続行します。それらの行が手動対応のToDoリストです。

完了したら：

bun run build
bunx cap sync

次に、各プラットフォームを開き、IDEから一度ビルドして、ネイティブエラーを詳細に確認してください。

オプション2：手動でアップグレードする

ネイティブプロジェクトを大幅にカスタマイズしている場合や、移行ツールがステップをスキップした場合は、手動で変更を適用してください。これらは以下の 公式の Capacitor 8 アップグレードガイド.

npm パッケージを更新する

bun add @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
bun add -D @capacitor/cli@latest

次に、各公式プラグインを更新します。例：

bun add @capacitor/app@latest @capacitor/splash-screen@latest @capacitor/status-bar@latest

iOS: Deployment Target を 15.0 に上げる

Xcode でプロジェクトを選択し、 ビルド設定を開いて、 iOS Deployment Target を 内の デプロイ 15.0 に設定します。拡張機能を含め、すべてのアプリターゲットで繰り返します。

アプリがまだ CocoaPods を使用している場合は、更新してください ios/App/Podfile:

platform :ios, '15.0'

次に実行します bunx cap sync iosこれは次を実行します pod install あなたの代わりに行います。

アプリが SPM を使用している場合、CLI が再生成されます ios/App/CapApp-SPM/Package.swift 正しいプラットフォームバージョンと正確な capacitor-swift-pm インストール済みのバージョンと一致する @capacitor/ios。このファイルを直接編集しないでください。

iOS: カスタムビューコントローラーの通知を削除

Capacitor 8 は CAPBridgeViewController の通知を viewDidAppear と viewWillTransition 自身から発行します。拡張機能やサブクラスを追加して .capacitorViewDidAppear または .capacitorViewWillTransitionをポストしていた場合は削除してください。そうしないとリスナーが2回発火します。

Android: Android Studio と AGP を更新

Android Studio Otter 以降をインストールし、 android フォルダで実行 ツール > AGP アップグレード アシスタント。8.13.0 を選択して、選択したステップを実行します。または編集 android/build.gradle 直接:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

そして android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

Android: アップデート variables.gradle

ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}

プラグインが読み取る追加の変数はそのまま保持してください（例： firebaseMessagingVersion）。Capacitor 8 向けの公式プラグインアップデートには以下が含まれます： firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' と androidxExifInterfaceVersion = '1.4.1'.

Android: 切り替え = Gradle ファイルでの代入式

Gradle ではスペース区切りの代入構文が非推奨になりました。現在は警告のみですが、将来の Gradle リリースで動作しなくなるため、今のうちに修正してください： android/app/build.gradle:

android {
-    namespace "com.example.app"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.example.app"
+    compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
}

以下のようなメソッド呼び出しは、 google() または mavenCentral() そのままにします。

Android: Kotlin と configChanges

アプリモジュールで Kotlin を使用している場合は、次を設定してください： kotlin_version = '2.2.20'. Kotlin 2.x では、従来の kotlinOptions {} ブロックがエラーになるので、移動してください jvmTarget 次のように分類しています kotlin { compilerOptions { ... } }.

次に、以下を追加します： density main activity に追加して、表示密度が変更された際（折りたたみデバイス、ウィンドウのリサイズ、表示サイズ設定など）に WebView が再生成されないようにします：

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Android: bridge レイアウト名が変更されました。

bridge_layout_main.xml はもう存在しません。もし MainActivity またはカスタム fragment が参照している R.layout.bridge_layout_main、 R.layout.capacitor_bridge_layout_main.

Edge-to-edge と新しい System Bars plugin

これが最も見た目に現れやすい変更です。Capacitor 8 では削除されました。 android.adjustMarginsForEdgeToEdge さらに、コアとなる System Bars plugin を追加しました。インストールは不要で、標準で同梱されています。 @capacitor/core.

Android 15では、SDK 35をターゲットとするアプリでedge-to-edgeが強制され、Android 16ではSDK 36をターゲットとするアプリのオプトアウトが廃止されます。Capacitor 8は36をターゲットにしているため、insetsを処理しない限り、Webコンテンツはステータスバーとナビゲーションバーの背後に描画されます。

プラグイン設定は次の場所にあります： plugins.SystemBars:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    SystemBars: {
      // 'css' (default) injects --safe-area-inset-* variables on Android
      // 'native' relies on env() and viewport-fit
      // 'disable' leaves inset handling entirely to you
      insetsHandling: 'css',
      initialViewportFitValueHint: 'cover',
    },
  },
};

export default config;

を使用すると、 css または native、新しいAndroid WebView（Chromium 140以降）は viewport-fit=cover 実際の env(safe-area-inset-*) 値を報告します。古いWebViewでは、Capacitor がWebViewにパディングを適用し、env値を設定します。 0pxそのため、metaタグを設定し、次の変数を使用してください：

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

実行時にバーのスタイルや表示/非表示を変更できます：

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
await SystemBars.hide({ bar: SystemBarType.NavigationBar });

Ionic Frameworkのアプリはすでにsafe-area変数を使用しているため、通常はmetaタグの追加だけで済みます。以前の投稿 「プラグインなしのedge-to-edge」 では、8では廃止されたCapacitor 7のオプションについて説明しています。

その他の動作変更点

• appendUserAgent iOSの場合: Capacitor 7では文字列の前にスペースが2つ追加されましたが、Capacitor 8では1つになります。サーバー側でUser Agentを厳密にパースしている場合は、文字列の先頭にスペースを追加してください ios.appendUserAgent （Androidにも影響するrootオプションではありません）。
• Screen OrientationとBarcode Scanner: Android 16以降の大画面デバイスでは、向きのロックは無視されます。一時的なオプトアウトは次の android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY manifestプロパティで可能ですが、Android 17では廃止されます。
• 位置情報: timeout は、AndroidとiOSのすべてのリクエストに適用されるようになりました。新たにタイムアウトが発生する場合は、値を大きくしてください。 watchPosition のAndroid版に interval オプションが追加されました。
• ステータスバー: プラグインは独自の通知ファイルを同梱しなくなりました CAPBridgeViewController コアがこれらのイベントを発行するようになったためです。
• 新しい iOS プラットフォームではデフォルトで SPM が使われます: bunx cap add ios SPM プロジェクトを作成するようになりました。 --packagemanager CocoaPods 以前のテンプレートが必要な場合は、こちらを使用してください。詳細は Capacitor 8 で CocoaPods を使う方法.

アップグレードの確認

リリース前に、両方のプラットフォームでこのリストを確認してください：

bunx cap doctor
bunx cap sync
bunx cap run ios
bunx cap run android

• cap doctor core、CLI、iOS、Android の対応する 8.x バージョンを表示します。
• アプリが起動し、スプラッシュ画面が非表示になり、ディープリンクで正しい画面が開くこと。
• Android 15/16 デバイスやノッチ付き iPhone で、ステータスバーとナビゲーションバーの領域が正しく表示されること。
• プッシュ通知、カメラ、ファイルアクセス、およびネイティブ権限を持つプラグインが引き続き動作すること。
• リリースビルド（Xcodeのアーカイブ、 ./gradlew bundleRelease）が成功し、デバッグビルドだけでなく。

すべてのマシンでXcode 26とJDK 21をメンテナンスしたくない場合は、 Capgo のビルド 最新のツールチェーンでiOSとAndroidのビルドをクラウドで実行します。

Live Updateでアップグレードを安全にリリース

Capacitorのメジャーアップグレードはネイティブのcodeを変更するため、App StoreとGoogle Playを経由する必要があります。アップグレード後にビルドされたWebバンドルは、古いバイナリに存在しないプラグインAPIを呼び出す可能性があります。

以下を使用する場合は、 Capgo Live Updates、Capacitor 7 ユーザーと Capacitor 8 ユーザーを、普及が追いつくまで分離してください。ネイティブバージョンを上げ、新しいバイナリが使用するチャネルに新しいバンドルをアップロードし、 互換性チェック アップロード前に:

bunx @capgo/cli@latest bundle compatibility

バンドル内のネイティブプラグインのバージョンと、チャンネル上で実行中のバージョンを比較し、ユーザーに壊れたアップデートが届く前に不一致を検知します。

よくある Capacitor 8 アップグレードエラーのトラブルシューティング

The engine "node" is incompatible または CLI が実行できない場合。 Node 20 以前を使用しています。Node 22 LTS をインストールし、CI イメージも更新してください。

error: invalid source release: 21 Androidの場合 Gradle が JDK 17 で実行されています。Android Studio の JDK 設定を同梱の JDK 21 (設定 > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK) に設定し、 JAVA_HOME コマンドラインや CI ビルド用に JDK 21 を設定してください。

Minimum supported Gradle version is 8.13. AGP は更新されましたが、wrapper が更新されていません。wrapper を 8.14.3 に設定してください。

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion どこかでまだ 35 が使用されています。以下を確認してください： variables.gradle および、そのバージョンをハードコードしているプラグイン。

Using 'kotlinOptions' ... is an error または同様の Kotlin DSL エラーです。プラグインまたはアプリモジュールがまだ使っているもの： kotlinOptions。プラグインをアップデートするか、リリースが出るまでパッチを当ててください（次を参照： Capacitor プラグインのパッチ方法）).

Xcode: No such module 'Capacitor' アップグレード後。 CocoaPods の場合は、次を開いて App.xcworkspaceではなく、 App.xcodeproj、再実行してください。 bunx cap sync ios。SPM の場合は、次を使用してください： File > Packages > Reset Package Caches.

"X" plugin is not implemented on ios/android. プラグインが同期されていないか、Capacitor 8 / SPM 対応のリリースがありません。次を実行し bunx cap sync 、警告を確認してください。

より長いリストについては、 Capacitor iOSトラブルシューティングガイド および Androidトラブルシューティングガイド。コアとプラグインのバージョン不一致については Capacitor のバージョン不一致エラーを修正する方法.

AIエージェントに面倒な作業を任せる

Claude Code、Cursor、または同様のエージェントを使用している場合、オープン Capgo のスキル には以下が含まれます： capacitor-app-upgrade-v7-to-v8 と capacitor-app-upgrades メジャーバージョンの複数回ジャンプに対応します。以下でインストールしてください。 bunx skills add Cap-go/capgo-skills そして、エージェントにアプリのアップグレードを依頼します。エージェントはマイグレーターを実行した後、Gradleの構文、Kotlinのオプション、CIイメージなど、CLI が通常見落としがちなステップを確認します。

次のステップ

Capacitor 9 はすでにプレリリース版として公開されています。バージョン8で安定したら、以下を読んでください。 Capacitor 9 の準備 次回のアップグレードを小さくするために。