Ghi chú phát hành trình bổ trợ Android cho Gradle 8.9

Kho lưu trữ JCenter chuyển sang chế độ chỉ đọc từ ngày 31 tháng 3 năm 2021. Để biết thêm thông tin, hãy xem nội dung Cập nhật dịch vụ JCenter.

Android Studio là một hệ thống xây dựng dựa trên Gradle còn trình bổ trợ Android cho Gradle bổ sung một số tính năng dành riêng cho việc xây dựng ứng dụng Android. Mặc dù trình bổ trợ Android cho Gradle (AGP) thường được cập nhật ở dạng khoá trong Android Studio, nhưng trình bổ trợ này (và phần còn lại của hệ thống Gradle) có thể hoạt động độc lập với Android Studio và được cập nhật riêng.

Trang này giải thích cách cập nhật các công cụ Gradle cũng như nội dung các bản cập nhật gần đây. Để nắm được ghi chú phát hành cho các phiên bản trình bổ trợ Android cho Gradle trước đây, hãy xem ghi chú phát hành trước đây.

Để biết những vấn đề đã được khắc phục trong phiên bản trình bổ trợ Android cho Gradle này, hãy xem các vấn đề đã xử lý.

Để đọc toàn bộ tóm tắt tổng quan về những thay đổi có thể gây lỗi sắp tới trong trình bổ trợ Android cho Gradle, vui lòng xem lộ trình phát triển trình bổ trợ Android cho Gradle.

Để biết thông tin chi tiết về cách định cấu hình bản dựng Android bằng Gradle, hãy xem các trang sau đây:

Để biết thêm thông tin về hệ thống xây dựng Gradle, hãy xem Hướng dẫn sử dụng Gradle.

Cập nhật trình bổ trợ Android cho Gradle

Khi cập nhật Android Studio, bạn có thể nhận được lời nhắc tự động cập nhật trình bổ trợ Android cho Gradle lên phiên bản mới nhất. Bạn có thể chọn chấp nhận bản cập nhật hoặc chỉ định một phiên bản theo cách thủ công dựa trên yêu cầu bản dựng của dự án.

Bạn có thể chỉ định phiên bản trình bổ trợ trong trình đơn File (Tệp) >Project Structure (Cấu trúc dự án) >Project (Dự án) trong Android Studio hoặc tệp build.gradle.kts cấp cao nhất. Phiên bản trình bổ trợ này áp dụng cho mọi mô-đun được tạo trong dự án Android Studio đó. Ví dụ sau đây sẽ thiết lập trình bổ trợ thành phiên bản 8.9.0 qua tệp build.gradle.kts:

KotlinGroovy
plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}
 
plugins {
    id 'com.android.application' version '8.9.0' apply false
    id 'com.android.library' version '8.9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.10' apply false
}

Thận trọng: Bạn không nên sử dụng các phần phụ thuộc động trong số phiên bản, chẳng hạn như 'com.android.tools.build:gradle:8.9.+'. Việc sử dụng tính năng này có thể dẫn đến tình trạng cập nhật phiên bản không mong muốn và khó giải quyết sự khác biệt giữa các phiên bản.

Nếu phiên bản trình bổ trợ đã chỉ định chưa được tải xuống, Gradle sẽ tải phiên bản này xuống vào lần tiếp theo bạn tạo dự án hoặc nhấp vào File (Tệp) >Sync Project with Gradle Files (Đồng bộ hoá dự án với tệp Gradle) qua thanh trình đơn trong Android Studio.

Cập nhật Gradle

Khi cập nhật Android Studio, bạn có thể nhận được lời nhắc cập nhật Gradle lên phiên bản mới nhất. Bạn có thể chọn chấp nhận bản cập nhật hoặc chỉ định một phiên bản theo cách thủ công dựa trên yêu cầu bản dựng của dự án.

Bảng sau đây liệt kê phiên bản Gradle cần thiết cho mỗi phiên bản của trình bổ trợ Android cho Gradle. Để đạt hiệu quả tối đa, bạn nên sử dụng phiên bản mới nhất có thể của cả Gradle và trình bổ trợ.

