Capacitor 안드로이드 문제 해결: 일반적인 오류와 수정

대부분의 Capacitor 안드로이드 빌드 실패는 도구-chain 불일치로 인해 발생합니다: 잘못된 JDK, 오래된 Gradle wrapper, 또는 SDK 수준이 의존성 요구 사항과 일치하지 않는 경우입니다. Capacitor 8 버전을 사용하는 경우 JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk 및 targetSdk 36, 그리고 minSdk 24를 사용한 다음 bunx cap sync android 그리고 마지막 Gradle 오류를 읽지 마세요.

이 안내서에는 Capacitor 프로젝트에서 가장 많이 발생하는 안드로이드 오류가 나열되어 있습니다. 그룹화는 Gradle 설정, 의존성 해결, 컴파일, 설치, 및 런타임입니다. iOS에 대한 자세한 내용은 Capacitor iOS 문제 해결 안내서를 참조하세요. Capacitor iOS 문제 해결 가이드.

그런 다음 __CAPGO_KEEP_0__ 버전의 예상값을 확인하세요:

bunx cap doctor              # core, CLI and android must share the same major
node -v                      # 22+ for Capacitor 8
java -version                # 21 for Capacitor 8
bun run build && bunx cap sync android
cd android && ./gradlew assembleDebug --stacktrace

그런 다음 Capacitor 버전의 예상값을 확인하세요.

업그레이드 중이신가요? Capacitor 앱을 Capacitor 8으로 업그레이드하는 방법 먼저

Gradle 및 JDK 오류

error: invalid source release: 21

Gradle은 JDK 17 또는 이전 버전에서 실행되지만 @capacitor/android 8은 Java 21과 호환됩니다. Android Studio에서: 설정 > 빌드, 실행, 배포 > 빌드 도구 > Gradle > Gradle JDK 및 bundled JDK 21 (JetBrains Runtime)을 선택합니다. 명령줄 및 CI에서:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # macOS

# GitHub Actions
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'

Unsupported class file major version 65

반대 문제: JDK 21을 실행하여 Gradle wrapper가 Java 21 클래스 파일을 읽을 수 없는 너무 오래된 버전입니다. wrapper를 업데이트하십시오:

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

Minimum supported Gradle version is 8.13. Current version is 8.11.1

AGP가 업데이트되었지만 wrapper가 업데이트되지 않았습니다. 각 AGP 버전에는 최소 Gradle 버전이 있으며 AGP 8.13은 Gradle 8.13 이상이 필요합니다. wrapper를 8.14.3으로 설정하십시오.

The project is using an incompatible version (AGP 8.13.0) of the Android Gradle plugin

프로젝트의 AGP 버전이 Android Studio 버전보다 높습니다. Android Studio Otter 또는 새로운 버전을 설치하십시오.

SDK location not found

Gradle은 Android SDK을 찾을 수 없습니다. Android Studio에서 프로젝트를 한 번 열어보십시오 (그것은 android/local.properties), 또는 변수를 설정하세요:

export ANDROID_HOME="$HOME/Library/Android/sdk"

하지 마십시오. local.properties. 이에는 머신-특정 경로가 포함되어 있습니다.

Could not resolve all files for configuration / Could not GET https://dl.google.com/...

네트워크 또는 저장소 문제입니다. ~/.gradle/gradle.properties확인하세요. google() 그리고 mavenCentral() 가 있습니다. repositories그리고 --refresh-dependencies를 확인하고

Java heap space or GC overhead limit exceeded

또는 android/gradle.properties:

org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8

Capacitor 템플릿은 -Xmx1536m앱이 많은 플러그인을 사용하는 경우, 이는 꽉 찬 앱입니다.

의존성 및 SDK 수준 오류

Dependency 'androidx.core:core:1.17.0' requires libraries and applications that depend on it to compile against version 36 or later

compileSdkVersion AndroidX 라이브러리가 필요로 하는 최소 버전보다 낮습니다. 36으로 설정하십시오. variables.gradle. 에서 오류가 플러그인 모듈을 이름으로 지칭한다면, 플러그인이 오래된 값을 고정하고 있습니다. 업그레이드하거나 .

Manifest merger failed : uses-sdk:minSdkVersion 23 cannot be smaller than version 24 declared in library

의 minSdkVersion 는 플러그인의 의존성보다 낮습니다. Capacitor 8는 24이 필요합니다. variables.gradle.

Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules

에서 높여 주십시오. kotlin-stdlib-jdk8일반적으로 하나의 플러그인이 오래된 kotlin_version = '2.2.20' 를 pulls로 인해 발생합니다. 하나의 Kotlin 버전으로 일치시키십시오. build.gradle 에서 rootProject.ext(플러그인이 via로 읽습니다.)를 설정하고 Kotlin 1.x를 pin하는 플러그인을 업그레이드하십시오. 필요하다면 BOM을 강제로 설정하십시오. android/app/build.gradle:

dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.2.20"))
}

Duplicate class com.google.android.gms... 또는 com.google.firebase...

두 플러그인은 Play Services 또는 Firebase의 다른 버전을 가져옵니다. 대부분의 Capacitor 플러그인은 버전을 읽습니다. variables.gradle 두 플러그인은 Play Services 또는 Firebase의 다른 버전을 제공합니다. 대부분의 __CAPGO_KEEP_0__ 플러그인은 버전을 읽어오기 때문에 firebaseMessagingVersion(예를 들어)

Project with path ':capacitor-xxx' could not be found in project ':app'

android/capacitor.settings.gradle and android/app/capacitor.build.gradle 그리고 bunx cap sync android, then 최신 버전이 아닙니다. 모두 생성됩니다. Run.

그런 다음

Namespace not specified. Specify a namespace in the module's build file

파일 > Gradle 파일과 Sync Project namespace 컴파일 오류 package 그들의 AndroidManifest.xml. 플러그인을 업그레이드하세요. 릴리스가 없다면, 패치를 적용하세요. android/build.gradle:

android {
    namespace = "com.example.plugin"
}

그것을 제거하세요 package manifest 속성

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17) jvm target compatibility should be set to the same Java version

Kotlin 모듈 (당신의 모듈 또는 플러그인의 모듈)이 Java 모듈과 다른 경우가 있습니다. jvmTarget Java보다 더 빠르다 targetCompatibilityIn Kotlin 2.x, set it with compilerOptions:

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21
    }
}

구성 kotlinOptions {} block은 Kotlin 2.2에서 오류입니다. 따라서 여전히 이 블록을 사용하는 플러그인은 업데이트 또는 패치를 적용해야 합니다.

오류에 관한 proguard-android.txt AGP 9

AGP 9로 이미 이동한 경우, AGP 9을 참조하는 플러그인이 실패합니다. 이 문제를 해결하려면 getDefaultProguardFile('proguard-android.txt') 에러가 발생했습니다. 해결 방법은 proguard-android-optimize.txt. 전체 세부 정보는 AGP 9 버전으로 Capacitor 플러그인 빌드 오류를 해결하세요.AGP 8.13은 Capacitor 8 앱에 대해 테스트된 버전입니다.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8은 레이아웃 이름을 capacitor_bridge_layout_main. __CAPGO_KEEP_0__ 앱의 참조를 업데이트하거나 커스텀 프래그먼트를 업데이트하세요. MainActivity Android 12 이상을 대상으로 하는 앱은

android:exported needs to be explicitly specified for element <activity#...>

