メインコンテンツへスキップ
Capacitor 移行 開発

Capacitor プラグインを Capacitor 8 へアップグレードする方法

Capacitor プラグインを Capacitor 8 へアップグレード：peer dependencies、SDK 36、AGP 8.13、Kotlin 2.2 compilerOptions、Java 21、iOS 15、Package.swift、リリース手順。

記事クレジット

マーティン・ドナディエ

ライター

Valeria

レビュアー

ジョーダン

編集者
Capacitor 8 プラグインアップグレードガイド用、ダークブルー背景の Capgo プラグインロゴ

Capacitor プラグインを Capacitor 8 にアップグレードするには、次を実行してください： bunx @capacitor/plugin-migration-v7-to-v8@latest プラグインのルートで実行し、差分を確認してください：Capacitor の依存関係は 8.x に移行、Android は minSdk 24 で SDK 36 をターゲットに、AGP 8.13 と Gradle 8.14.3、Kotlin は 2.2.20 になり、 compilerOptions、iOS はデプロイメントターゲットが 15.0 に変更されます capacitor-swift-pm 8. 最後に、両プラットフォームでサンプルアプリをビルドし、新しいメジャーバージョンを公開します。

このガイドはプラグインのメンテナー向けです。アプリチームは Capacitor アプリを Capacitor 8 へアップグレードする方法.

プラグイン作者向けの変更点

ファイル 変更内容
package.json @capacitor/core ピア >=8.0.0、開発依存 @capacitor/cli, core, android, ios まで ^8.0.0
android/build.gradle compileSdk = 36, minSdkVersion = 24, targetSdkVersion = 36、AndroidX バージョンアップ
android/build.gradle （buildscript） AGP 8.13.0, google-services 4.4.4、Kotlin 2.2.20
android/gradle/wrapper/gradle-wrapper.properties Gradle 8.14.3
すべての Gradle ファイル = 代入構文、 kotlinOptions に置き換えられました compilerOptions
*.podspec s.ios.deployment_target = '15.0'
Package.swift .iOS(.v15) と capacitor-swift-pm from: "8.0.0"

ローカルおよびCIで必要なプラットフォームツール: Node.js 22+、Xcode 26+、Android Studio Otter (2025.2.1) 以降、JDK 21。

オプション1：公式移行ツールを実行する

プラグインのルートディレクトリで、git ツリーがクリーンな状態で:

bunx @capacitor/plugin-migration-v7-to-v8@latest

ツール:

  • Capacitor の依存関係を更新し、パッケージのバージョンを以下に設定します 8.0.0.
  • 公式テンプレートで使用される開発ツールを更新します: @capacitor/docgen、Rollup、TypeScript、 @types/node、および Prettier（v2 から v3 へのアップグレードが必要な場合 @ionic/prettier-config、さらに prettier-plugin-java).
  • を削除し node_modules/@capacitor と package-lock.jsonを実行します npm install。Bun を使用している場合、このステップは警告とともに失敗します。実行してください bun install を自分で実行し、コミットしてください bun.lock.
  • Gradle wrapper を再生成します ./gradlew wrapper --gradle-version 8.14.3.
  • を書き換えます build.gradle：SDK レベル、AndroidX バージョン、AGP、Kotlin バージョン、Java 21 互換性、および kotlinOptions まで compilerOptions.
  • podspec のデプロイターゲットを 14.0 から 15.0 に引き上げ、 Package.swift で .iOS(.v15) と from: "8.0.0" を capacitor-swift-pm.

期待される文字列が見つからない場合、ログに Unable to find "..." in <file>. Try updating it manually。これらの各行はすべて手動での作業を意味します。カスタム Gradle ロジック、非標準のフォルダ、またはファイル名が変更されているプラグインほど、多くの警告が発生します。

Prettier が v2 から v3 に移行した場合は、移行後に format と lint スクリプトを実行してください。フォーマットの差分が大きくなる可能性があるため、機能変更とは別にコミットしてください。

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

ツールがファイルをパースできない場合、または各変更を確認したい場合に使用します。手順は 公式プラグインアップグレードガイド.

1. 依存関係

{
  "devDependencies": {
    "@capacitor/android": "^8.0.0",
    "@capacitor/cli": "^8.0.0",
    "@capacitor/core": "^8.0.0",
    "@capacitor/ios": "^8.0.0"
  },
  "peerDependencies": {
    "@capacitor/core": ">=8.0.0"
  }
}

