How to Upgrade Your Capacitor App to Capacitor 8

To upgrade a Capacitor app to Capacitor 8, install Node.js 22+, Xcode 26+ and Android Studio Otter, update @capacitor/cli 、を実行し、 bunx cap migrate, then fix whatever the migrator reports. The main breaking changes are iOS 15 as the minimum deployment target, Android SDK 36 with minSdk 24, AGP 8.13 with Gradle 8.14.3, and the removal of adjustMarginsForEdgeToEdge の代わりに新しい System Bars プラグインを使用することです。

このガイドでは、自動化されたパス、自動化されていないステップ、およびアップグレード後に最もよく発生するエラーについて説明します。プラグインを管理している場合は、 How to Upgrade Your Capacitor Plugin to Capacitor 8 を参照してください。

Capacitor 8 の要件の概要

プロジェクトに触れる前にツールチェーンを確認してください。ほとんどのアップグレード失敗は、古い JDK、古い Xcode、または CI の古い Node ではなく、code です。

Xcode 26 is not only a Capacitor requirement. Since April 28, 2026, App Store Connect rejects uploads built with an older Xcode, so you need it anyway. See AppleのXcode 26の要件はCapacitorアプリに適用されます。 Capacitor 8 にアップグレードするには、以下のステップを実行してください。

開始する前に

1. すべての変更をコミットするか、ブランチを作成します。マイグレーターは、ネイティブファイルをそのまま編集します。
2. アプリが Capacitor 7 でビルドされることを確認してください。破損したプロジェクトをアップグレードすると、ノイズが増加します。
3. If you are on Capacitor 6 or older, do the previous major first. Each major has its own migration logic in the CLI.
4. プラグインのリストを作成し、 bunx cap ls を確認してください。各プラグインが Capacitor 8 をサポートしていることを確認してください。最新バージョンの peerDependencies のバージョンを確認してください。

bun pm view @capgo/capacitor-updater peerDependencies

