만약 Capacitor 컨텍스트: Live updates 제품 페이지. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 live-update.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지하십시오. 메시지 키 `live_update_platform_capacitor_title` (Live Update Platform Capacitor Title).
AGP 9로 업그레이드한 후 플러그인이 실패하기 시작했다면, Android Gradle Plugin 9 (AGP 9)에서 발생하는 작은 nhưng 중요한 Gradle 구성 문제를 만난 것입니다.
- Capacitor plugin build error AGP 9
- __CAPGO_KEEP_0__ 플러그인 빌드 오류 AGP 9
proguard-android.txtAndroid Gradle Plugin 9 플러그인 빌드 실패- 찾을 수 없음
getDefaultProguardFileAGP 9 - 오류입니다. Capacitor AGP 업그레이드 후 안드로이드 빌드 실패
The short version:
proguard-android.txtis no longer the safe default baseline to reference in AGP 9 plugin builds.- Switch to
proguard-android-optimize.txt. - Rebuild and verify.
The longer version matters too, especially if you maintain many plugins or large Capacitor workspaces. In this article we cover:
- Android와 AGP가 빌드 chain에서 어떤 역할을 하는가
- What Capacitor is and how plugin builds work
- Capgo는 무엇이며 플러그인 빌드가 어떻게 작동하는가 Capgo Capgo는 무엇이며 플러그인 빌드가 어떻게 작동하는가
- Android와 AGP가 빌드 chain에서 어떤 역할을 하는가
- Capgo는 무엇이며 플러그인 빌드가 어떻게 작동하는가
안드로이드는 이 상황에서 무엇인가요?
안드로이드 is both an operating system and a build ecosystem. When you ship a Capacitor app or plugin on Android, your project goes through:
- Gradle 빌드 시스템으로 Gradle을 사용합니다.
- Android Gradle Plugin (AGP) 안드로이드 전용 Gradle 통합입니다.
- The Android SDK toolchain for packaging, shrinking, linting, and producing
.aar,.apk, 또는.aab출력을 생성합니다.
AGP 버전이 변경될 때, 기본값 및 내부 파일도 변경될 수 있습니다. AGP 8에서 작동하던 플러그인 구성이 AGP 9에서 실패할 수 있습니다. 만약 구성이 제거된 또는 deprecated baseline에 대한 참조를 포함하고 있다면.
What is Capacitor?
Capacitor iOS/Android 앱을 웹 code (TypeScript, JavaScript, HTML, CSS)으로 빌드하는 데 사용되는 크로스 플랫폼 런타임입니다.
Capacitor
- 웹层(UI 및 비즈니스 로직)
- Native shells (
ios/,android/) - JavaScript로 native 기능을 노출하는 플러그인
각 플러그인은 Android에서 native 빌드 구성이 있습니다. 이 경우 AGP는 각 플러그인이 포함하는 파일을 올바르게 파싱하고 컴파일해야 합니다. android/build.gradle 플러그인 Gradle 설정이 outdated일 경우, 웹 __CAPGO_KEEP_0__이 올바른 경우에도 앱 빌드가 실패할 수 있습니다.
If plugin Gradle settings are outdated, the whole app build can fail, even when your web code is correct.
What is Capgo?
Capgo는 Capgo 전달 및 운영에 대한 도구를 제공합니다. Capacitor
- 실시간 업데이트 웹 번들 변경
- 플러그인 생태계 및 네이티브 기능 패키지
- CI/CD-friendly update workflows for Capacitor teams
실시간 업데이트도 네이티브 빌드의 안정성은 협상할 수 없는 것입니다. 여전히 다음을 위해 깨끗한 안드로이드 빌드를 필요로 합니다:
- 앱 스토어 / 플레이 스토어 출시
- 네이티브 플러그인 업그레이드
- 플랫폼 SDK 이주
- 팀 온보딩 및 CI 신뢰도
그것은 왜 AGP 9 호환성 수정이 중요하다는 것을 의미합니다: 그것은 플러그인 층이 신뢰할 수 있게 유지되므로 배달 pipe라인이 예측 가능하도록 합니다.
AGP 9이 이전 플러그인 설정을 깨뜨리는 이유
많은 플러그인 템플릿은 역사적으로 다음과 같이 사용했습니다:
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
AGP 9 환경에서 이 레거시 베이스 라인 참조는 실패할 수 있습니다. 이는 이전 템플릿/설정에 의존하는 오래된 파일이 더 이상 보장되지 않기 때문입니다.
Gradle 오류가 Gradle 빌드 중에 발생하거나, 또는 assemble, lint, 또는 build 단계에서 발생할 수 있습니다. 이 오류는 일반적으로 ProGuard 베이스 라인 리소스가 누락되거나, 또는 기본 파일 참조가 유효하지 않음을 나타냅니다.
빠른 배경: ProGuard, R8, 및 베이스 라인 파일
- R8 Android 빌드에서 현대적인 code shrinker/optimizer입니다.
proguard-rules.pro프로젝트/플러그인에서 사용하는 custom keep 규칙입니다.getDefaultProguardFile(...)Android에서 제공하는 베이스 라인을 주입합니다.
참조할 때:
proguard-android.txt-> 레거시, 최소 베이스 라인proguard-android-optimize.txt-> 현재 환경에서 권장되는 기본값인 최적화된 베이스 라인
AGP 9 호환성을 위해 proguard-android-optimize.txt 는 실제적인 해결책입니다.
한 줄로 해결하는 방법입니다.
플러그인 및 앱 모듈 Gradle 파일을 업데이트하세요:
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
적어도 다음을 확인하세요:
android/build.gradle각 플러그인에서example-app/android/app/build.gradle플러그인 저장소에서- 새로운 플러그인 Gradle 구성이 생성되는 모든 제너레이터/템플릿 파일
한 플러그인의 마이그레이션 가이드
1. 이전 참조를 찾으세요.
rg -n "proguard-android\\.txt" android example-app
2. 이를 대체하세요.
perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g" \
android/build.gradle example-app/android/app/build.gradle
3. Bun와 확인하세요.
bun run verify:android
만약 플러그인이 완전한 검증 스크립트를 가지고 있다면, 다음 명령어를 실행하십시오:
bun run verify
모든 플러그인 저장소에 Batch 업데이트
만약 하나의 워크스페이스에서 많은 플러그인 저장소를 관리한다면, 자동화하십시오:
rg -l "proguard-android\\.txt" capacitor-* \
--glob '!**/node_modules/**' \
--glob '!**/.gradle/**' \
--glob '!**/build/**' \
| xargs perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g"
그 다음, 트래킹 중인 플러그인 소스 중 아직旧 파일을 사용하지 않는지 확인하십시오:
for d in capacitor-*; do
[ -d "$d/.git" ] || continue
git -C "$d" grep -n "proguard-android\\.txt" -- || true
done
일치하는 항목이 없으면, 트래킹 중인 플러그인 파일에서旧 기준 참조가 삭제된 것입니다.
Capgo 배포 상태
Capgo Capacitor 공식 플러그인 저장소 및 템플릿에 이 마이그레이션을 완료했습니다:
- 플러그인 안드로이드 모듈은 이제
proguard-android-optimize.txt - 플러그인 예제 안드로이드 앱도 업데이트되었습니다.
- 플러그인 스캐폴딩 템플릿도 업데이트되어 새 플러그인은 기본적으로 AGP 9-safe합니다.
이것은 CI에 도달하기 전에 AGP 9 업그레이드 실패의 일반적인 클래스를 방지합니다.
왜 오늘도 빌드가 통과하더라도 이것이 중요한 이유
만약에 다음과 같은 경우에는 즉시 실패를 확인하지 못할 수 있습니다:
- CI 캐시가 여전히 문제를 가린다.
- 프로젝트에 다양한 AGP 버전이 혼합되어 있다.
- 로컬 개발 시에 일부 모듈만 다시 빌드된다.
그러나 결국, 빌드가 깨끗해지거나 새로운 환경, 업그레이드된 빌드 서버가 노출시킨다. 현재의 마이그레이션은 숨겨진 불안정성을 제거한다.
빌드가 여전히 실패하는 경우 해결하는 방법
다음 점을 확인하세요:
-
모든 모듈이 패치되었다. 플러그인 모듈, 앱 모듈, 샘플, 템플릿 자산을 확인하세요.
-
공유 스크립트에 두 번째 참조가 없다. 전체 저장소 (포함하여 커스텀 Gradle 스크립트)를 검색하세요.
-
캐시가 깨끗하다.
./gradlew cleanAGP / Gradle / JDK 버전이 일치한다. Android 문서에서 지원하는 AGP 버전과 일치하는 combination을 사용하세요. -
Run
-
CI는 동일한 버전을 사용합니다. CI에서 JDK 및 Gradle wrapper 버전을 고정하여 환경漂移을 피합니다.
-
당신은 오직 패치를 적용하지 않습니다.
node_modules. 트래킹된 플러그인 소스, 아닌 임시 의존성 디렉토리에서 고쳐야합니다.
SEO FAQ: AGP 9 Capacitor 플러그인 빌드 오류
AGP 9에서 __CAPGO_KEEP_0__ 플러그인 빌드 오류를 어떻게 고치나요? proguard-android.txt 대체:
대신:
getDefaultProguardFile('proguard-android.txt')
그런 다음 clean rebuild를 실행하세요.
getDefaultProguardFile('proguard-android-optimize.txt')
Android Gradle Plugin 9로 업그레이드 후 __CAPGO_KEEP_0__ 플러그인 빌드가 실패하는 이유는 무엇인가요?
Why does my Capacitor plugin build fail after upgrading to Android Gradle Plugin 9?
CI에서 JDK 및 Gradle wrapper 버전을 고정하여 환경漂移을 피합니다. android/build.gradle legacy Gradle config이 아직 참조하는 플러그인 파일 때문입니다. proguard-android.txt. AGP 9 프로젝트는 proguard-android-optimize.txt.
AGP 9 마이그레이션의 빠른 경로를 사용하는 Capacitor 플러그인에 대해 무엇인가요?
워크스페이스 전체에서 검색 및 대체 명령어를 사용하고, 대표적인 플러그인에 대해 git grep 을 실행하세요. bun run verify:android 이것은 __CAPGO_KEEP_0__ 문제만인가요?
Is this only a Capacitor issue?
이 마이그레이션에 관련된 키워드는 무엇인가요?
내부 문서나 지원 페이지에 이 내용을 문서화할 때, 다음과 같은 용어를 포함하세요:
AGP 9 빌드 오류
- Android Gradle Plugin 9 ProGuard 파일 누락
- __CAPGO_KEEP_0__ 플러그인 Android 빌드 실패
- Capacitor plugin Android build failed
proguard-android.txt대체proguard-android-optimize.txt이동
관련 링크
- 안드로이드 개발자: 앱 빌드 개요
- 안드로이드 그레이들 플러그인: 릴리즈 노트
- 안드로이드 code 축소: R8 및 규칙
- 그레이들 문서: 빌드 도구 기초
- Capacitor 문서: 공식 문서
- Capgo 문서: 자동 업데이트 문서
최종 결론
AGP 9 문제는 간단하지만, 여러 플러그인 워크스페이스에서 쉽게 놓치기 쉬운 문제입니다. __CAPGO_KEEP_0__를 모든 관련된 곳에 대체하면 안드로이드 빌드가 예측 가능해집니다. proguard-android.txt __CAPGO_KEEP_0__ 플러그인을 사용하는 경우, 공식 저장소에서 이미 이 마이그레이션을 적용했기 때문에 업그레이드 시 더 많은 충격을 받지 않습니다. proguard-android-optimize.txt __CAPGO_KEEP_0__ 플러그인 AGP 9 빌드 오류 해결에 대해 계속 진행하세요.
Capgo 플러그인 AGP 9 빌드 오류 해결을 사용하여 CI/CD 자동화 계획을 세우고, 이를 연결하세요.
Capacitor
__CAPGO_KEEP_0__ Capacitor __CAPGO_KEEP_0__ Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, CI/CD 통합 Capgo CI/CD 통합 GitHub Actions Integration for the implementation detail in GitHub Actions Integration.