2. Android SDK レベルと Gradle 構文

android {
    namespace = "com.example.plugin"
    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
    defaultConfig {
        minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
        targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
    }
    lintOptions {
        abortOnError = false
    }
}

この project.hasProperty(...) ? rootProject.ext... : default パターンを維持してください。これにより、ホストアプリ側で variables.gradle 値を制御できるため、アプリで「バージョン36に対してコンパイル」系のエラーを回避できます。

この = この構文はプロパティにのみ適用されます。次のようなメソッド呼び出しは mavenCentral() メソッド呼び出しは変更されず、 maven { url = "..." } には =.

3. AndroidX のデフォルト

プラグインが実際に使っているライブラリだけを上げてください。Capacitor 8 のデフォルトは次のとおりです：

ext {
    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
    androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.17.0'
    androidxActivityVersion = project.hasProperty('androidxActivityVersion') ? rootProject.ext.androidxActivityVersion : '1.11.0'
    androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
}

公式リストのその他： androidxCoordinatorLayoutVersion 1.3.0, androidxFragmentVersion 1.8.9, firebaseMessagingVersion 25.0.1, androidxBrowserVersion 1.9.0, androidxMaterialVersion 1.13.0, androidxExifInterfaceVersion 1.4.1, coreSplashScreenVersion 1.2.0.

4. AGP と Gradle wrapper

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
    }
}
cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

プラグインで Firebase または他の Google Services を使用している場合は、以下を設定します com.google.gms:google-services まで 4.4.4.

5. Java 21 と Kotlin 2.2

AGP 8.13 と SDK 36 には Java 21 が推奨されます。プラグイン自体には Java 17 でも動作します。

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

Kotlin プラグインの場合、デフォルトのバージョンを更新し、 jvmTarget から kotlinOptionsへ移動します。Kotlin 2.2 では旧ブロックがエラーになります:

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

buildscript {
    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
}

android {
    // remove: kotlinOptions { jvmTarget = '17' }
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.JVM_21
    }
}

保持 jvmTarget と targetCompatibility 同じ Java バージョンにしてください。そうしないと、Gradle が「Inconsistent JVM-target compatibility」エラーで停止します。まだ適用している場合は kotlin-android-extensions、削除してください。代わりに kotlin-parcelize を @Parcelize と view binding を synthetic view へのアクセスに使用してください。

6. iOS デプロイメントターゲット

Podspec:

s.ios.deployment_target = '15.0'

Package.swift:

platforms: [.iOS(.v15)],
dependencies: [
    .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
],

使用する from:ではなく、 branch: または exact:。アプリが生成した CapApp-SPM package の固定先は capacitor-swift-pm インストールされているアプリの正確なバージョンで、 @capacitor/ios 範囲を指定すると SPM がそのバージョンに対してプラグインを解決できます。

旧 Xcode プロジェクトレイアウトを使うプラグインも、プロジェクトの deployment target を引き上げる必要があります。 ビルド設定 および ios/Podfile (platform :ios, '15.0').

プラグインにまだ Package.swift ない場合は、次にそれを行ってください。Capacitor 8 で作成されたアプリはデフォルトで SPM を使用するため、プラグインが未対応だと「not compatible with SPM」という警告を出してスキップします。以下に従ってください： Capacitor プラグインを Swift Package Manager へ移行する方法.

オプション 3: エージェントに任せる

オープンな Capgo のスキル には以下が含まれます： capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades 複数バージョンをまたぐ移行用、および capacitor-plugin-spm-support。インストールは bunx skills add Cap-go/capgo-skills で行い、エージェントにプラグインのアップグレードを依頼してください。この Skill は公式ツールを実行した後、ツールがスキップとしてログに記録したステップを処理します。差分は、チームメイトの PR をレビューするときと同じようにレビューしてください。

どの手法を使うべきか

アプローチ 適したユースケース 注意点
マイグレーションツール 公式テンプレートから生成されたプラグイン カスタマイズ済みファイルでスキップされたステップ、 npm install Bun のステップ
手動 GradleまたはXcodeのセットアップが大幅にカスタマイズされている AndroidXやKotlinの変更を1つ見落としやすい
エージェント + スキル アップグレードが必要なプラグインが多い、またはレイアウトが混在している レビューは引き続きあなたが行う

