Capacitor Plugin AGP 9 빌드 오류 해결 방법

만약 Capacitor Android Gradle Plugin 9(AGP 9)로 업그레이드한 후 플러그인이 실패하기 시작했다면, 작지만 치명적인 Gradle 설정 문제일 가능성이 높습니다.

이 글은 다음과 같은 검색 의도를 겨냥합니다:

Capacitor 플러그인 빌드 오류 AGP 9
Android Gradle Plugin 9 플러그인 빌드 실패
proguard-android.txt 찾을 수 없음
AGP 9 getDefaultProguardFile 오류
AGP 업그레이드 후 Capacitor Android 빌드 실패

요약하자면:

proguard-android.txt 는 더 이상 AGP 9 플러그인 빌드에서 안전한 기본 기준이 아닙니다.
다음으로 전환하세요: proguard-android-optimize.txt.
다시 빌드하고 확인하세요.

더 자세한 버전도 중요합니다. 특히 많은 플러그인이나 대규모 Capacitor 워크스페이스를 관리한다면요. 이 글에서는 다음을 다룹니다:

빌드 체인 내 Android와 AGP의 역할
Capacitor란 무엇이며 플러그인 빌드는 어떻게 작동하는가
무엇인지 Capgo 그리고 릴리스 안정성에 왜 중요한지
기존 플러그인 템플릿을 깨뜨리는 AGP 9의 구체적인 변경 사항
단일 또는 다중 레포지토리를 위한 안전한 마이그레이션 전략

여기서 말하는 Android란 무엇인가요?

Android Android는 운영체제이자 빌드 생태계입니다. Android용 Capacitor 앱이나 플러그인을 배포할 때 프로젝트는 다음 과정을 거칩니다:

Gradle 빌드 시스템입니다.
Android Gradle Plugin (AGP) Android 전용 Gradle 통합 도구입니다.
Android SDK 툴체인은 패키징, 슈링킹(shrinking), 린팅 및 결과물 .aar, .apk, 또는 .aab 생성을 담당합니다.

AGP 버전이 변경되면 기본 설정이나 내부 파일도 바뀔 수 있습니다. AGP 8에서 잘 작동하던 플러그인 설정이라도, 삭제되거나 지원이 중단된 베이스라인을 참조하고 있다면 AGP 9에서 오류가 발생할 수 있습니다.

Capacitor란 무엇인가요?

Capacitor code는 웹 code (TypeScript, JavaScript, HTML, CSS)로 iOS/Android 앱을 빌드하면서도 네이티브 API를 호출할 수 있게 해주는 크로스 플랫폼 런타임입니다.

Capacitor 앱은 보통 다음을 포함합니다:

웹 레이어 (UI 및 비즈니스 로직)
Native shell (ios/, android/)
JavaScript에 네이티브 기능을 노출하는 플러그인)

각 플러그인은 고유한 Native Build 설정을 가집니다. Android의 경우, 각 플러그인에는 AGP가 정확하게 파싱하고 컴파일해야 하는 android/build.gradle 파일이 포함되어 있습니다.

플러그인의 Gradle 설정이 오래된 경우, 웹 code 코드가 올바르더라도 앱 전체 빌드가 실패할 수 있습니다.

Capgo란 무엇인가요?

Capgo Capacitor 배포 및 운영을 위한 도구를 제공합니다:

Live Update 웹 번들 변경 사항 적용
플러그인 생태계 및 네이티브 기능 패키지
Capacitor 팀을 위한 CI/CD 친화적 업데이트 워크플로우

Live Update를 쓰더라도 Native Build 안정성은 필수입니다. 다음을 위해서는 여전히 클린 Android 빌드가 필요합니다:

App Store / Play Store 출시
Native 플러그인 업그레이드
플랫폼 SDK 마이그레이션
팀 온보딩 및 CI 신뢰성

그래서 AGP 9 호환성 수정이 중요합니다. 플러그인 레이어를 안정적으로 유지해 delivery pipeline이 예측 가능하게 해주기 때문입니다.

AGP 9에서 기존 플러그인 설정이 깨지는 이유

기존의 많은 플러그인 템플릿은 다음과 같은 방식을 사용해 왔습니다:

proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

AGP 9 환경에서는 이전 파일이 기존 템플릿/설정이 기대하는 위치에 더 이상 보장되지 않으므로, 이 레거시 베이스라인 참조가 실패할 수 있습니다.

대표적인 증상은 빌드 단계에서 발생하는 Gradle 에러이며, assemble, lint, 또는 build 주로 ProGuard 베이스라인 리소스 누락이나 잘못된 기본 파일 참조를 가리킵니다.

간단한 배경 지식: ProGuard, R8, baseline 파일

R8 은 Android 빌드 시 사용되는 최신 code shrinker/optimizer입니다.
proguard-rules.pro 은 프로젝트/플러그인의 커스텀 keep 규칙입니다.
getDefaultProguardFile(...) 은 Android에서 제공하는 baseline을 주입합니다.

다음 항목을 참조할 때:

proguard-android.txt -> 레거시, 최소 baseline
proguard-android-optimize.txt -> 최신 최적화 baseline (현재 설정의 권장 기본값)

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 설정을 생성하는 모든 generator/template 파일

플러그인 하나 마이그레이션 가이드

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

모든 플러그인 레포지토리 일괄 업데이트

