使用 R8 設定分析器

R8 設定分析器這項工具可提供應用程式設定品質的詳細洞察資料，協助您充分發揮 R8 的效能優勢。您可以監控縮減、最佳化和模糊化分數等重要指標，藉此追蹤及改善 R8 最佳化作業。這些分數代表可供最佳化的程式碼集百分比。分析器會找出廣泛或不必要的保留規則 (包括第三方程式庫導入的規則)，協助您修正設定，確保 R8 盡可能有效最佳化類別、欄位和方法。

產生報表

使用 AGP 9.3.0 以上版本時，您可以透過專屬的獨立 Gradle 工作產生 R8 設定分析器報表，或在 R8 建構期間自動產生。

執行獨立的 Gradle 工作 (建議用於本機)

積極疊代保留規則時，請使用獨立的 Gradle 工作，快速評估變更的影響，不必完整建構 APK 或套件：

./gradlew :app:analyzeReleaseR8Config

由於這項工作會略過 APK 或套件產生作業，因此意見回饋循環時間會大幅縮短。您可以快速分析保留規則對縮減、最佳化和模糊處理分數的影響，並立即進行調整。HTML 報表會在 app/build/reports/r8/r8-config-analyzer-release.html 產生。

在一般建構期間自動產生

執行完整的 R8 發布版本建構作業 (例如 assembleRelease) 時，系統會自動在 build/outputs/mapping/release/configanalyzer.html 產生報表。如要在一般建構作業期間停用自動產生輸出內容的功能，請設定下列 Gradle 屬性：

android.experimental.r8.enableR8ConfigurationAnalyzer=false

適用於 AGP 9.2 以下版本

如果是 AGP 9.2 以上版本，請在執行 Gradle 工作時設定 com.android.tools.r8.dumpkeepradiushtmltodirectory 系統屬性，並啟用 R8 建構。

./gradlew assembleRelease \
    -Dcom.android.tools.r8.dumpkeepradiushtmltodirectory=<output_directory>

舉例來說，使用下列指令在 /tmp/r8analysis 目錄中產生 HTML 報表：

# To create the /tmp/r8analysis folder.
mkdir -p /tmp/r8analysis

# To generate the report in the /tmp/r8analysis folder.
./gradlew assembleRelease \
    -Dcom.android.tools.r8.dumpkeepradiushtmltodirectory=/tmp/r8analysis

解讀報表

R8 設定分析器可深入瞭解應用程式的 R8 設定，以及每項保留規則對應用程式的影響，協助您充分發揮 R8 的最佳化功能，進而提升應用程式效能。您可以根據下列分數，瞭解 R8 可最佳化的程式碼集比例。

縮減分數

R8 縮減應用程式時，會找出並移除未使用的程式碼和資源，盡可能縮減最終建構版本的大小。縮減分數會追蹤可縮減的類別、欄位和方法百分比。舉例來說，如果縮減分數為 66%，表示 R8 可以在 66% 的程式碼集中執行縮減作業。

最佳化分數

R8 會執行方法內嵌和類別合併等最佳化作業，進而提升應用程式的啟動速度和記憶體效率。最佳化分數會追蹤受 R8 最佳化作業影響的類別、欄位和方法百分比。舉例來說，如果最佳化分數為 66%，表示 R8 只能在 66% 的程式碼集執行最佳化。

模糊化分數

R8 會將類別、欄位和方法模糊處理為較短的名稱，藉此縮減應用程式的中繼資料用量，節省記憶體。混淆分數會評估程式碼集中可混淆處理的程式碼百分比。

調整保留規則

如要提高分數並解鎖更完善的 R8 最佳化功能，請調整保留規則，避免 R8 不必要地無法最佳化應用程式。您應只保留透過反射存取的類別、方法或欄位。

如要達成此目標，請使用「保留規則分析」。

如要查看規則的詳細分析，請點選規則開啟詳細資料畫面。

如何調整保留規則

如要調整保留規則，充分發揮 R8 最佳化功能對應用程式的效益，請按照下列步驟操作：

