本頁面由 Cloud Translation API 翻譯而成。

設定基準設定檔產生作業

基準設定檔 Gradle 外掛程式可讓您更輕鬆產生及維護基準設定檔。此外掛程式可執行以下工作：

本頁面說明如何使用基準設定檔 Gradle 外掛程式，自訂基準設定檔產生作業。

外掛程式需求

AGP 8.0 以上版本
最新 Gradle 外掛程式版本的依附元件

使用 Gradle 管理的裝置產生基準設定檔

如要使用 Gradle 管理的裝置 (GMD) 產生基準設定檔，請在設定檔產生者模組 (例如 :baselineprofile 測試模組) 的 build.gradle.kts 設定中新增 GMD，如以下範例所示：

Kotlin

android {
   testOptions.managedDevices.devices {
       create<com.android.build.api.dsl.ManagedVirtualDevice>("pixel6Api31") {
           device = "Pixel 6"
           apiLevel = 31
           systemImageSource = "aosp"
       }
   }
}

Groovy

android {
   testOptions.managedDevices.devices {
       pixel6Api31(ManagedVirtualDevice) {
           device 'Pixel 6'
           apiLevel = 31
           systemImageSource 'aosp'
       }
   }
}

請使用 GMD 產生基準設定檔，方法是將 GMD 新增至基準設定檔 Gradle 外掛程式設定，如下所示，在 :baselineprofile 測試模組的 build.gradle.kts 中：

Kotlin

baselineProfile {
    managedDevices += "pixel6Api31"
}

Groovy

baselineProfile {
    managedDevices = ['pixel6Api31']
}

使用 GMD 產生基準設定檔時，請在 :baselineprofile 測試模組中將 useConnectedDevices 設為 false：

Kotlin

baselineProfile {
    ...
    useConnectedDevices = false
}

Groovy

baselineProfile {
    ...
    useConnectedDevices false
}

為不同變化版本產生基準設定檔

您可以為每個變化版本、每個變種版本產生基準設定檔，也可以產生單一檔案供所有變化版本使用。採用合併設定即可控管這項行為，如以下範例所示，在應用程式或程式庫模組的 build.gradle.kts 中。

Kotlin

baselineProfile {
    mergeIntoMain = true
}

Groovy

baselineProfile {
    mergeIntoMain true
}

如要將為所有變化版本產生的設定檔合併成單一設定檔，請將 mergeIntoMain 設為 true。這項設定為 true 時，就無法為每個變化版本產生基準設定檔，因此會有一個名為 generateBaselineProfile 的 Gradle 工作。設定檔會輸出至 src/main/generated/baselineProfiles。

如要停用合併功能，讓每個變化版本都有一個設定檔，請將 mergeIntoMain 設為 false。在這種情況下，會依照各個變化版本存在多個 Gradle 工作。舉例來說，如果有免費版和付費版這兩個變種版本，以及一個發布子版本類型，則產生的工作如下：

* `generateFreeReleaseBaselineProfile`
* `generatePaidReleaseBaselineProfile`
* `generateReleaseBaselineProfile`

如要為每個變化版本指定合併行為，請使用下列程式碼：

Kotlin

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

在上述範例中，標記設為 true 的變化版本都會合併至 src/main/generated/baselineProfiles，標記設為 false 的變化版本設定檔則會保留在資料夾 src/<variant>/generated/baselineProfiles 中。

根據預設，程式庫的 mergeIntoMain 會設為 true，應用程式則設為 false。

在組合新版本時自動產生基準設定檔

您可以將基準設定檔設為使用每個發布子版本自動產生，而不是使用工作 generateBaselineProfile 手動產生。使用自動產生功能時，最新的設定檔會包含在發布子版本中。

如要為發布子版本啟用自動產生功能，請使用 automaticGenerationDuringBuild 標記：

Kotlin

baselineProfile {
    automaticGenerationDuringBuild = true
}

Groovy

baselineProfile {
    automaticGenerationDuringBuild true
}