Phiên bản trình bổ trợPhiên bản Gradle tối thiểu cần có
8.98.11.1
8.88.10.2
8,78.9
8.68,7
8,58,7
8.48.6
8.38.4
8.28.2
8.18.0
8.08.0
7.47.5
Phiên bản trình bổ trợPhiên bản Gradle bắt buộc
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0 trở lên6.7.1
4.1.0 trở lên6.5 trở lên
4.0.0 trở lên6.1.1 trở lên
3.6.0 – 3.6.45.6.4 trở lên
3.5.0 – 3.5.45.4.1 trở lên
3.4.0 – 3.4.35.1.1 trở lên
3.3.0 – 3.3.34.10.1 trở lên
3.2.0 – 3.2.14.6 trở lên
3.1.0 trở lên4.4 trở lên
3.0.0 trở lên4.1 trở lên
2.3.0 trở lên3.3 trở lên
2.1.3 – 2.2.32.14.1 – 3.5
2.0.0 – 2.1.22.10 – 2.13
1.5.02.2.1 – 2.13
1.2.0 – 1.3.12.2.1 – 2.9
1.0.0 – 1.1.32.2.1 – 2.3

Bạn có thể chỉ định phiên bản Gradle trên trình đơn File (Tệp) > Project Structure (Cấu trúc dự án) > Project (Dự án) trong Android Studio hoặc bằng cách cập nhật phiên bản Gradle qua dòng lệnh. Bạn nên sử dụng công cụ dòng lệnh Trình bao bọc Gradle để cập nhật tập lệnh gradlew. Ví dụ sau đây sẽ thiết lập phiên bản Gradle thành 8.9 bằng Trình bao bọc Gradle. Lưu ý: Bạn cần chạy lệnh này 2 lần để nâng cấp cả Gradle và chính Trình bao bọc Gradle (để biết thêm thông tin, hãy xem phần Nâng cấp Trình bao bọc Gradle). 

gradle wrapper --gradle-version 8.9

Tuy nhiên, có thể không thực hiện được việc này trong một số trường hợp, chẳng hạn như khi bạn vừa cập nhật AGP và AGP đó không còn tuân thủ phiên bản Gradle hiện tại nữa. Trong trường hợp này, bạn cần chỉnh sửa thông tin tham chiếu phân phối Gradle trong tệp gradle/wrapper/gradle-wrapper.properties. Ví dụ sau đây sẽ thiết lập phiên bản Gradle thành 8.9 trong tệp gradle-wrapper.properties. 

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

Trình bổ trợ Android cho Gradle và khả năng tương thích với Android Studio

Android Studio là một hệ thống xây dựng dựa trên Gradle, còn trình bổ trợ Android cho Gradle (AGP) bổ sung một số tính năng dành riêng cho việc xây dựng ứng dụng Android. Bảng sau đây liệt kê yêu cầu về phiên bản AGP cho từng phiên bản Android Studio.

Phiên bản Android Studio Phiên bản AGP bắt buộc
Meerkat | 2024.3.1 3.2-8.9
Bản cập nhật tính năng Ladybug | 2024.2.2 3.2-8.8
Ladybug | 2024.2.1 3.2-8.7
Bản cập nhật tính năng Koala | 2024.1.2 3.2-8.6
Koala | 2024.1.1 3.2-8.5
Jellyfish | 2023.3.1 3.2-8.4
Iguana | 2023.2.1 3.2-8.3
Hedgehog | 2023.1.1 3.2-8.2
Giraffe | 2022.3.1 3.2-8.1
Flamingo | 2022.2.1 3.2-8.0
Phiên bản Android Studio Phiên bản AGP bắt buộc
Electric Eel | 2022.1.1 3.2-7.4
Dolphin | 2021.3.1 3.2-7.3
Chipmunk | 2021.2.1 3.2-7.2
Bumblebee | 2021.1.1 3.2-7.1
Arctic Fox | 2020.3.1 3.1-7.0

