Capacitor 플러그인을 Capacitor 8로 업그레이드하는 방법

Capacitor 플러그인을 Capacitor 8으로 업그레이드하려면 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 compilerOptionsiOS는 15.0 배포 대상으로 업그레이드됩니다. capacitor-swift-pm 8. 예제 앱을 양쪽 플랫폼에서 빌드하고 새로운 메이저 버전을 배포하세요.

이 문서는 플러그인 유지보수자들을 위한 것입니다. 앱 팀은 이 문서를 따르세요. Capacitor Capacitor을 Capacitor Capacitor 8으로 업그레이드하는 방법.

플러그인 개발자에게 어떤 변화가 있는가

Platform tooling you need locally and in CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) or later, and a JDK 21.

옵션 1: 공식 마이그레이션 도구를 실행하십시오

Option 1: 공식 마이그레이션 도구를 실행합니다.

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

도구:

• 업데이트는 Capacitor 의존성을 업데이트하고 패키지 버전을 설정합니다. 8.0.0.
• __CAPGO_KEEP_0__ 의존성을 업데이트하고 패키지 버전을 설정합니다. @capacitor/docgenCapacitor 8으로 플러그인을 업그레이드하는 방법 @types/node, Rollup, TypeScript, @ionic/prettier-config, plus prettier-plugin-java).
• , plus node_modules/@capacitor 삭제 package-lock.json그리고 npm installCapacitor 8로 업그레이드하는 경우 Bun을 사용하면 경고 메시지가 나타나며 실행이 중단됩니다. Run bun install 그리고 bun.lock.
• 삭제 ./gradlew wrapper --gradle-version 8.14.3.
• 그런 다음 실행 build.gradle. SDK을 사용하는 경우, 그 단계는 경고 메시지와 함께 실패합니다. SDK을 실행한 후에 kotlinOptions to compilerOptions.
• 14.0에서 15.0으로 podspec 배포 대상 버전을 높이고, Package.swift 설정 .iOS(.v15) 그리고 from: "8.0.0" 위치 capacitor-swift-pm.

대신 Unable to find "..." in <file>. Try updating it manually위치

위치

위치

위치 위치.

위치

{
  "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. 안드로이드 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 패턴을 유지하세요. 호스트 앱이 값을 제어할 수 있게 해서 앱에서 '버전 36'과 같은 컴파일 오류를 피할 수 있습니다. variables.gradle 이 패턴은 속성에만 적용됩니다. 메소드 호출은 그대로 유지되고

The = 사용하지 않는 라이브러리는 업그레이드하지 마세요. Capgo 8 기본값은 다음과 같습니다: mavenCentral() 다른 공식 목록의 항목: maven { url = "..." } needs the =.

Firebase나 다른 Google 서비스를 사용하는 플러그인이 있다면

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.

이러한 오류를 피하기 위해

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
    }
}

cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

호스트 앱이 값을 제어할 수 있게 해서 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 밖으로 kotlinOptionsKotlin 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은 "일관된 JVM-대상 호환성" 오류로 중단됩니다. 여전히 적용하려면 kotlin-android-extensions제거하고 kotlin-parcelize 사용 @Parcelize for

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:iOS 앱의 생성된 CapApp-SPM 패키지 핀 capacitor-swift-pm 해당 앱이 설치된 exact 버전으로, 그리고 범위는 SPM이 플러그인을 해당 버전으로 해결하도록 해줍니다. @capacitor/ios Xcode 프로젝트 레이아웃이 이전 버전인 플러그인도 프로젝트의

빌드 설정 및 그리고 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 Swift Package Manager로 Capacitor 플러그인을 업그레이드하는 방법.

How to Migrate a __CAPGO_KEEP_0__ Plugin to Swift Package Manager

The open Capgo 기술력 include capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades include capacitor-plugin-spm-supportmulti-version jumps에 대한 지원을 포함하고, bunx skills add Cap-go/capgo-skills 와 함께 설치하고,

