Skip to Content

Nâng cấp Android Gradle Plugin (AGP)

Android Gradle Plugin (AGP) là plugin chính để build Android apps. Google thường xuyên phát hành phiên bản mới với tính năng mới, cải thiện hiệu suất và sửa lỗi. Bài viết này hướng dẫn cách nâng cấp AGP một cách an toàn.

Quy trình nâng cấp AGP

Bước 1: Kiểm tra phiên bản hiện tại

Xem phiên bản trong libs.versions.toml

# gradle/libs.versions.toml [versions] agp = "8.5.0" # Phiên bản hiện tại

Hoặc trong build.gradle.kts

// build.gradle.kts (Project-level) plugins { id("com.android.application") version "8.5.0" apply false }

Bước 2: Kiểm tra Release Notes

Trước khi nâng cấp, luôn đọc Release Notes để biết:

  • Breaking changes
  • Deprecated APIs
  • Yêu cầu phiên bản Gradle mới
  • Tính năng mới

Links quan trọng:


Bước 3: Kiểm tra Compatibility

AGP và Gradle Compatibility

AGP VersionMinimum GradleRecommended Gradle
8.78.98.10+
8.68.78.9+
8.58.78.9+
8.48.68.7+
8.38.48.6+
8.28.28.5+
8.18.08.4+
8.08.08.3+

AGP và Android Studio Compatibility

AGP VersionMinimum Android Studio
8.7Ladybug (2024.2.1)
8.6Koala (2024.1.1)
8.5Jellyfish (2023.3.1)
8.4Iguana (2023.2.1)
8.3Hedgehog (2023.1.1)

Kotlin và AGP Compatibility

AGP VersionMinimum Kotlin
8.7+1.9.20
8.5+1.9.0
8.0+1.8.0

⚠️ Quan trọng: Luôn kiểm tra compatibility matrix chính thức  trước khi upgrade.


Bước 4: Sử dụng AGP Upgrade Assistant

Android Studio có công cụ để tự động upgrade AGP với các thay đổi cần thiết.

Mở AGP Upgrade Assistant

  1. Tools → AGP Upgrade Assistant
  2. Chọn phiên bản AGP muốn upgrade
  3. Click Run selected steps
  4. Review các thay đổi

Các thay đổi tự động

AGP Upgrade Assistant có thể:

  • Cập nhật AGP version trong build files
  • Cập nhật Gradle wrapper version
  • Migrate deprecated APIs
  • Thêm/xóa properties trong gradle.properties

Bước 5: Cập nhật thủ công

Nếu không dùng Assistant hoặc cần control nhiều hơn:

5.1. Cập nhật Gradle Wrapper

# gradle/wrapper/gradle-wrapper.properties distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip

Hoặc dùng command:

./gradlew wrapper --gradle-version=8.10

5.2. Cập nhật AGP trong Version Catalog

# gradle/libs.versions.toml [versions] agp = "8.7.2" # Cập nhật version [plugins] android-application = { id = "com.android.application", version.ref = "agp" } android-library = { id = "com.android.library", version.ref = "agp" }

5.3. Cập nhật Kotlin (nếu cần)

[versions] kotlin = "2.0.21" # Cập nhật nếu cần [plugins] kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" } kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

5.4. Sync và Build

./gradlew --refresh-dependencies ./gradlew build

Xử lý Breaking Changes phổ biến

AGP 8.0 Breaking Changes

1. Default Java 17

android { compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } }

2. BuildConfig disabled by default

android { buildFeatures { buildConfig = true // Bật nếu cần dùng } }

3. Non-transitive R classes by default

# gradle.properties # Đã mặc định true từ AGP 8.0 android.nonTransitiveRClass=true

AGP 8.5+ Changes

Namespace required

android { namespace = "com.example.myapp" // Bắt buộc }

Compile SDK 34+ support

android { compileSdk = 35 }

AGP 8.7+ Changes

Kotlin 1.9.20+ required

[versions] kotlin = "2.0.21" # Cập nhật từ 1.9.x

Migration Script Example

Tạo script để automate upgrade process:

#!/bin/bash # upgrade-agp.sh NEW_AGP_VERSION="8.7.2" NEW_GRADLE_VERSION="8.10" NEW_KOTLIN_VERSION="2.0.21" echo "Upgrading AGP to $NEW_AGP_VERSION..." # Update gradle wrapper ./gradlew wrapper --gradle-version=$NEW_GRADLE_VERSION # Update libs.versions.toml (using sed) sed -i '' "s/^agp = \".*\"/agp = \"$NEW_AGP_VERSION\"/" gradle/libs.versions.toml sed -i '' "s/^kotlin = \".*\"/kotlin = \"$NEW_KOTLIN_VERSION\"/" gradle/libs.versions.toml echo "Syncing project..." ./gradlew --refresh-dependencies echo "Building project..." ./gradlew build echo "Upgrade complete!"

Troubleshooting thường gặp

1. Gradle version mismatch

Error: Minimum supported Gradle version is X.X. Current version is Y.Y.

Giải pháp: Cập nhật gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip

2. Kotlin version incompatible

Error: Module was compiled with an incompatible version of Kotlin

Giải pháp: Cập nhật Kotlin version trong libs.versions.toml

3. Deprecated API warnings

warning: API 'XXX' is deprecated

Giải pháp:

  1. Check AGP release notes cho migration guide
  2. Sử dụng AGP Upgrade Assistant
  3. Search documentation cho API mới

4. BuildConfig not generated

Unresolved reference: BuildConfig

Giải pháp: Bật BuildConfig explicitly:

android { buildFeatures { buildConfig = true } }

5. JVM target mismatch

Error: 'compileDebugJavaWithJavac' task (current target is 17) and 'compileDebugKotlin' task (current target is 11) jvm target compatibility

Giải pháp: Đồng bộ JVM target:

android { compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } }

Best Practices cho Upgrade

1. Upgrade thường xuyên

Upgrade định kỳ (mỗi minor version) dễ hơn upgrade nhảy nhiều versions.

2. Đọc Release Notes trước

Hiểu rõ breaking changes và deprecated APIs.

3. Test kỹ sau upgrade

# Build tất cả variants ./gradlew build # Chạy tests ./gradlew test ./gradlew connectedAndroidTest # Check lint ./gradlew lint

4. Commit changes riêng

git add -A git commit -m "chore: upgrade AGP to 8.7.2, Gradle to 8.10"

5. Sử dụng feature branches

git checkout -b upgrade/agp-8.7 # ... thực hiện upgrade ... git push origin upgrade/agp-8.7 # Tạo PR để review

Rollback nếu cần

Nếu upgrade gặp vấn đề nghiêm trọng:

# Revert changes git checkout -- . # Hoặc hard reset git reset --hard HEAD~1 # Clear Gradle caches ./gradlew clean rm -rf ~/.gradle/caches

📚 Tham khảo

Last updated on