ほとんどの場合、ツールから始めること。ログが残りの作業を正確に教えてくれる。

公開前に確認

  1. bun install && bun run build （または自分の verify スクリプト）。
  2. Android: cd android && ./gradlew clean build test。JDK 21でビルド。
  3. CocoaPods を使用した iOS: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (新しいレイアウトのプラグインは xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
  4. SPM を使用した iOS: swift package resolve、その後スキームをビルドします。
  5. プラグインを新しい Capacitor 8 アプリにインストールします(bunx cap add ios デフォルトでSPMを利用できます）し、CocoaPodsアプリでも同様です。実機でpublicメソッドをすべて呼び出してください。
  6. 実行 bunx cap doctor テストアプリで。

リリース

  • 新しいメジャーバージョンに上げます（ツールが使用する 8.0.0）。minSdkとiOSの最小バージョンを引き上げることは、利用者にとって破壊的変更です。
  • 短いリリースノートを書き、 BREAKING.md またはchangelogエントリを書いてください：新しいpeer依存範囲、minSdk 24、iOS 15、ビルド用Java 21、APIの挙動変更。
  • ブランチを維持する 7.x （Capacitor 7のユーザー向けに修正を出し続ける場合）。それらは次のようなdist-tagで公開してください： latest-7.
  • READMEのインストールセクションと互換性テーブルを更新してください。

Capgo はこのサイクルで多数のプラグインをメンテナンスしており、各 @capgo/* Capacitor のメジャーアップデートを追跡しています。一覧はこちら： プラグインディレクトリ.

トラブルシューティング

invalid source release: 21. Gradle が JDK 17 以下で動作しています。Android Studio Otter に同梱の JDK 21 を使い、 JAVA_HOME CI で設定してください。

Unsupported class file major version 65. 逆の問題：Java 21 のクラスファイルを読めない古い Gradle wrapper で JDK 21 を実行しているケースです。wrapper を 8.14.3 で再生成してください。

Namespace not specified. AGP 8+ では、 namespace = "..." プラグインの android ブロック内に記述します。古いプラグインでは package 属性が AndroidManifest.xml内にありました。これを Gradle に移動し、 package manifest から削除してください。

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Kotlin jvmTarget が一致しない、 targetCompatibility。両方を 21 にするか、両方を 17 にしてください。

言及するエラー proguard-android.txt AGP 9 での AGP 9 を実行しているアプリもあります。 proguard-android-optimize.txt に切り替えて、これらのアプリでもプラグインがビルドされるようにしてください。詳細は AGP 9 で Capacitor プラグインのビルドエラーを修正する.

SPM: product 'Capacitor' required by package ... not found. お使いの Package.swift 依存関係の行に誤字があるか、存在しないバージョンが指定されています。 from: "8.0.0" に対して https://github.com/ionic-team/capacitor-swift-pm.git.

Play Console での 16 KB ページサイズに関する警告。 プラグインにネイティブ .so ライブラリが含まれる場合は、16 KB アラインメントで再ビルドしてください。 Android 16 KB ページサイズと Capacitor プラグイン.

プラグインが 8 にアップグレードされたら、次のステップは 9 への準備です。 Capacitor 9 の準備 は、Capacitor 8 のユーザーに影響を与えずに今すぐプラグインチームが変更できる項目をリストアップしています。

Capacitor アプリ向けの Live Updates

Web レイヤーのバグが本番で発生したら、App Store の審査を何日も待たずに Capgo で修正を配信しましょう。ネイティブの変更は通常の審査フローに残したまま、ユーザーはバックグラウンドでアップデートを受け取れます。

最新のブログ記事

Capgoは、真にプロフェッショナルなモバイルアプリを作るために必要な最高のインサイトを提供します。

WindowsでのWSL2を使ったCapacitor開発
チュートリアル Capacitor +1
2026年10月8日

WindowsでのWSL2を使ったCapacitor開発

Capacitor Windowsでの開発：完全セットアップガイド
チュートリアル Capacitor +1
2026年10月8日

Capacitor Windowsでの開発：完全セットアップガイド

LinuxでのCapacitor開発：完全セットアップガイド
チュートリアル Capacitor +1
2026年10月8日

LinuxでのCapacitor開発：完全セットアップガイド

ブログ記事一覧を見る