將 automaticGenerationDuringBuild 標記設為 true，即可觸發每個發布組合的新基準設定檔產生作業。也就是說，執行組合發布子版本工作 (例如 ./gradlew:app:assembleRelease) 也會觸發 :app:generateReleaseBaselineProfile、開始基準設定檔檢測設備測試，並建構用於執行測試的基準設定檔版本。自動產生功能可協助使用者獲得最佳效能的優勢，但系統需要執行雙倍的建構作業與檢測設備測試，因此建構時間也會增加。

您也可以為每個變化版本指定這個行為，如以下範例所示：

Kotlin

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

在上述範例中，系統會在啟動 assembleFreeRelease 時執行 generateFreeReleaseBaselineProfile 工作。舉例來說，如果使用者想將 release 用於會一律在建構過程中產生設定檔的發布版本，並將 releaseWithoutProfile 版本用於內部測試，這種做法會很實用。

將基準設定檔儲存至來源

您可以使用應用程式或程式庫模組 build.gradle.kts 中的 saveInSrc 標記，將基準設定檔儲存至來源目錄：

true：基準設定檔儲存在 src/<variant>/generated/baselineProfiles 中。這可讓您使用來源修訂最新產生的設定檔。
false：基準設定檔會儲存在版本目錄的中繼檔案。這樣一來，您修訂程式碼時，就不會儲存最新產生的設定檔。

Kotlin

baselineProfile {
    saveInSrc = true
}

Groovy

baselineProfile {
    saveInSrc true
}

您也可以為每個變化版本指定這個行為：

Kotlin

baselineProfile {
    variants {
        freeRelease {
            saveInSrc = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

停用警告

根據預設，基準設定檔 Gradle 外掛程式會針對可能導致問題的情況發出警告。如要停用警示，您可以在 build.gradle.kts 檔案中將相關選項設為 false。警告選項如下：

baselineProfile {
    warnings {

        /**
        * Warn when the Android Gradle Plugin version is higher than the max
        * tested one.
        */
        maxAgpVersion = true

        /**
        * Warn when a benchmark or baseline profile variant has been disabled.
        */
        disabledVariants = true

        /**
        * Warn that running `generateBaselineProfile` with AGP 8.0 doesn't
        * support running instrumentation tests for multiple build types at
        * once.
        */
        multipleBuildTypesWithAgp80 = true

        /**
        * Warn when no baseline profiles are generated after running the
        * generate baseline profile command.
        */
        noBaselineProfileRulesGenerated = true

        /**
        * Warn when no startup profiles are generated after running the generate
        * baseline profile command.
        */
        noStartupProfileRulesGenerated = true
    }
}

篩選設定檔規則

基準設定檔 Gradle 外掛程式可讓您篩選所產生的基準設定檔規則。如果您排除設定檔規則時，是針對範例應用程式中其他依附元件或程式庫本身的類別和方法，那麼這個做法對程式庫尤其實用。篩選器可包含及排除特定套件和類別。如果您只指定排除條件，系統只會排除相符的基準設定檔規則，其他所有項目都會包含在內。

篩選器規格可以是下列任一項目：

結尾為雙萬用字元的套件名稱，會符合指定套件和所有子套件。舉例來說，com.example.** 符合 com.example.method 和 com.example.method.bar。
結尾為萬用字元的套件名稱，只會符合指定套件。舉例來說，com.example.* 符合 com.example.method，但不符合 com.example.method.bar。
與特定類別相符的類別名稱，例如 com.example.MyClass。

以下範例說明如何納入及排除特定套件：

Kotlin

baselineProfile {
    filter {
        include("com.somelibrary.widget.grid.**")
        exclude("com.somelibrary.widget.grid.debug.**")
        include("com.somelibrary.widget.list.**")
        exclude("com.somelibrary.widget.list.debug.**")
        include("com.somelibrary.widget.text.**")
        exclude("com.somelibrary.widget.text.debug.**")
    }
}

Groovy

baselineProfile {
    filter {
        include 'com.somelibrary.widget.grid.**'
        exclude 'com.somelibrary.widget.grid.debug.**'
        include 'com.somelibrary.widget.list.**'
        exclude 'com.somelibrary.widget.list.debug.**'
        include 'com.somelibrary.widget.text.**'
        exclude 'com.somelibrary.widget.text.debug.**'
    }
}

您可以為不同的變化版本自訂篩選器規則，如下所示：

Kotlin

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include("com.myapp.**") }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include("com.myapp.free.**")
            }
        }
        paid {
            filter {
                include("com.myapp.paid.**")
            }
        }
    }
}

