AAPT2

AAPT2 (Android 資產封裝工具) 是 Android Studio 和 Android Gradle 外掛程式用來編譯及封裝應用程式資源的一項建構工具。AAPT2 會剖析資源、建立索引，並將資源編譯為適用於 Android 平台的二進位格式。

Android Gradle 外掛程式 3.0.0 以上版本預設會啟用 AAPT2。您通常不需要自行叫用 aapt2。不過，如果您想要使用終端機和自己的建構系統，而不是 Android Studio，則可透過指令列使用 AAPT2。您也可以透過指令列，針對與 AAPT2 相關的建構錯誤進行偵錯。方法很簡單，在 Android SDK Build Tools 26.0.2 以上版本中，找出 AAPT2 這個獨立工具。

如要從指令列下載 Android SDK Build Tools，請使用 sdkmanager 並執行以下指令：

sdkmanager "build-tools;build-tools-version"

下載 SDK Build Tools 後，在 android_sdk/build-tools/version/ 中可以找到 AAPT2。

由於 Android SDK Build Tools 的修訂版本不會經常發布，因此您 SDK Build Tools 中的 AAPT2 可能不是最新版。如要取得最新版的 AAPT2，請參閱「前往 Google Maven 下載 AAPT2」。

如要透過 Linux 或 Mac 指令列使用 AAPT2，請執行 aapt2 指令。在 Windows 上執行 aapt2.exe 指令。

AAPT2 可讓您啟用漸進式編譯功能，讓資源編譯速度更快。為了完成漸進式編譯，資源處理會分為兩個步驟：

• 編譯：將資源檔案編譯為二進位格式。
• 連結：將所有已編譯的檔案與套件合併成一個套件。

這種劃分有助提升漸進式建構的效能。舉例來說，如果單一檔案發生變更，您只需要重新編譯該檔案。

前往 Google Maven 下載 AAPT2

如要取得建構工具中未搭售的最新版 AAPT2，可以從 Google Maven 存放區下載 AAPT2，方法如下：

1. 在存放區索引中，前往 com.android.tools.build > aapt2。
2. 複製最新版 AAPT2 的名稱。

3. 請將您複製的版本名稱貼到以下網址中，並指定目標作業系統：https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version- [windows | linux | osx].jar

   例如，如要下載 Windows 3.2.0-alpha18-4804415 版本，請使用以下這個檔案：https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

4. 使用瀏覽器開啟上面的網址後，很快就會開始下載 AAPT2。

5. 解壓縮您剛下載的 JAR 檔案。

   JAR 檔案應包含 aapt2 執行檔，以及執行檔需要的程式庫。

編譯

AAPT2 支援所有 Android 資源類型的編譯作業，例如可繪項目和 XML 檔案。叫用 AAPT2 編譯時，請將單一資源檔案當成每次叫用的輸入內容傳遞。AAPT2 會剖析檔案，並產生副檔名為 .flat 的中繼二進位檔案。

傳遞完整目錄時，AAPT2 會重新編譯目錄中的所有檔案，即使只有一項資源變更也一樣。雖然您可以使用 --dir 旗標，將包含多個資源檔案的資源目錄傳遞給 AAPT2，但這種做法並不會讓您取得增量資源編譯的優勢。

視您提供編譯的輸入內容而定，輸出檔案類型可能不同，如下表所示：

表 1. 編譯的輸入和輸出檔案類型。

AAPT2 輸出的檔案不是執行檔，因此您必須在之後的連結階段加入這些二進位檔案才能產生 APK。不過，產生的 APK 檔案並非可立即部署於 Android 裝置上的執行檔，因為該檔案並未包含 DEX 檔案且未經簽署。

編譯語法

使用 compile 的一般語法如下：

aapt2 compile path-to-input-files [options] -o output-directory/

在下列範例中，AAPT2 會個別編譯名為 values.xml 和 myImage.png 的資源檔案：

aapt2 compile project_root/module_root/src/main/res/values-en/strings.xml -o compiled/
aapt2 compile project_root/module_root/src/main/res/drawable/myImage.png -o compiled/

如表 1 所示，輸出檔案的名稱取決於輸入檔案名稱及其父項目錄的名稱。