를 설정해야 합니다. android:exported (또는 android:exported="true" (or false설치 오류

__CAPGO_KEEP_0__ 앱과 동일한 ID지만 다른 서명 키를 가진 앱이 설치되어 있습니다. 일반적으로 Play Store에서 릴리즈 빌드를 설치한 경우 debug 빌드를 먼저 제거하세요.

INSTALL_FAILED_UPDATE_INCOMPATIBLE

__CAPGO_KEEP_0__

adb uninstall com.example.app

Android Studio에서 장치 목록이 표시되지 않거나 adb devices shows unauthorized

개발자 옵션을 활성화하고 USB 디버깅을 허용한 후 전화에서 RSA 프롬프트를 수락하고 데이터 전송 가능한 케이블을 사용하세요. adb kill-server && adb start-server 대부분의 멈춰있는 상태를 고쳐줍니다.

Play Console: "앱이 16 KB 메모리 페이지 크기를 지원하지 않습니다"

앱에 포함된 네이티브 .so 라이브러리가 16 KB로 맞춰져 있지 않습니다. 해당 라이브러리를 제공하는 플러그인을 찾고 업그레이드하세요. Android 16 KB 페이지 크기와 Capacitor 플러그인.

릴리스 빌드에 대한 서명

키스토어 설정이 누락되거나 잘못되면 Keystore file not found 또는 Failed to read key. Our 안드로이드 키스토어 생성기 키스토어와 Gradle 서명 구성이 생성됩니다. 키스토어는 Git에서 제외하고 백업하세요. 키스토어가 사라지면 앱을 업데이트하려면 Play App Signing을 사용해야 합니다.

런타임 오류

"X" plugin is not implemented on android

1. 플러그인은 package.json 그리고 bunx cap sync android 설치 후
2. 실행했습니다.Android Studio는 Gradle을 동기화했습니다. ().
3. 파일 > Gradle 파일과 프로젝트를 동기화 android/capacitor.settings.gradle.
4. Capacitor Android 빌드 오류를 해결하는 방법 플러그인 버전이 Capacitor의 주요 버전과 일치합니다. Capacitor 7 플러그인은 컴파일 할 수 있지만 다른 방식으로 등록될 수 있습니다.
5. 플러그인 버전은

와 일치합니다. __CAPGO_KEEP_0__ 메이저 버전의 플러그인은 컴파일이 가능하지만 다른 방식으로 등록될 수 있습니다. __CAPGO_KEEP_1__ 7 플러그인은 컴파일이 가능하지만 다른 방식으로 등록될 수 있습니다.

열기 chrome://inspect 그리고 WebView 콘솔을 확인하세요. 일반적인 원인:

• net::ERR_CLEARTEXT_NOT_PERMITTED 실시간 리로드 중인 경우: Android는 평범한 HTTP를 차단합니다. 개발용으로만, __CAPGO_KEEP_0__ 설정에서 server.cleartext: true Capacitor 설정에서, 제거 server.url 을 삭제하세요.
• 개발 서버에 접근할 수 없습니다: 0.0.0.0에 바인드하세요. LAN IP를 사용하세요, 전화기와 컴퓨터가 같은 네트워크에 있게 하세요, 또는 bunx cap run android --forwardPorts 5173:5173.
• 을 사용하세요.Capacitor 체크 android.minWebViewVersion : __CAPGO_KEEP_0__는 (기본값 60)과 오래된 WebView에서 에러를 로깅합니다. WebView 버전 체커 플러그인 웹뷰의 업데이트를 감지하고 사용자에게 업데이트를 권장할 수 있습니다.
• 빌드 대상 버전이 너무 최신입니다. 장치의 WebView를 위한 것입니다. 빌더의 목표를 낮추거나 폴리필을 추가하세요.
• 오류 webDir: 확인하세요 android/app/src/main/assets/public contains index.html.
• 구성된 live update 패키지Capgo의 경우 Capgo이 호출하지 않는 번들 notifyAppReady() 자동으로 시간 초과 후 롤백됩니다. 자세한 내용은 Capacitor Android 빌드 오류 해결.

화면 하단에 있는 상태栏 또는 네비게이션 바 뒤에 있는 콘텐츠

애플리케이션은 SDK 35 이상 버전에서 안드로이드 15 에서 edge-to-edge로 표시되며, 안드로이드 16 버전에서는 SDK 36 버전을 대상으로 한 애플리케이션에 대한 opt-out 옵션을 제거했습니다. Capacitor 8 버전은 제거되었습니다. adjustMarginsForEdgeToEdge. Android 시스템 바의 플러그인 설정과 CSS를 사용하여 인셋을 처리하십시오.

plugins: {
  SystemBars: {
    insetsHandling: 'css',
    initialViewportFitValueHint: 'cover',
  },
},

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

With insetsHandling: 'css', Capacitor 또한 CSS 변수를 주입하여, --safe-area-inset-* 오래된 WebView에서 env() WebView는 회전 또는 크기 조절 시 재로드됩니다.

액티비티가 다시 생성되는 중입니다.

메인 액티비티에 android:configChanges (__CAPGO_KEEP_0__ 8에서 추가됨) density (added in Capacitor 8)과 함께 orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

모바일 장치의 방향 잠금은 태블릿에서 무시됩니다.

Android 16 이상에서, 대형 화면은 SDK 36을 대상으로 하는 앱에서 방향锁을 무시합니다. 임시 매니페스트 옵트아웃이 존재합니다.android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY대형 화면을 위한 양쪽 방향 설계를 고려하십시오.

오류가 표시되지 않을 때 디버깅하는 방법

1. 첫 번째 오류를 읽어보세요. Run ./gradlew assembleDebug --stacktrace 스크롤을 위로 올려서 첫 번째 에러 메시지를 확인하세요. FAILURE or What went wrong.
2. 버전 충돌을 확인하세요: Logcat ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat Capacitor native 앱 오류에 대한 로그를 필터링하여 패키지에 적용합니다. Capacitor 로그 플러그인은 native 앱 오류와 관련된 로그를 호출합니다. Capacitor tag.
4. Check the dependency tree for version conflicts:
5. Isolate 새로운 프로젝트와 의심스러운 플러그인만을 사용하여 bun create @capacitor/app 문제를 격리하세요.

더 많은 도구는 __CAPGO_KEEP_0__ 앱을 디버깅하는 최종 가이드에서 다룹니다. ultimate debugging guide for Capacitor apps and . CI 머신이 문제가 아니라 Capacitor에 문제가 있다면code 빌드 Capgo 빌드 안드로이드 빌드를 올바른 JDK와 SDK이 이미 설치된 상태로 실행합니다.