Flutter url_launcher 추가 후 AAB 빌드 실패 해결 (androidx.browser / AGP 8.9.1 요구)

 

안녕하세요. 코딩하는 Jay입니다.

 

Flutter 앱에 링크 열기 기능을 붙이려고 url_launcher 패키지를 추가했더니, 잘 되던 Android AAB(App Bundle) 빌드가 갑자기 실패하는 상황을 만났습니다. 릴리스 직전에 터지면 당황스럽죠. 원인과 해결법을 정리해둡니다.

 

증상

url_launcher를 추가하고 릴리스 번들을 만들려는데 빌드가 깨집니다.

flutter build appbundle --release

에러는 대략 이런 형태로 나옵니다. (메시지 표현은 환경마다 조금씩 다를 수 있습니다.)

Dependency 'androidx.browser:browser:1.9.0' requires Android Gradle plugin 8.9.1 or higher.
This build currently uses Android Gradle plugin 8.7.0.

즉, 코드 문제가 아니라 빌드 도구 버전이 부족해서 나는 에러입니다.

 

원인

url_launcher(정확히는 Android 구현체)가 내부적으로 androidx.browser에 의존합니다. 이 라이브러리가 버전이 올라가면서(androidx.browser:1.9.0, 그리고 함께 딸려오는 androidx.core:1.17.0) 더 높은 Android Gradle Plugin(AGP) 을 요구하게 됐습니다.

• 요구 조건: AGP 8.9.1 이상
• 기존 프로젝트: AGP 8.7.0 → 조건 미달로 빌드 실패

정리하면 url_launcher → androidx.browser 1.9.0 / androidx.core 1.17.0 → AGP 8.9.1+ 필요 라는 연쇄입니다.

 

해결 — AGP와 Gradle 버전 올리기

두 곳만 손보면 됩니다. AGP 버전과, 그 AGP를 지원하는 Gradle Wrapper 버전입니다.

 

1. ndroid/settings.gradle(또는 settings.gradle.kts)에서 AGP 버전을 올립니다.

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    // AGP 8.7.0 -> 8.9.1
    id "com.android.application" version "8.9.1" apply false
    id "org.jetbrains.kotlin.android" version "1.8.22" apply false
}

 

 

2.  android/gradle/wrapper/gradle-wrapper.properties에서 Gradle 배포 버전을 올립니다. AGP 8.9.x는 Gradle 8.11+ 를 필요로 합니다.

# 8.10.2 -> 8.11.1
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip

 

 

3. compileSdk는 기존 값(36)을 그대로 유지해도 됩니다. 이번 이슈는 AGP/Gradle 버전 문제라서 SDK 레벨을 굳이 함께 올릴 필요는 없습니다.

android {
    compileSdk 36   // 유지
    ...
}

 

확인

버전을 올린 뒤 클린 빌드로 다시 만들어 봅니다.

flutter clean
flutter pub get
flutter build appbundle --release

androidx.browser 요구 조건을 만족하게 되어 AAB가 정상적으로 생성됩니다.

 

결론

url_launcher 같은 패키지를 추가한 뒤 빌드가 깨질 때는, 패키지 코드가 아니라 그 패키지가 요구하는 빌드 도구(AGP·Gradle) 버전을 먼저 의심하면 빠르게 해결됩니다. 에러 메시지에 "requires Android Gradle plugin X 이상"이 보이면 settings.gradle의 AGP 버전과 gradle-wrapper.properties의 Gradle 버전을 짝으로 올려주면 됩니다.

다음에도 유익한 포스팅으로 찾아오겠습니다. 감사합니다!