以上述 strings.xml 檔案做為輸入範例，aapt2 會自動將輸出檔案命名為 values-en_strings.arsc.flat。但如果是儲存在可繪項目目錄中的已編譯可繪項目檔案，名稱會是 drawable_img.png.flat。

編譯選項

您可以透過 compile 指令使用多個選項，如表 2 所示：

表 2. 編譯指令選項

連結

在連結階段，AAPT2 會將從編譯階段產生的所有中繼檔案合併，例如資源資料表、二進位 XML 檔案，以及已處理的 PNG 檔案，並將這些檔案封裝為單一 APK。此外，在這個階段會產生其他輔助檔案 (例如 R.java 和 ProGuard 規則檔案)。不過，產生的 APK 不包含 DEX 位元碼，且未簽署。您無法將這個 APK 部署至裝置。

如果您不是使用 Android Gradle 外掛程式透過指令列建構應用程式，則可使用其他指令列工具，例如 d8，將 Java 位元碼編譯成 DEX 位元碼，再使用 apksigner 簽署您的 APK。

連結語法

使用 link 的一般語法如下：

aapt2 link path-to-input-files [options] -o
outputdirectory/outputfilename.apk --manifest AndroidManifest.xml

在以下範例中，AAPT2 合併了兩個中繼檔案：drawable_Image.flat 和 values_values.arsc.flat，以及 AndroidManifest.xml 檔案。AAPT2 會將結果與 android.jar 檔案連結，該檔案保存了 android 套件中定義的資源：

 aapt2 link -o output.apk
 -I android_sdk/platforms/android_version/android.jar
    compiled/res/values_values.arsc.flat
    compiled/res/drawable_Image.flat --manifest /path/to/AndroidManifest.xml -v

連結選項

您可以搭配 link 指令使用下列選項：

表 3. 連結指令選項

傾印

dump 是用來列印使用 link 指令產生的 APK 相關資訊。

傾印語法

使用 dump 的一般語法如下：

aapt2 dump sub-command filename.apk [options]

下列範例會列印指定 APK 資源資料表的內容：

aapt2 dump resources output.apk

傾印子指令

使用 dump 指令指定下列其中一個子指令：

表 4. 傾印子指令

傾印選項

請搭配 dump 使用下列選項：

表 5. 傾印選項

差異比較

使用 diff 比較兩個 APK，並找出兩者之間的差異。

差異比較語法

使用 diff 的一般語法如下：

aapt2 diff first.apk second.apk

沒有 diff 指令可用的選項。

盡力改善

optimize 用於在合併的資源和 resources.arsc 上執行最佳化，然後再將套件封裝至 APK。根據使用資源大小和數量，這項最佳化可縮減 APK 的大小約 1-3%。

最佳化語法

使用 optimize 的一般語法如下：

aapt2 optimize options file[,file[..]]

下列範例會最佳化 input.apk 中的資源，並在 output.apk 中建立新的最佳化 APK。這樣做可將一般的二維資料表呈現為更精簡的二進位搜尋樹狀圖，進而產生較小的 APK，但擷取效能也會隨之降低：

aapt2 optimize -o output.apk --enable-sparse-encoding input.apk

最佳化選項

下列選項可與 optimize 搭配使用：

表 6. 最佳化選項

轉換

根據預設，AAPT compile 指令會將資源編譯成適合 APK 的二進位格式。您也可以指定 --proto-format，藉此來指定適合 AAB 的 protobuf 格式。convert 指令會在這兩種格式之間轉換 APK。

轉換語法

使用 convert 的一般語法如下：

aapt2 convert -o output-file options file[,file[..]]

下列範例會轉換 input.apk 中的資源，並在 output.apk 中建立包含 protobuf 格式資源的新 APK。這樣做可將一般的二維資料表呈現為更精簡的二進位搜尋樹狀圖，進而產生較小的 APK，但擷取效能也會隨之降低：

aapt2 convert -o output.apk --output-format proto --enable-sparse-encoding input.apk

轉換選項

請搭配 convert 使用下列選項：

表 7. 轉換選項

Daemon 模式

AAPT 2.19 版推出 Daemon 模式，可用於發出指令。Daemon 模式可讓您在單一 AAPT 工作階段輸入多個指令。

Daemon 語法

使用下列指令啟動 Daemon 模式：

aapt2 daemon