플러그인을 업그레이드하도록 agent에게 요청하세요.

대부분의 경우 도구에서 시작하세요. 그 로그는 정확히 무엇이 남았는지 알려줍니다.

배포하기 전에 확인하세요.

1. bun install && bun run build (또는 verify 스크립트).
2. 안드로이드: cd android && ./gradlew clean build test. JDK 21로 빌드하세요.
3. iOS with CocoaPods: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (새로운 레이아웃 플러그인은 xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS with SPM: swift package resolve, 그리고 빌드 스키마를 호출하세요.
5. 새로운 8 버전의 Capacitor 앱에 플러그인을 설치하세요.bunx cap add ios iOS with CocoaPods: (새로운 레이아웃 플러그인은 iOS with SPM: , 그리고 빌드 스키마를 호출하세요.
6. 실행 bunx cap doctor 테스트 앱에서

릴리스

• 새 메이저 버전으로 업그레이드합니다 (도구는 8.0.0). minSdk 및 iOS floor를 높이는 것은 소비자에게 깨끗한 변경입니다.
• 짧은 BREAKING.md 또는 변경 로그 항목: 새로운 peer 범위, minSdk 24, iOS 15, Java 21 빌드, API 동작 변경 사항.
• 업그레이드 7.x Capacitor를 업데이트하여 README 설치 섹션과 호환성 테이블을 업데이트합니다. latest-7.
• __CAPGO_KEEP_0__는 이 사이클에 큰 플러그인 세트를 유지하며, 각 메이저는 __CAPGO_KEEP_0__ 메이저를 추적합니다. 그들을浏览할 수 있습니다.

Capgo @capgo/* Capacitor 플러그인 디렉토리.

문제 해결

invalid source release: 21. Gradle은 JDK 17 또는 이전 버전에서 실행 중입니다. Android Studio Otter와 함께 제공되는 JDK 21을 사용하십시오. JAVA_HOME CI에서 업그레이드합니다.

Unsupported class file major version 65. CI에서 JDK 21을 실행하는 경우, 이전 버전의 Gradle wrapper가 Java 21 클래스 파일을 읽을 수 없다는 문제가 발생합니다. wrapper를 8.14.3 버전으로 다시 생성하십시오.

Namespace not specified. AGP 8 이상 버전은 namespace = "..." 플러그인의 android 속성은 package 속성 AndroidManifest.xml속성 package 속성

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). 속성 jvmTarget 일치하지 않습니다. targetCompatibility21 또는 17으로 모두 설정하세요.

AGP 9과 관련된 오류 proguard-android.txt AGP 9. AGP 9을 사용하여 플러그인 빌드를 위해 Switch를 사용하세요. 자세한 내용은 proguard-android-optimize.txt fix __CAPGO_KEEP_0__ 플러그인 빌드 오류 AGP 9 AGP 9 버전으로 Capacitor 플러그인 빌드 오류를 수정합니다..

SPM: product 'Capacitor' required by package ... not found. Your Package.swift AGP 9을 사용하여 플러그인 빌드를 위해 Switch를 사용하세요. from: "8.0.0" against https://github.com/ionic-team/capacitor-swift-pm.git.

AGP 9을 사용하여 플러그인 빌드를 위해 Switch를 사용하세요. 8 버전으로 업그레이드하는 Capacitor 플러그인 .so 네이티브 라이브러리를 포함하는 플러그인은 16 KB 정렬로 다시 빌드해야 합니다. Android 16 KB 페이지 크기 및 Capacitor 플러그인.

8 버전의 플러그인이 준비되면 다음 단계는 9 버전을 준비하는 것입니다. Capacitor 9 버전 준비 Capacitor 8 버전 사용자에게 영향을 주지 않는 변경 사항을 지금부터 플러그인 팀이 할 수 있는 변경 사항입니다.