하나의 워크스페이스에서 많은 플러그인 레포지토리를 관리한다면, 자동화하세요:

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

No matches는 추적 중인 플러그인 파일에서 기존 baseline 참조가 사라졌음을 의미합니다.

Capgo 롤아웃 상태

모든 공식 Capgo Capacitor 플러그인 레포지토리와 템플릿에 대해 이번 마이그레이션을 완료했습니다:

이제 플러그인 Android 모듈이 다음을 참조합니다 proguard-android-optimize.txt
플러그인 예제 Android 앱도 업데이트되었습니다
플러그인 스캐폴딩 템플릿을 업데이트하여, 새로 만드는 플러그인도 기본적으로 AGP 9 환경에서 안전합니다

이를 통해 CI 단계에 도달하기 전, AGP 9 업그레이드 시 흔히 발생하는 오류를 미리 방지할 수 있습니다.

현재 빌드가 성공하더라도 이 작업이 중요한 이유

다음과 같은 상황에서는 오류가 즉시 나타나지 않을 수 있습니다:

CI 캐시가 문제를 가리고 있는 경우
프로젝트마다 AGP 버전이 혼용되어 있는 경우
로컬 개발 시 일부 모듈만 다시 빌드되는 경우

하지만 결국 clean build, 새로운 환경, 또는 업그레이드된 runner에서 문제가 드러납니다. 지금 마이그레이션을 진행하여 잠재적인 불안정성을 제거하세요.

교체 후에도 빌드가 실패할 경우 문제 해결 방법

다음 사항들을 확인하세요:

모든 모듈이 패치되었는지 확인하세요. 플러그인 모듈, 앱 모듈, 샘플 및 템플릿 에셋을 살펴보세요.
공유 스크립트에 중복 참조가 없는지 확인하세요. 전체 레포지토리(커스텀 Gradle 스크립트 포함)를 검색하세요.
캐시를 정리하세요. 다음 명령어를 실행하세요: ./gradlew clean 그리고 다시 빌드하세요.
AGP / Gradle / JDK 버전이 일치하는지 확인하세요. 사용 중인 AGP 버전에 대해 Android 문서에서 지원하는 조합을 사용하세요.
CI 환경이 로컬과 동일한 버전을 사용하는지 확인하세요. 환경 차이(drift)를 방지하기 위해 CI에서 JDK 및 Gradle wrapper 버전을 고정하세요.
단순히 패치만 하는 것이 아닙니다 node_modules패치해서는 안 됩니다. transient dependency 디렉토리가 아닌, 추적 중인 플러그인 소스를 수정하세요.

SEO FAQ: AGP 9 Capacitor 플러그인 빌드 오류

해결 방법: `proguard-android.txt` AGP 9에서 찾을 수 없음?

변경 전:

getDefaultProguardFile('proguard-android.txt')

변경 후:

getDefaultProguardFile('proguard-android-optimize.txt')

그 다음 clean rebuild를 실행하세요.

Android Gradle Plugin 9로 업그레이드한 후 왜 Capacitor 플러그인 빌드가 실패하나요?

대부분의 실패는 플러그인의 레거시 Gradle 설정에서 발생하며, android/build.gradle 여전히 다음을 참조하는 파일: proguard-android.txt. AGP 9 프로젝트에서는 다음을 사용해야 합니다: proguard-android-optimize.txt.

많은 Capacitor 플러그인을 위한 가장 빠른 AGP 9 마이그레이션 방법은 무엇인가요?

워크스페이스 전체에서 search-and-replace 명령을 사용한 뒤, 다음으로 검증하세요: git grep 그리고 다음을 실행하세요: bun run verify:android 대표적인 플러그인들에서 발생합니다.

Capacitor에서만 발생하는 문제인가요?

아니요. Deprecated된 ProGuard baseline 참조를 사용하는 모든 Android 모듈(app 또는 library)에서 유사한 AGP 9 빌드 에러가 발생할 수 있습니다. 특히 많은 레포지토리가 오래된 템플릿을 공유하기 때문에 플러그인 생태계에서 더욱 두드러지게 나타납니다.

이번 마이그레이션과 관련된 주요 키워드는 무엇인가요?

사내 런북이나 지원 페이지에 이 내용을 문서화할 때 다음 용어들을 포함하세요:

AGP 9 빌드 에러
Android Gradle Plugin 9 ProGuard 파일 누락
Capacitor 플러그인 Android 빌드 실패
proguard-android.txt 대체 방법
proguard-android-optimize.txt 마이그레이션

Android 개발자 여러분: 앱 빌드 개요
Android Gradle Plugin: 릴리스 노트
Android code shrinking: R8 및 규칙
Gradle 문서: 빌드 도구 기초
Capacitor 문서: 공식 문서
Capgo 문서: Auto update 문서

마치며

이 AGP 9 문제는 간단하지만, 여러 플러그인을 사용하는 워크스페이스에서는 놓치기 쉽습니다. 해당 부분을 모두 proguard-android.txt 포함 proguard-android-optimize.txt 교체하면 Android 빌드가 다시 예측 가능해집니다.

Capgo 플러그인을 사용한다면, 공식 저장소에 이 마이그레이션이 이미 적용되어 있어 예상치 못한 문제를 줄이며 업그레이드할 수 있습니다.

계속 읽기: Capacitor Plugin AGP 9 Build Error Fix

사용 중이라면 Capacitor Plugin AGP 9 빌드 오류 해결 방법 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.