在 Daemon 模式執行後，您可以輸入指令。指令中的每個引數必須分行列出，並在指令結尾使用空白行。鍵入 Control+D 即可退出 Daemon 模式。

請考慮使用下列個別的 compile 指令：

aapt2 compile project_root/module_root/src/main/res/values-en/strings.xml -o compiled/
aapt2 compile project_root/module_root/src/main/res/drawable/myImage.png -o compiled/

這些指令可在 Daemon 模式下輸入，如下所示：

aapt2 daemon
Ready
compile
project_root/module_root/src/main/res/values-en/strings.xml
-o
compiled/

Done
compile
project_root/module_root/src/main/res/drawable/myImage.png
-o
compiled/

Done
^D
Exiting daemon

Daemon 模式選項

Daemon 模式的單一選項是 --trace-folder folder，這會向指定的 folder 產生 systrace JSON 追蹤記錄片段。

版本

確定您要透過 version 指令使用的 AAPT2 版本：

aapt2 version
Android Asset Packaging Tool (aapt) 2.19-8678579

使用 AAPT2 時的行為改變

在 AAPT2 之前，AAPT 是 Android 資產封裝工具的預設版本，現已淘汰。雖然 AAPT2 應立即處理舊版專案，但本節將說明您應注意的部分行為改變。

Android 資訊清單中的元素階層

在舊版 AAPT 中，AndroidManifest.xml 檔案中錯誤節點銜接的元素遭到忽略或導致警告。例如，請看以下範例：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.myname.myapplication">
   <application
       ...
       <activity android:name=".MainActivity">
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
           <action android:name="android.intent.action.CUSTOM" />
       </activity>
   </application>
</manifest>

舊版 AAPT 只會忽略錯誤的 <action> 標記。

使用 AAPT2 時，系統會顯示下列錯誤：

AndroidManifest.xml:15: error: unknown element <action> found.

如要解決這個問題，請確認您的資訊清單元素正確銜接。詳情請參閱「應用程式資訊清單總覽」。

資源宣告

您無法再從 name 屬性表示資源類型。下列範例未正確宣告 attr 資源項目：

<style name="childStyle" parent="parentStyle">
    <item name="attr/my_attr">@color/pink</item>
</style>

以這種方式宣告資源類型會導致下列建構錯誤：

Error: style attribute 'attr/attr/my_attr (aka my.package:attr/attr/my_attr)'
not found.

如要解決這個錯誤，請使用 type="attr" 明確宣告類型：

<style name="childStyle" parent="parentStyle">
  <item type="attr" name="my_attr">@color/pink</item>
</style>

此外，在宣告 <style> 元素時，其父項也必須是樣式資源類型。否則，您會收到類似下列內容的錯誤：

Error: (...) invalid resource type 'attr' for parent of style

未正確使用 @ 資源參考符號

AAPT2 會在您省略或錯誤放置資源參照符號 (@) 時擲回建構錯誤。例如，如果您在指定樣式屬性時省略符號：

<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
  ...
  <!-- Note the missing '@' symbol when specifying the resource type. -->
  <item name="colorPrimary">color/colorPrimary</item>
</style>

建構模組時，AAPT2 會擲回下列建構錯誤：

ERROR: expected color but got (raw string) color/colorPrimary

此外，如果您從 android 命名空間存取資源時錯誤加入符號：

...
<!-- When referencing resources from the 'android' namespace, omit the '@' symbol. -->
<item name="@android:windowEnterAnimation"/>

建構模組時，AAPT2 會擲回下列建構錯誤：

Error: style attribute '@android:attr/windowEnterAnimation' not found

資料庫設定有誤

如果您的應用程式含有舊版 Android SDK Build Tools 建構第三方程式庫的依附元件，則該應用程式可能會在執行階段異常終止，且不會顯示任何錯誤或警告。這個異常終止情況的可能原因為，在程式庫建立期間，R.java 欄位會宣告 final。因此，所有資源 ID 都會內嵌至該程式庫的類別中。

AAPT2 仰賴在建立應用程式時，能將 ID 重新指派給程式庫資源的動作。如果程式庫假設 ID 是 final，且在資料庫 DEX 中內嵌這些 ID，則系統會發生執行階段不符的情形。

如要解決這個錯誤，請與程式庫作者聯絡，以使用最新版 Android SDK Build Tools 重新建構程式庫，然後重新發布程式庫。