Harmonogram migracji DSL/API wtyczki Androida do obsługi Gradle

Wtyczka Androida do Gradle (AGP) to obsługiwany system kompilacji aplikacji na Androida. Umożliwia kompilowanie wielu różnych typów źródeł i łączenie ich w aplikację, którą można uruchomić na fizycznym urządzeniu z Androidem lub w emulatorze.

W sekcji poniżej opisujemy planowany rozwój języka DSL i interfejsu API platformy AGP. Wraz z wprowadzaniem nowych interfejsów API w stabilnych wersjach stare interfejsy API będą oznaczane jako wycofane. Wycofane interfejsy API staną się niedostępne w kolejnej stabilnej wersji. W kolejnych sekcjach znajdziesz informacje o nadchodzących zmianach w każdej głównej wersji AGP.

Szczegółowe informacje o wycofanych lub usuniętych interfejsach AGP API znajdziesz w sekcji Aktualizacje interfejsu AGP API.

AGP 10.0 (koniec 2026 r.)

Zmiany i modernizacja interfejsu API wtyczki Androida do obsługi Gradle w wersji 10.0

Wtyczka Androida do obsługi Gradle 10.0 kończy przejście na w pełni leniwy model kompilacji zgodny z pamięcią podręczną konfiguracji. Ta wersja jest wynikiem wieloletnich prac nad zastąpieniem starszych interfejsów API, które nie są ładowane z opóźnieniem, bezpieczniejszą i wydajniejszą architekturą.

Dlaczego warto używać modelu leniwego tworzenia?

W starszym modelu kompilacji bez opóźnionego tworzenia Gradle podczas każdej synchronizacji lub wywołania kompilacji aktywnie ocenia obiekty, wysyła zapytania o dane wariantów i konfiguruje zadania we wszystkich modułach projektu. Wczesna ocena marnuje czas procesora i pamięć na warianty i zadania, które nie są uruchomione, oraz powoduje konflikty w kolejności oceny w złożonych skryptach kompilacji.

Dzięki przejściu na w pełni leniwy model kompilacji z użyciem leniwych dostawców (Provider<T>) i nowoczesnego interfejsu Variant API (androidComponents {}) właściwości i połączenia zadań są obliczane leniwie na żądanie tylko wtedy, gdy są potrzebne w aktywnym grafie wykonywania kompilacji.

Starsze interfejsy API usuwane w tej wersji były zasadniczo niezgodne z tą nowoczesną architekturą. Usunięcie tych plików umożliwia wtyczce Androida do obsługi Gradle pełną obsługę pamięci podręcznej konfiguracji Gradle i izolacji projektu, co znacznie przyspiesza kompilację i synchronizację w Android Studio.

Podstawowa różnica w architekturze

Starszy interfejs BaseVariant API (applicationVariants.all {}) był nastawiony na wykonywanie zadań. Zapewniało to programistom bezpośredni dostęp do zadań Gradle i wewnętrznych konfiguracji w fazie konfiguracji, co z założenia naruszało nowoczesne funkcje Gradle związane z wydajnością.

Nowy interfejs API wariantów (androidComponents {}) jest leniwy i skupiony na artefaktach. W dużym stopniu korzysta z interfejsu Property API Gradle i całkowicie usuwa wszystkie odwołania do Task i TaskProvider, co wymaga czystej interakcji z danymi wejściowymi i wyjściowymi (Variant.artifacts) zamiast z samymi zadaniami.

Co jest usuwane i zastępowane

Wszystkie poprzednie interfejsy i klasy używane w starszym DSL i starym interfejsie Variant API zostaną usunięte. Aby przygotować skrypty kompilacji i wtyczki niestandardowe, przeprowadź migrację z tych wycofanych interfejsów API i flag:

Aby uzyskać dostęp do wszystkich interfejsów i klas zastępujących DSL i Variant API (androidComponents {}), podczas tworzenia niestandardowych wtyczek Gradle lub logiki kompilacji zawsze używaj artefaktu gradle-api.

Etapy migracji

Aby ułatwić i usprawnić przejście na AGP 10.0, skorzystaj z tych sprawdzonych metod migracji:

1. Uruchom Asystenta uaktualniania wtyczki Androida do obsługi Gradle: przed bezpośrednim uaktualnieniem do wersji 10.0 uruchom oficjalnego Asystenta uaktualniania wtyczki Androida do obsługi Gradle w Android Studio (Tools > AGP Upgrade Assistant). Automatyzuje on kilka typowych migracji DSL i skryptów kompilacji oraz pomaga zachować dotychczasowe zachowania kompilacji.
2. Korzystaj z umiejętności trybu agenta w Android Studio: korzystaj z umiejętności opartych na AI (takich jak umiejętności aktualizacji wtyczki Androida do obsługi Gradle dostępne w repozytorium umiejętności Androida), aby zautomatyzować i uprościć migrację złożonej logiki kompilacji i języków DSL w Android Studio.
3. Najpierw usuń ostrzeżenia o wycofaniu w AGP 9.x: zaktualizuj projekt do najnowszej wersji AGP 9.x i usuń wszystkie ostrzeżenia o wycofaniu. Gdy projekt będzie działać w wersji 9.x bez ostrzeżeń i bez korzystania z android.newDsl=false ani android.builtInKotlin=false, przejście na wersję 10.0 będzie płynne.
4. Sprawdź wtyczki Gradle innych firm: upewnij się, że wtyczki innych firm zostały zaktualizowane do wersji zgodnych z AGP 10.0. Wtyczki, które nadal korzystają ze starszych typów rozszerzeń, będą powodować błędy kompilacji, np. ClassCastException: ... cannot be cast to class BaseExtension.
5. Korzystaj z oficjalnych przepisów migracji: w przypadku złożonych, rzeczywistych przykładów migracji i porównań obok siebie zapoznaj się z oficjalnym repozytorium GitHub gradle-recipes.