Để biết thông tin về các tính năng mới trong trình bổ trợ Android cho Gradle, hãy xem ghi chú phát hành của trình bổ trợ Android cho Gradle.

Phiên bản tối thiểu của các công cụ dành cho cấp độ API trên Android

Có các phiên bản Android Studio và AGP tối thiểu hỗ trợ một cấp độ API cụ thể. Việc sử dụng các phiên bản Android Studio hoặc AGP thấp hơn so với yêu cầu của targetSdk hoặc compileSdk của dự án có thể dẫn đến các sự cố không mong muốn. Bạn nên sử dụng phiên bản xem trước mới nhất của Android Studio và AGP để thao tác trong các dự án nhắm đến phiên bản xem trước của hệ điều hành Android. Bạn có thể cài đặt các phiên bản xem trước của Android Studio cùng với một phiên bản ổn định.

Sau đây là các phiên bản Android Studio và AGP tối thiểu:

Cấp độ API Phiên bản Android Studio tối thiểu Phiên bản AGP tối thiểu
Bản xem trước Baklava Meerkat | 2024.3.1 8.9.0
35 Bản cập nhật tính năng Koala | 2024.2.1 8.6.0
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2

Thay đổi về phiên bản (tháng 11 năm 2020)

Chúng tôi đang cập nhật cách đánh số phiên bản cho trình bổ trợ Android cho Gradle (AGP) để phù hợp hơn với công cụ bản dựng Gradle cơ bản.

Sau đây là những thay đổi đáng chú ý:

  • AGP sẽ sử dụng phiên bản ngữ nghĩa và các thay đổi có thể gây lỗi sẽ dành cho các bản phát hành chính.

  • Sẽ có một phiên bản lớn của AGP được phát hành mỗi năm, phù hợp với bản phát hành chính của Gradle.

  • Bản phát hành sau AGP 4.2 sẽ là phiên bản 7.0 và yêu cầu phải nâng cấp lên Gradle phiên bản 7.x. Mọi bản phát hành chính của AGP sẽ yêu cầu nâng cấp phiên bản lớn trong công cụ Gradle cơ bản.

  • Các API không được sử dụng nữa trước khoảng một năm, đồng thời chức năng thay thế sẽ được ra mắt. API không dùng nữa sẽ bị xoá sau khoảng một năm trong lần cập nhật chính tiếp theo.

Khả năng tương thích

Cấp độ API tối đa mà trình bổ trợ Android cho Gradle 8.9 hỗ trợ là API cấp 35. Sau đây là một số thông tin khác về khả năng tương thích:

Phiên bản tối thiểu Phiên bản mặc định Lưu ý
Gradle 8.11.1 8.11.1 Để tìm hiểu thêm, hãy xem phần cập nhật Gradle.
Công cụ tạo SDK 35.0.0 35.0.0 Cài đặt hoặc định cấu hình Công cụ tạo SDK.
NDK Không áp dụng 27.0.12077973 Cài đặt hoặc định cấu hình phiên bản khác của NDK.
JDK 17 17 Để tìm hiểu thêm, hãy xem phần cài đặt phiên bản JDK.

Vấn đề đã khắc phục

Trình bổ trợ Android cho Gradle 8.9.0

