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

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

Upgrade a Capacitor plugin to Capacitor 8: peer dependencies, SDK 36, AGP 8.13, Kotlin 2.2 compilerOptions, Java 21, iOS 15, Package.swift and release steps.

Article Credits

マーティン・ドナディュー

ライター

ヴァレリア

レビュアー

ジョーダン

エディター

How to Upgrade a Capacitor Plugin to Capacitor 8

To upgrade a Capacitor plugin to Capacitor 8, run bunx @capacitor/plugin-migration-v7-to-v8@latest from the plugin root, then review the diff: Capacitor dependencies move to 8.x, Android targets SDK 36 with minSdk 24, AGP 8.13 and Gradle 8.14.3, Kotlin goes to 2.2.20 with compilerOptionsCapacitor プラグインを Capacitor 8 にアップグレードする capacitor-swift-pm 8. 両プラットフォームで例のアプリをビルドし、メジャーバージョンを公開する。

プラグインメンテナ向けのガイドです。アプリチームはこのガイドを参照してください。 How to Upgrade Your Capacitor App to Capacitor 8.

プラグイン作者にとっての変更点

ファイル 変更
package.json @capacitor/core パートナー >=8.0.0, dev 依存関係 @capacitor/cli, core, android, ios to ^8.0.0
android/build.gradle compileSdk = 36, minSdkVersion = 24, targetSdkVersion = 36コンテキスト: Live updates product page. ロール: 短い UI ラベルまたはナビゲーションアイテム。 メッセージキー `live_update_dynamic_label_to` (Live Update Dynamic Label To).
android/build.gradle , AndroidX bumps 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"

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

オプション 1: オフィシャル マイグレーションツールを実行

プラグインのルートディレクトリから、clean git tree上で:

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

ツール:

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

文字列が期待どおりない場合、ログに記録します。 Unable to find "..." in <file>. Try updating it manually. Every one of those lines is a manual step for you. Plugins with custom Gradle logic, non-standard folders or renamed files produce the most of them.

If Prettier moved from v2 to v3, run your format and lint scripts after the migration. The formatting diff can be large, so commit it separately from the functional changes.

オプション 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 にコンパイルする」クラスのエラーが発生するのを避けることができます。アプリ。

The = プロパティのみに適用される構文は、 mavenCentral() メソッド呼び出しは変更されず、 maven { url = "..." } 必要なのは =.

3. AndroidXのデフォルト

プラグインが実際に使用しているライブラリのみをバージョンアップしてください。Capacitor 8のデフォルトはCapacitorです。

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ワッパー

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サービスを使用するプラグインがある場合は、 com.google.gms:google-services に 4.4.4.

5. Java 21 と Kotlin 2.2

Java 21 は AGP 8.13 と SDK 36 における推奨バージョンです。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 and targetCompatibility に kotlin-android-extensionsとビュー バインディングを使用してシンセティック ビュー アクセスを実行してください。 kotlin-parcelize context @Parcelize pagePath

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:Capacitor Live Update の代替手段について CapApp-SPM Capacitor Live Update の代替手段 capacitor-swift-pm Capacitor Live Update の代替手段 @capacitor/ios Capacitor Live Update の代替手段

Capacitor Live Update の代替手段 Capacitor Live Update の代替手段 そして ios/Podfile (platform :ios, '15.0').

Capacitor 8 にアップグレードする Capacitor プラグイン Package.swift yet, do that next. Apps created with Capacitor 8 default to SPM and will skip your plugin with a “not compatible with SPM” warning. Follow How to Migrate a Capacitor Plugin to Swift Package Manager.

SPM に移行する __CAPGO_KEEP_0__ プラグインの方法

The open オープンな Capgo スキル 複数バージョンのジャンプを含む capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades インストールしてエージェントにプラグインをアップグレードしてもらいます。スキルは公式ツールを実行し、ツールがログとしてスキップしたステップを処理します。プルリクエストをレビューするのと同じように、差分をレビューしてください。 capacitor-plugin-spm-supportどのアプローチを使用するか bunx skills add Cap-go/capgo-skills アプローチ

How to Migrate a __CAPGO_KEEP_0__ Plugin to Swift Package Manager