Poniżej znajdziesz porównanie przed i po, które pokazuje, jak przeprowadzić migrację z wcześniejszego wysyłania zapytań do starszych wariantów na leniwe konfigurowanie wariantów za pomocą androidComponents {}:

Wcześniej: starsza wersja interfejsu API wariantów (usunięta w AGP 10.0)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

Po: nowoczesny interfejs API wariantów (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

Testowanie działania wtyczki Androida do obsługi Gradle 10.0 w wersji 9.x

Nie musisz czekać na wydanie AGP 10.0, aby rozpocząć testowanie jego zachowań podczas kompilacji i sprawdzanie zgodności. W przypadku korzystania z dowolnej wersji AGP 9.x możesz jawnie wymusić działanie AGP 10.0, sprawdzając, czy gradle.properties wyłącza wszystkie rezygnacje i ustawia te flagi ścisłego działania:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

Wymagając android.newDsl=true i android.builtInKotlin=true, możesz sprawdzić, czy Twoja niestandardowa logika kompilacji i wtyczki innych firm są w pełni zgodne z rygorystycznymi wymaganiami interfejsu API AGP 10.0.

Selektywne wycofywanie się z migracji w przypadku podprojektów

Jeśli chcesz włączyć android.newDsl=true w całym projekcie, aby przetestować nowoczesne zachowania, ale potrzebujesz więcej czasu na migrację konkretnych podprojektów, możesz selektywnie wyłączać poszczególne moduły od wersji AGP 9.4.0-alpha04. Dodaj android.newDsl.optOut do gradle.properties, podając ścieżki projektu:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Selektywne wyłączanie wbudowanego języka Kotlin w poszczególnych modułach

Jeśli chcesz włączyć wbudowany Kotlin globalnie w całym projekcie (android.builtInKotlin=true), ale potrzebujesz więcej czasu na migrację konkretnych podprojektów z kotlin-android (lub w przypadku modułów bez kodu Kotlin), skonfiguruj te moduły na poziomie DSL, a nie na poziomie projektu. W pliku kompilacji modułu ustaw wartość enableKotlin = false:

android {
    enableKotlin = false
}

Przepływ pracy związany z opiniami i zgłaszaniem błędów

Chcemy mieć pewność, że nowy interfejs Variant API obsługuje wymagane przez Ciebie przypadki użycia. Jeśli podczas migracji ze starych interfejsów API napotkasz problem, który uniemożliwi Ci korzystanie z nowego interfejsu Variant API, wykonaj te czynności, aby przesłać opinię:

1. Sprawdź istniejące elementy: najpierw sprawdź błąd śledzenia w interfejsie AGP 10.0 Variant API Global, aby dowiedzieć się, czy blokada migracji jest już znana, i kliknij przycisk „+1” przy tym problemie.
2. Zgłaszanie brakujących interfejsów API: jeśli Twój przypadek użycia jest unikalny, zgłoś prośbę o dodanie nowej funkcji, korzystając z naszego szablonu interfejsu API wariantów. Dzięki temu będziemy mogli zbadać sprawę i Ci pomóc.

(Wstępnie) Usunięcie dostępu do prywatnych wewnętrznych klas AGP

Zależność od artefaktu gradle ukrywa teraz wszystkie wewnętrzne klasy i zapewnia dostęp do kompilacji tylko w przypadku interfejsów i klas dostępnych w artefakcie gradle-api. Ma to wpływ na kompilację wtyczki.

Nie można ręcznie dodać zależności, aby uzyskać dostęp do klas wewnętrznych.

AGP 9.0 (styczeń 2026 r.)

Nowe interfejsy API wariantów są stabilne, a stare interfejsy API są wycofane

Interfejsy API wariantów, które były w fazie testów w wersjach 4.1 i 4.2, są stabilne i znajdują się w artefakcie gradle-api. Poprzednie interfejsy i klasy używane w starym interfejsie Variant API są obecnie wycofane i wymagają wyraźnej zgody na użycie.

Nowe interfejsy DSL są stabilne, a stare zostały wycofane

Interfejsy DSL, które były w fazie rozwoju w wersjach 4.1, 4.2 i 7.0, są teraz stabilne i znajdują się w artefakcie gradle-api. Poprzednie interfejsy i klasy używane w DSL są teraz wycofane i wymagają wyraźnej zgody na użycie.

Prywatne wewnętrzne klasy AGP, które będą nadal dostępne

Prywatne klasy wewnętrzne z AGP, znajdujące się w innych artefaktach, są nadal dostępne podczas kompilacji plików i wtyczek, ale nie zalecamy ich używania, ponieważ w każdej chwili mogą ulec zmianom powodującym niezgodność.