プラグインのペアとして @capacitor/core: ^7.0.0 を持つプラグインは、警告とともにインストールされ、コンパイルに失敗する可能性があります。 Capgo プラグインは、 Capacitor メジャーに従って、独自のバージョン番号を使用します。 @capgo/* Capacitor 8 へのリリースは、 Capacitor 8 をターゲットにします。

5. ローカルとCIツールチェーンをアップデートしてください: Node 22、Xcode 26、JDK 21、Android Studio Otter。 GitHub Actions では、Xcode 26 を含む macOS イメージを固定し、 actions/setup-java with java-version: '21'.

Option 1: with cap migrate

The CLI ships a migration command that handles most of the work. Install the latest CLI, then run it:

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

マイグレーターは、新しいCapacitorパッケージをインストールするかどうかを尋ね、またnpm、Yarn、pnpm、またはBunを選択することを許可します。プロジェクトがBunを持つ場合に選択してください。 bun.lockプロンプトをスキップするには bunx cap migrate --noprompt.

変更されること:

• バージョンを8.xに上げる @capacitor/core, @capacitor/ios, @capacitor/android 公式 @capacitor/* プラグインを8.xに上げる
• を8.xに上げる IPHONEOS_DEPLOYMENT_TARGET = 15.0 を8.xに上げる platform :ios, '15.0' を8.xに上げる
• アップデート variables.gradle、AGPクラスパス、Gradleワッパーと kotlin_version.
• 追加 density に android:configChanges in AndroidManifest.xml.

Read the full output. When a step cannot be applied, for example because a file was customized, the CLI prints an error with the file name and continues. Those lines are your manual to-do list.

Then open each platform and build it once from the IDE so you see native errors in full.

bun run build
bunx cap sync

Option 2: upgrade manually

If your native projects are heavily customized, or the migrator skipped steps, apply the changes by hand. These match the

official __CAPGO_KEEP_0__ 8 upgrade guide Update the Capacitor packages.

Update the npm packages

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: デプロイメントのターゲットを 15.0 に上げてください

Xcode でプロジェクトを選択し、 プロパティ, で under を探してください デプロイメント

の下に ios/App/Podfile:

platform :ios, '15.0'

Then run bunx cap sync iosアプリがまだ CocoaPods を使用している場合、 pod install あなたのために。

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

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

Capacitor 8は CAPBridgeViewController と viewDidAppear の通知を発行します。 viewWillTransition 自分自身の通知も発行します。アプリに拡張機能またはサブクラスを追加した場合は .capacitorViewDidAppear or .capacitorViewWillTransitionリスナが二回発火するため、削除するか、またはリスナを削除する必要があります。

Android: Android Studio と AGP を更新

Install 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'
    }
}

And android/gradle/wrapper/gradle-wrapper.properties:

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

プラグインが読み取る追加変数をすべて保持してください (例えば) 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'
}

公式のプラグインバージョンアップは __CAPGO_KEEP_0__ 8 に含まれます firebaseMessagingVersion). Official plugin bumps for Capacitor 8 include firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' and androidxExifInterfaceVersion = '1.4.1'.

context = Gradleファイルの割り当て

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:!*~'
         }
     }
}

Gradleファイルのメソッド呼び出し google() または mavenCentral() Capacitorライブアップデートの代替

現在のままにしておいてください。 configChanges

Android: Kotlinと kotlin_version = '2.2.20'Kotlinを使用するアプリモジュールでは、次のようになります。 kotlinOptions {} Kotlin 2.xでは、古い jvmTarget into kotlin { compilerOptions { ... } }.

に移動してください。 density 主活動に追加してください。 WebViewが表示密度の変更 (折り畳み、ウィンドウサイズの変更、表示サイズの設定) のときに再作成されないようにします。

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

Android: 画面レイアウトの名前が変更されました。

bridge_layout_main.xml は存在しません。 ご利用中の MainActivity またはカスタムのフラグメントが参照されていた場合 R.layout.bridge_layout_mainを使用してください。 R.layout.capacitor_bridge_layout_main.

Edge-to-edge と新しい System Bars プラグイン

これは、最も視覚的に表示される変更です。 Capacitor 8 は削除され android.adjustMarginsForEdgeToEdge と、コアの System Bars プラグインが追加されました。 インストールする必要はありませんが、 @capacitor/core.

Android 15 は、SDK 35 をターゲットとするアプリにエッジツーヨーローエッジを強制し、Android 16 は、SDK 36 をターゲットとするアプリからオプトアウトのオプションを削除します。 Capacitor 8 は 36 をターゲットしているため、ステータスバーとナビゲーションバーの後ろにウェブコンテンツが描画されます。 これを回避するには、インセットを処理する必要があります。

プラグインの設定は 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;

With css または native、新しい Android WebViews (Chromium 140+) は viewport-fit=cover と実際の env(safe-area-inset-*) 値を報告します。古いWebViewsでは、Capacitor はWebViewを拡張し、環境変数を設定します。 0px値を設定します。なので、メタタグを設定し、変数を使用してください。

<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 });

イオニックフレームワークアプリはすでに安全なエリアの変数を使用しているため、通常はメタタグのみが必要です。古い投稿 端末の端から端までの表示 を使用して、Capacitor 7 のオプションを使用しましたが、Capacitor 8 では存在しません。

他の変更点を確認してください。

• appendUserAgent iOSで、Capacitor 7 は文字列の前に2つのスペースを追加し、Capacitor 8 は1つのスペースを追加します。ユーザーエージェントを厳密に解釈するサーバーがある場合は、先頭にスペースを追加してください。 ios.appendUserAgent 画面の向きとバーコードスキャナー
• スクリーン オリエンテーションとバーコード スキャナー: Android 16+ の大きな画面では、オートロックは無視されます。 一時的なオプトアウトは、manifest プロパティを通じて実行できますが、Android 17 では廃止されます。 android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY manifest プロパティを使用してオプトアウトすることができます。
• Geolocation: timeout すべてのリクエストに適用されます。タイムアウトが発生する場合は値を増やしてください。 watchPosition Android では新しいオプションが追加されました。 interval Status Bar
• ステータス バーiOS の新しいプラットフォームでは SPM がデフォルトになりました。 CAPBridgeViewController Capacitor CLI は SPM プロジェクトを作成します。古いテンプレートが必要な場合は
• を使用してください。: bunx cap add ios context --packagemanager CocoaPods blog/upgrade-capacitor-app-to-capacitor-8 How to use CocoaPods with Capacitor 8.

アップグレードを確認する

両方のプラットフォームで、以下のリストを実行してください:

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のビルドを実行します。

安全にアップグレードしてライブアップデートを実行

A Capacitor major upgrade changes native code, so it has to go through the App Store and Google Play. Web bundles built after the upgrade may call plugin APIs that older binaries don’t have.

If you use Capgo ライブアップデート, keep Capacitor 7 users and Capacitor 8 users apart until adoption catches up: bump your native version, upload new bundles to a channel used by the new binary, and run the Capacitor 8のライブアップデート Capacitor 8のライブアップデート

bunx @capgo/cli@latest bundle compatibility

Capacitor 8のライブアップデート

Troubleshooting common Capacitor 8 upgrade errors

The engine "node" is incompatible またはCLIが実行されない。 Capacitor 8のライブアップデート

error: invalid source release: 21 Androidで。 GradleはJDK 17で実行中です。Android Studioの設定から、組み込まれたJDK 21 (設定>ビルド、実行、デプロイ>ビルドツール>Gradle>Gradle JDK) と設定します。 JAVA_HOME をJDK 21に設定してください。

Minimum supported Gradle version is 8.13. AGPを更新しましたが、ラッパーはまだ8.14.3に設定されていません。ラッパーを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エラー。プラグインまたはアプリモジュールがまだ使用しています。 kotlinOptionsXcode: how to patch a Capacitor plugin).

Xcode: No such module 'Capacitor' アップグレード後。 CocoaPodsの場合、開きます。 App.xcworkspace, not App.xcodeproj, and rerun bunx cap sync iosSPMの場合、使用します。 ファイル>パッケージ>パッケージキャッシュをリセット.

"X" plugin is not implemented on ios/android. プラグインが同期されていません、またはCapacitor 8 / SPM互換のリリースが存在しません。Run bunx cap sync と警告を読みます。

詳細なリストは、 Capacitor iOSのトラブルシューティングガイド と __CAPGO_KEEP_0__ Androidのトラブルシューティングガイドです。 fix Capacitor version mismatch errors.

AI が面倒な部分を手伝ってください。

Claude Code を使用している場合、または似たようなエージェントである Cursor を使用している場合、オープン Capgoスキル include capacitor-app-upgrade-v7-to-v8 と capacitor-app-upgrades for multi-major jumps. Install them with bunx skills add Cap-go/capgo-skills アップグレードするアプリをエージェントに尋ねる。エージェントはマイグレーターを実行し、Gradle の構文、Kotlin のオプション、CI のイメージなど、CLI が通常見落とすステップを確認する。

次のステップは何ですか。

Capacitor 9はすでにプレビュー版です。8に安定したら、 Preparing for Capacitor 9 次のアップグレードは小さなアップデートになります。