1. 在「設定分析器」中，查看每個保留規則無法由 R8 最佳化的類別、欄位和方法百分比。您可以使用這項功能，找出大量類別、欄位或方法中，導致無法最佳化的保留規則。系統也會列出各項保留規則禁止的最佳化屬性。
2. 如果發現有保留規則導致大量類別無法最佳化，請務必檢查保留規則禁止最佳化的類別、欄位和方法，確認這項規則是否保留了未使用反映動態叫用的項目。
3. 如要減少因保留規則而遭到封鎖的最佳化作業，請選擇合適的保留選項，並遵循最佳做法，只指定必要的類別、欄位或方法。
4. 調查並執行涵蓋受影響類別、欄位和保留規則方法的測試，然後修正保留規則。

檢查程式庫最佳化程度

整合第三方程式庫時，這些程式庫通常會包含自己的消費者保留規則，以便與 R8 搭配運作。由於程式庫作者無法預測您的具體實作方式，他們有時會編寫保守且適用範圍廣泛的規則，導致不必要的類別、欄位和方法遭到最佳化。這可能會導致 R8 無法最佳化與程式庫實際執行階段無關的應用程式部分。您可以使用 R8 設定分析器，找出導入規則的程式庫，這些規則會對應用程式的最佳化作業造成負面影響。

使用設定分析器檢查所有合併的消費者保留規則，瞭解這些規則的綜合影響。分析第三方程式庫中每項保留規則的影響，找出並追蹤導致應用程式無法大幅最佳化的特定第三方程式庫。

如何最佳化程式庫

如要解決第三方程式庫導入的保留規則，請按照下列步驟操作：

• 如果程式庫包含過於寬鬆的規則，建議您提供報表中的資料，向程式庫維護人員說明目前的規則如何影響應用程式的優化分數，如果是外部程式庫，請先在程式庫中尋找現有錯誤，再提出問題。
• 如有需要，您可以從特定程式庫中篩除規則，測試潛在的改善項目。您可以將程式庫的規則匯入專案、排除廣泛規則，然後重新執行設定分析器，評估大小和效能的潛在增益。

併入的規則

如果多個保留規則重疊，其中一項規則可能會導致系統無法進行必要的最佳化。如果程式碼集中有兩項保留規則。

# Prevents optimization in the entire package
# Remove this to improve optimization
-keep class com.example.package.** { *; }

# Prevents optimization to the class inside the package
-keep class com.example.package.Myclass

第一個保留規則會防止整個套件進行最佳化，並涵蓋第二個保留規則，後者則是以第一個保留規則保留的套件內類別為目標。如果保留規則重疊，可能會阻礙過多最佳化作業。修正這些重疊規則，即可盡量提升 R8 最佳化成效，並消除技術債。這個程序包括簡化設定，確保只保留必要程式碼，同時充分發揮 R8 的最佳化功能。

最佳化涵蓋規則

1. 使用 R8 設定分析工具找出 subsuming keep 規則。
2. 找出程式碼集內實際依附於反射的確切類別、欄位或方法，這些項目需要使用保留規則保留。瞭解這點有助於調整保留規則。
3. 使用設定分析器，比較以相同類別、欄位或方法為目標的各項規則所造成的影響。您可以根據每項保留規則避免的優化百分比，判斷保留規則的範圍較廣或較窄。
   1. 如果窄規則編寫精確，只保留以反射方式存取的確切成員或類別，請移除較廣泛的保留規則。這項操作可安全地為套件的其餘部分解鎖 R8 最佳化功能。
   2. 如果廣泛規則指定的是正確的類別，請保留廣泛規則並刪除精細規則。窄版規則只是多餘的雜亂內容。 請務必修正廣泛規則，只指定您識別出的類別、欄位或方法。

驗證及測試變更：重新執行設定分析器，確保衝突已修正。接著，編譯發布版本並測試變更，確保程式碼集正常運作。

移除不必要的規則

您可以使用設定分析工具，有系統地稽核程式碼集，找出並刪除造成設定混亂的過時保留規則。R8 設定分析器會特別標示不必要規則的兩個主要來源：

• 未使用的規則：在目前的建構作業中，與零個類別、方法或欄位相符的規則。這些設定通常會在程式碼重構、移除依附元件後保留，或是從不再相關的複製貼上設定中保留，進而增加不必要的設定複雜度。
• 相同規則：相同保留規則是指目標為相同類別、欄位和方法的規則，或是在相同或不同保留規則檔案中重複宣告的保留規則。

這兩種規則都會讓設定變得雜亂，更難維護和偵錯。找出這些項目後，即可清除設定。