Capacitor Android 트러블슈팅: 주요 오류 및 해결 방법

대부분의 Capacitor Android 빌드 실패는 툴체인 불일치에서 비롯됩니다. 잘못된 JDK, 오래된 Gradle 래퍼, 또는 의존성이 요구하는 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 프로젝트에서 가장 자주 발생하는 Android 오류를 발생 위치에 따라 그룹화하여 나열합니다: Gradle 설정, 의존성 해결, 컴파일, 설치, 런타임. iOS의 경우 다음을 참조하세요 Capacitor iOS 트러블슈팅 가이드.

빠른 문제 진단 체크리스트

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에서: Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK 번들된 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

역방향 문제: Java 21 클래스 파일을 읽을 수 없는 구버전 Gradle wrapper를 JDK 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

Android Studio 버전이 프로젝트의 AGP보다 오래되었습니다. 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 또는 GC overhead limit exceeded

의 Gradle 메모리를 늘리세요 android/gradle.properties:

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

Capacitor 템플릿에는 다음이 포함되어 있습니다 -Xmx1536m, 이는 플러그인이 많은 앱에는 부족합니다.

Dependency 및 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. 오류에 플러그인 모듈 이름이 표시되면, 해당 플러그인이 오래된 값을 하드코딩하고 있습니다. 업그레이드하거나 build.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 표준 라이브러리 아티팩트가 존재합니다. 보통 플러그인 중 하나가 오래된 버전을 가져오기 때문에 발생합니다. kotlin-stdlib-jdk8Kotlin 버전을 하나로 통일하세요. 다음 설정을 지정하세요: kotlin_version = '2.2.20' 루트 build.gradle (플러그인은 이를 통해 rootProject.ext을(를) 읽습니다)을(를) 설정하고, Kotlin 1.x를 고정하는 플러그인을 업그레이드하세요. 필요 시 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 (예를 들어 firebaseMessagingVersion에서 읽으므로, 모든 플러그인이 동일한 값을 사용하도록 해당 파일에 한 번만 정의하세요.

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

android/capacitor.settings.gradle 및 android/app/capacitor.build.gradle 이전 버전입니다. 둘 다 생성된 파일입니다. 다음을 실행하세요 bunx cap sync android, 그 다음 File > Sync Project with Gradle Files.

컴파일 오류

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

AGP 8+에는 namespace 모든 Android 모듈에서 발생합니다. 오래된 플러그인은 다음만 선언합니다 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 모듈(내 프로젝트 또는 플러그인)의 버전이 다릅니다 jvmTarget Java보다 targetCompatibility. Kotlin 2.x에서는 이렇게 설정합니다 compilerOptions:

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

기존 kotlinOptions {} 블록은 Kotlin 2.2에서 오류가 발생하므로, 이를 사용하는 플러그인은 업데이트나 패치가 필요합니다.

에 대한 오류 proguard-android.txt AGP 9 사용 시

AGP 9로 마이그레이션을 완료했다면, 다음을 참조하는 플러그인은 getDefaultProguardFile('proguard-android.txt') 실패합니다. 해결 방법은 proguard-android-optimize.txt입니다. 자세한 내용은 AGP 9에서 Capacitor 플러그인 빌드 에러 해결하기에서 확인하세요. Capacitor 8 앱의 경우 AGP 8.13이 테스트된 버전입니다.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8에서 레이아웃 이름을 다음으로 변경했습니다 capacitor_bridge_layout_main. 참조를 업데이트하세요 MainActivity 또는 커스텀 프래그먼트.

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

Android 12+를 타겟으로 하는 앱은 android:exported 의 모든 activity, service, receiver에 intent filter가 있는 경우 설정해야 합니다. 추가하세요 android:exported="true" (또는 false)를 manifest에 추가하세요. 해당 요소가 플러그인 manifest에서 온 경우 플러그인을 업그레이드하거나 패치하세요.

설치 오류

INSTALL_FAILED_UPDATE_INCOMPATIBLE

같은 ID를 가지지만 서명 키가 다른 앱이 설치되어 있습니다. 보통 Play Store의 release 빌드와 디버그 빌드 간 충돌입니다. 먼저 삭제하세요:

adb uninstall com.example.app

Android Studio 또는 adb devices 에 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. 저희 Android 키스토어 생성기 키스토어와 Gradle 서명 설정을 생성합니다. 키스토어는 git에 올리지 말고 반드시 백업하세요. 키스토어를 분실하면 Play App Signing을 사용하지 않는 한 앱을 업데이트할 수 없습니다.

런타임 오류

"X" plugin is not implemented on android

1. 플러그인이 package.json 그리고 실행한 bunx cap sync android 설치 후 ...
2. Android Studio가 동기화 후 Gradle을 동기화했습니다 (File > Sync Project with Gradle Files).
3. 플러그인이 다음에 표시됩니다 android/capacitor.settings.gradle.
4. 플러그인 버전이 Capacitor major와 일치합니다. Capacitor 7 플러그인은 컴파일은 되지만 등록 방식이 다를 수 있습니다.
5. 오래된 APK를 실행하고 있지 않습니다. 삭제 후 다시 설치하세요.

빈 흰색 화면

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

• net::ERR_CLEARTEXT_NOT_PERMITTED live reload 중: Android는 일반 HTTP를 차단합니다. 개발 전용으로 다음을 설정하세요 server.cleartext: true Capacitor 설정에서, 그리고 제거하세요 server.url 릴리스 전에.
• Dev server에 연결할 수 없음: 여기에 바인딩하세요 0.0.0.0, LAN IP를 사용하거나, 휴대폰과 컴퓨터를 같은 네트워크에 두거나, 다음 명령으로 포트를 포워딩하세요 bunx cap run android --forwardPorts 5173:5173.
• 오래된 Android System WebView: Capacitor가 확인합니다 android.minWebViewVersion (기본값 60)이며, 오래된 WebView에서는 오류를 기록합니다. WebView를 업데이트하지 않는 기기는 최신 JavaScript에서도 실패할 수 있습니다. WebView 버전 확인 플러그인 오래된 WebView를 감지하고 사용자에게 업데이트하도록 안내할 수 있습니다.
• 빌드 타겟 버전이 너무 높음 기기 WebView에 맞게. 번들러 타겟을 낮추거나 폴리필을 추가하세요.
• 잘못된 webDir: 확인 android/app/src/main/assets/public 포함 index.html.
• 손상된 live update 번들: Capgo 사용 시, 호출하지 않는 번들은 notifyAppReady() 타임아웃 후 자동으로 롤백됩니다. 관련 내용은 updater 문서.

상태 바 또는 내비게이션 바 뒤의 콘텐츠

SDK 35 이상을 타겟팅하는 앱은 Android 15에서 엣지 투 엣지로 렌더링되며, Android 16에서는 SDK 36을 타겟팅하는 앱의 옵트아웃이 제거되었습니다. Capacitor 8에서 adjustMarginsForEdgeToEdgeSystem Bars 플러그인 설정과 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);
}