// Build-type-specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

Groovy

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include 'com.myapp.**' }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include 'com.myapp.free.**'
            }
        }
        paid {
            filter {
                include 'com.myapp.paid.**'
            }
        }
    }
}

// Build-type specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

您也可以透過 BaselineProfileRule.collect() 中的 filterPredicate 引數篩選規則，但我們建議您利用 Gradle 外掛程式篩選，因為這樣較容易篩選子套件，且能集中設定整個模組。

自訂基準測試和基準設定檔的建構類型

基準設定檔 Gradle 外掛程式會建立其他建構類型，以便產生設定檔和執行基準測試。這些建構類型的前置字串為 benchmark 和 nonMinified。舉例來說，對於 release 建構類型，外掛程式會建立 benchmarkRelease 和 nonMinifiedRelease 建構類型。這些建構類型會根據特定用途自動設定，通常不需要任何自訂設定。不過，在某些情況下，套用部分自訂選項可能仍有用處，例如套用不同的簽署設定。

您可以使用建構類型屬性子集自訂自動產生的建構類型，無法使用的屬性會遭到覆寫。以下範例說明如何自訂其他建構類型，以及要覆寫哪些屬性：

Kotlin

android {
    buildTypes {
        release {
            ...
        }
        create("benchmarkRelease") {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default
            // it's the same as for the `release` build type).
            signingConfig = signingConfigs.getByName("benchmarkRelease")
        }
        create("nonMinifiedRelease") {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.getByName("nonMinifiedRelease")

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't
            // customize the following properties, which are always overridden to
            // avoid breaking Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            ...
        }
        benchmarkRelease {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default it's the
            // same as for the `release` build type.)
            signingConfig = signingConfigs.benchmarkRelease
        }
        nonMinifiedRelease {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.nonMinifiedRelease

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't use
            // the following properties, which are always overridden to avoid breaking
            // Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false       
        }
    }
}

其他注意事項

建立基準設定檔時，您還需要注意下列幾點：

「編譯」後的基準設定檔必須小於 1.5 MB。這項限制不適用於來源檔案中的文字格式，這類檔案在編譯前通常較大。請確認二進位基準設定檔的大小，方法是在輸出構件中找到相對應的檔案，比如 APK 的檔案位於 assets/dexopt/baseline.prof 底下，AAB 的檔案則位於 BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof 底下。

提示：在 Android Studio Flamingo (2022.2.1) 以上版本中，請使用 APK 分析工具驗證設定檔大小。
如果廣泛規則對應用程式過度編譯，啟動速度會因為磁碟存取量變大而降低。如果您才剛開始使用基準設定檔，可以不必擔心這種情況。然而，視應用程式本身、歷程大小和歷程數量而定，新增大量歷程可能會降低效能。請測試應用程式效能，方法為嘗試運用不同的設定檔，並驗證效能不會在新增歷程後降低。

程式碼研究室

使用 Macrobenchmark 檢查應用程式效能

深入瞭解如何使用 Macrobenchmark 評估效能。

瞭解詳情

使用基準設定檔改善應用程式效能

產生專為 Android 應用程式建立的自訂基準設定檔，並驗證有效性。

瞭解詳情

為程式庫建立基準設定檔

使用 Macrobenchmark 程式庫進行評估