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ạiHoặ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 Version | Minimum Gradle | Recommended Gradle |
|---|---|---|
| 8.7 | 8.9 | 8.10+ |
| 8.6 | 8.7 | 8.9+ |
| 8.5 | 8.7 | 8.9+ |
| 8.4 | 8.6 | 8.7+ |
| 8.3 | 8.4 | 8.6+ |
| 8.2 | 8.2 | 8.5+ |
| 8.1 | 8.0 | 8.4+ |
| 8.0 | 8.0 | 8.3+ |
AGP và Android Studio Compatibility
| AGP Version | Minimum Android Studio |
|---|---|
| 8.7 | Ladybug (2024.2.1) |
| 8.6 | Koala (2024.1.1) |
| 8.5 | Jellyfish (2023.3.1) |
| 8.4 | Iguana (2023.2.1) |
| 8.3 | Hedgehog (2023.1.1) |
Kotlin và AGP Compatibility
| AGP Version | Minimum 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
- Tools → AGP Upgrade Assistant
- Chọn phiên bản AGP muốn upgrade
- Click Run selected steps
- 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.zipHoặc dùng command:
./gradlew wrapper --gradle-version=8.105.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 buildXử 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=trueAGP 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.xMigration 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.zip2. Kotlin version incompatible
Error: Module was compiled with an incompatible version of KotlinGiải pháp: Cập nhật Kotlin version trong libs.versions.toml
3. Deprecated API warnings
warning: API 'XXX' is deprecatedGiải pháp:
- Check AGP release notes cho migration guide
- Sử dụng AGP Upgrade Assistant
- Search documentation cho API mới
4. BuildConfig not generated
Unresolved reference: BuildConfigGiả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 compatibilityGiả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 lint4. 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 để reviewRollback 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