Vấn đề đã khắc phục
Trình bổ trợ Android cho Gradle
Cung cấp thông báo lỗi hữu ích khi tác vụ thiết lập GMD không thành công do không đủ dung lượng ổ đĩa
Trình bổ trợ com.android.settings không nhận dạng được targetSdk
Lỗi không hữu ích "compileSdkVersion chưa được chỉ định. Vui lòng thêm vào build.gradle"
Thiếu mục "Clean build" (Xây dựng sạch) trong trình đơn Build (Xây dựng)
Có thể cho phép tính năng hỗ trợ Kotlin tích hợp của AGP tự động thêm phần phụ thuộc kotlin stdlib
Cập nhật shouldConfigureKotlinPlatformAttribute để xử lý tính năng hỗ trợ Kotlin tích hợp
Cung cấp cú pháp gradle kotlin trong thông báo lỗi cho `checkTestedAppObfuscationRelease`
Lỗi Thư viện hợp nhất khi có thể cải thiện phần phụ thuộc chưa được phân giải
Các thuộc tính hệ thống từ gradle.properties không được truyền đến Worker Gradle R8 trong các quy trình riêng biệt
Đặt BuiltArtifact.outputFile làm loại Tệp
Việc không cung cấp không gian tên trên thư viện hợp nhất sẽ không đưa ra thông báo lỗi chính xác
Các tuỳ chọn tìm lỗi mã nguồn trong AGP 7.1.0-alpha08 không cho phép stdout
Trình bổ trợ Android cho Gradle: Các biến thể phải hiển thị tên nhóm tài nguyên
Bộ nhớ đệm cấu hình dễ bị lỗi khi thiết lập biến môi trường TERM
AndroidComponentsExtension.addSourceSetConfigurations bị hỏng khi bật số liệu thống kê
Dòng tập lệnh khởi chạy "C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle": 162
AndroidComponentsExtension.addSourceSetConfigurations bị hỏng khi bật số liệu thống kê
Dexer (D8)
java.lang.VerifyError: Lớp bị từ chối của trình xác minh: [0x430] copy1 v2<-v264 type=Undefined cat=3
Tìm lỗi mã nguồn
Tìm lỗi mã nguồn gặp sự cố với các bước kiểm tra tìm lỗi mã nguồn trong Gradle
Tìm lỗi mã nguồn không thành công với InstantiationException mà không có thông báo ngoại lệ trong dấu vết ngăn xếp tìm lỗi mã nguồn
Kết quả kiểm tra tìm lỗi mã nguồn dương tính giả android.permission.SCHEDULE_EXACT_ALARM chỉ được cấp cho các ứng dụng hệ thống
Bạn nên áp dụng tính năng kiểm tra StringFormatInvalid cho phương thức stringResource của Compose
Chú giải RequiresFeature không hoạt động đối với các tệp Kotlin
kotlin android.os.Handler removeCallbacks Runnable
Tìm lỗi mã nguồn WrongConstant trên định nghĩa thay vì sử dụng hằng số bằng cách sử dụng shift
Tìm lỗi mã nguồn WrongConstant xuất hiện hai lần
Ngoại lệ thời gian chạy dưới API 26 với API nio Java không được hỗ trợ (không có lỗi tìm lỗi mã nguồn)
Tìm lỗi mã nguồn ngăn chặn việc sử dụng RequiresApi ngay cả trên phương thức trợ giúp riêng tư trong kiểm thử
Chế độ K2 gửi cảnh báo RestrictedApi khi sử dụng .hasRoute(Route::class) trong Android Studio
Trình tìm lỗi mã nguồn đề xuất thay thế @RequiresExtension trên kiểm thử bằng @SdkSuppress, không hỗ trợ tiện ích SDK
Công cụ tìm lỗi mã nguồn báo cáo không chính xác một bố cục lồng không cần thiết khi FrameLayout được sử dụng với fitSystemWindows để gói một RelativeLayout con yêu cầu khoảng đệm tuỳ chỉnh.
Quy tắc tìm lỗi mã nguồn CoarseFineLocation không tính đến thuộc tính maxSdkVersion
AppLinkSplitToWebAndCustom là UnknownIssue trong công cụ tìm lỗi mã nguồn 8.7.3
Sự cố kiểm tra tìm lỗi mã nguồn StringEscapeDetector trên "\\ "
Cảnh báo về tìm lỗi mã nguồn không chính xác cho chú thích `@Parcelize` trên các giao diện kín
AS 2024.3.1.4 bị treo không liên tục khi chỉnh sửa văn bản kotlin.
Tích hợp công cụ tìm lỗi mã nguồn
lintVitalRelease không tự động chạy khi tạo gói ứng dụng
Trình rút gọn (R8)
Gson proguard không hoạt động đúng cách sau khi nâng cấp lên AGP 8.8
java.lang.VerifyError: Lớp bị từ chối của trình xác minh
Leanback gặp sự cố khi rút gọn bằng R8 có trong AGP 8.10.0-alpha04