Approach 適切なフィット 注意してください
移行ツール 公式テンプレートから生成されたプラグイン カスタマイズされたファイルのスキップされたステップ npm install Bunのステップ
手動 重度にカスタマイズされたGradleまたはXcode設定 AndroidXまたはKotlinの変更を1つでも見落とす
エージェント + スキル 多数のプラグインをアップグレードするか、混在したレイアウト レビューはあなたのものです

ほとんどの場合、ツールから始めましょう。ログはあなたに何が残っているかを正確に教えてくれます。

公開する前に確認してください。

  1. bun install && bun run build (またはスクリプト)。 verify Android:
  2. Android: cd android && ./gradlew clean build testiOS with CocoaPods:
  3. (新しいレイアウト プラグインを使用する場合) cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS iOS with SPM: xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
  4. , そしてスキームをビルドしてください。 swift package resolve新しい __CAPGO_KEEP_0__ 8 アプリにプラグインをインストールし (SPM がデフォルトで使用されます)、CocoaPods アプリにもインストールしてください。実機ですべての公開メソッドを呼び出してください。
  5. Install the plugin in a fresh Capacitor 8 app (bunx cap add ios (or your script).
  6. Run bunx cap doctor テストアプリ内で

Release

  • 新しいメジャーにアップグレードします。 8.0.0Raising minSdk と iOS の最低バージョンを上げることは、消費者にとって破壊的な変更です。
  • 短い BREAKING.md または変更履歴のエントリを書きます: 新しい依存範囲、minSdk 24、iOS 15、Java 21 のビルド、API の動作変更など。
  • Keep a 7.x branch if you still ship fixes for Capacitor 7 users, and publish those under a dist-tag such as latest-7.
  • Capacitor プラグインを Capacitor 8 にアップグレードする

Capgo のプラグインを確認できます。 @capgo/* Capacitor のプラグインを確認できます。 プラグインディレクトリ.

トラブルシューティング

invalid source release: 21. JDK 17 または古いバージョンの JDK 17 で Gradle が実行されている場合、Android Studio Otter に含まれる JDK 21 を使用してください。 JAVA_HOME CI で実行します。

Unsupported class file major version 65. JDK 21 で古い Gradle wrapper を実行すると、Java 21 のクラスファイルを読むことができません。8.14.3 で wrapper を再生成してください。

Namespace not specified. AGP 8 以降では namespace = "..." プラグインの android ブロック内で package 属性は古いプラグインでは AndroidManifest.xml属性が含まれていました。Gradle に移し、manifest から削除してください。 package Kotlin

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Kotlin jvmTarget 一致しません。 targetCompatibility両方を21または17に設定してください。

AGP 9を含むエラー proguard-android.txt AGP 9. fix __CAPGO_KEEP_0__ AGP 9でプラグインビルドエラー proguard-android-optimize.txt SPM: AGP 9 で Capacitor プラグインのビルドエラーを修正.

SPM: product 'Capacitor' required by package ... not found. Play Console Package.swift AGP 9を使用しているアプリがあります。両方のバージョンを使用して、プラグインを両方のアプリでビルドできるようにします。詳細は from: "8.0.0" against https://github.com/ionic-team/capacitor-swift-pm.git.

SPM: Capacitor プラグインをCapacitor 8にアップグレードする .so ネイティブ ライブラリを配布している場合、16 KB アライメントで再構築してください。 Android 16 KB ページ サイズとCapacitor プラグインを参照してください。.

Capacitor 8にアップグレードしたプラグインの次のステップはCapacitor 9に準備することです。 Preparing for Capacitor 9 Capacitor 8 にアップグレードするためのプラグインチームの変更リストは、8 の Capacitor を破壊しない限り、現在実行できる変更です。

Live updates for Capacitor apps

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

最新のブログ記事

Capgoは、プロフェッショナルなモバイルアプリを作成するために必要な最良の洞察を提供します。

Capacitorアプリで2方向のコミュニケーション
開発 モバイル +1
2025年4月26日

Capacitorアプリで2方向のコミュニケーション

5つのOTA更新ミスを避ける
開発 セキュリティ +1
2025年4月13日

5つのOTAアップデートのミスを避ける

モバイルアプリのライブアップデートのセキュリティベストプラクティス5つ
開発 モバイル +1
2025年1月14日

モバイルアプリのライブアップデートのセキュリティベストプラクティス5つ

__CAPGO_KEEP_0__のすべての記事を見る