사용하면 insetsHandling: 'css', Capacitor 은(는) 또한 --safe-area-inset-* CSS 변수를 주입하여, 구형 WebView에서 도움이 됩니다. env() 0건 보고됩니다.

WebView가 회전 또는 리사이즈 시 재로드됩니다

액티비티가 재생성되고 있습니다. 확인하세요 android:configChanges 메인 액티비티에 포함됩니다 density ( Capacitor 8에 추가됨) 및 orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

태블릿에서 방향 잠금 무시

Android 16 이상에서 대형 화면은 SDK 36을 타겟팅하는 앱의 방향 잠금을 무시합니다. 임시 매니페스트 옵트아웃이 존재합니다(android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY) 하지만 Android 17에서는 제거됩니다. 대형 화면에서는 두 방향 모두를 고려하여 디자인하세요.

목록에 없는 오류를 디버깅하는 방법

1. 첫 번째 오류를 읽어보세요. 실행 ./gradlew assembleDebug --stacktrace 그리고 첫 번째 오류로 스크롤을 올려보세요 FAILURE 또는 What went wrong.
2. 의존성 트리를 확인하세요 버전 충돌을 확인하려면: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat 네이티브 크래시를 확인하기 위해 패키지로 필터링하세요. Capacitor은 다음 태그로 플러그인 호출을 기록합니다. Capacitor 태그.
4. chrome://inspect JavaScript 오류를 확인하려면.
5. 격리하기 새로운 bun create @capacitor/app 프로젝트와 의심되는 플러그인만 포함하여.

더 많은 도구는 다음에서 다룹니다. Capacitor 앱 디버깅을 위한 최종 가이드 및 Capacitor에서 Android 빌드 오류 해결 방법. CI 머신에 문제가 있는 경우, code의 문제가 아니라면, Capgo 빌드 적절한 JDK와 SDK가 이미 설치된 상태로 Android 빌드를 실행합니다.