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

Capacitor 플러그인을 Capacitor 8로 업그레이드하려면 다음을 실행하세요 bunx @capacitor/plugin-migration-v7-to-v8@latest 플러그인 루트에서 실행한 후 diff를 검토하세요: Capacitor 의존성이 8.x로 이동하고, Android는 SDK 36을 타겟으로 minSdk 24, AGP 8.13, Gradle 8.14.3을 사용하며, Kotlin은 2.2.20으로 compilerOptions, iOS는 15.0 배포 타겟으로 capacitor-swift-pm 8. 두 플랫폼에서 예제 앱을 빌드하고 새로운 major 버전을 게시하여 마무리하세요.

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

플러그인 개발자에게 변경되는 사항

로컬 및 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 deployment target을 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로 업그레이드된 경우, 마이그레이션 후 포맷 및 린트 스크립트를 실행하세요. 포맷 변경 사항이 클 수 있으므로 기능 변경과 별도로 커밋하세요.

옵션 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 값을 제어할 수 있어, 앱에서 “version 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 synthetic view 접근을 위한 view binding도 지원합니다.

6. iOS 배포 대상(deployment target)

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 range를 지정하면 SPM이 해당 버전을 기준으로 플러그인을 resolve할 수 있습니다.

이전 Xcode 프로젝트 레이아웃을 사용하는 플러그인은 프로젝트의 deployment target도 함께 높여야 합니다. 빌드 설정 그리고 ios/Podfile (platform :ios, '15.0').

플러그인에 Package.swift 이 아직 없다면, 다음으로 진행하세요. Capacitor 8로 생성된 앱은 기본적으로 SPM을 사용하며, “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 에이전트에게 플러그인 업그레이드를 요청하세요. 스킬은 공식 도구를 실행한 후, 도구가 로그에 기록한 건너뛴 단계를 처리합니다. 팀원의 PR을 검토하듯 diff를 검토하세요.

어떤 접근법을 사용할지

거의 모든 경우 도구를 먼저 시작하세요. 로그가 남은 작업이 무엇인지 정확히 알려줍니다.

게시 전 검증

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 change입니다.
• 짧은 BREAKING.md 또는 changelog 항목: 새 peer range, minSdk 24, iOS 15, 빌드용 Java 21, API 동작 변경 사항.
• 브랜치를 유지하세요: 7.x Capacitor 7 사용자에게 계속 수정 사항을 배포한다면, 해당 수정 사항을 다음과 같은 dist-tag로 게시하세요: latest-7.
• README의 설치 섹션과 호환성 테이블을 업데이트하세요.

Capgo는 이 사이클에서 다수의 플러그인을 유지 관리하며, 각 @capgo/* major는 Capacitor major를 따라갑니다. 다음에서 확인할 수 있습니다: 플러그인 디렉토리.

문제 해결

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 사용자에게 영향을 주지 않고 플러그인 팀이 지금 바로 적용할 수 있는 변경 사항을 나열합니다.