Android Developers:ProGuard

ProGuard工具通過刪除未使用的代碼，使用語義模糊的名字重命名類、字段和方法的方式，減少、優化和混淆你的代碼。結果生成一個更小的，更難被反向工程的.apk文件。因為ProGuard使你的應用程序更難反向工程，當你發布的應用程序使用對安全敏感功能的時候，使用它尤為重要。

ProGuard已經被集成到Android的構建系統中，所以你不需要手動的調用它。ProGuard僅僅當你在release模式構建你的應用程序時運行，所以你不需要在Debug模式的時候處理被混淆的代碼。運行ProGuard是完全可選的，但是強烈推薦。

這個文檔描述了如何啟動和配置ProGuard，以及使用retrace工具解碼被混淆的堆棧跟蹤。

啟動ProGuard

————————————————————————————————————————————————————————————

當你創建一個Android項目，在項目的根目錄下自動生成一個proguard.cfg文件。這個文件定義了ProGuard如何優化和混淆你的代碼，所以你知道如何根據你的需要定制它是非常重要的。默認的配置文件僅僅涵蓋一般情況，所以你很可能為了你自己的需求必須編輯它。閱讀下面Configuring ProGuard的章節了解定制ProGuard配置文件的信息。

為了啟動ProGuard使它作為Ant或者Eclipse構建的一部分，設置/project.properties文件中的proguard.config屬性。這個路徑可以是絕對路徑或者一個相對項目根目錄的路徑。

注意：當使用Android Studio，你必須向你的gradle.build文件添加構建類型。更多信息，查閱Gradle Plug User Guid。

如果你放置proguard.cfg文件在它的默認位置（項目的跟目錄），你像這樣指定它的位置：

proguard.config=proguard.cfg

你也能將文件移動到任意你想要的位置，並且指定它的絕對路徑：

proguard.config=/path/to/proguard.cfg

當你以Release模式構建你的應用程序，通過運行ant發布或者通過使用Eclipse的導出向導，構建系統自動檢查是否proguard.config屬性是否設置。如果它設置了，ProGuard在把所有東西打包到.apk文件之前自動處理應用程序字節碼。在Debug模式不調用ProGuard，以為它使得調試更難處理。

在ProGuard運行後輸出下面的文件：

dump.txt

描述了在apk文件所有class文件的內部結構

mapping.txt
列出了原始和被混淆類，方法和成員之間名稱的映射。這個文件當你從release構建收到Bug報告的時候非常重要，因為它將混淆的堆棧轉義回原來的類，方法，和成員名稱。更多信息查閱Decoding Obfuscated Stack Traces。

seeds.txt
列出了沒有被混淆的類和成員。

usage.txt
列出了從.apk被刪除的代碼

這些文件被放置在下面的目錄：

• /bin/proguard如果你使用Ant。

• /proguard如果你使用Eclipse。

  注意：每次你在release模式運行一次構建，這些文件都被ProGuard最新生成的文件覆蓋。每次你發布你的應用程序保存它們的復本，為了從你的release構建反混淆Bug報告。更多關於為什麼保存這些文件是重要的信息，查看Debugging considerations for published applications。

  配置ProGuard

  —————————————————————————————————————————————————————————————

  對於一些情況，在proguard.cfg文件中的默認配置將足夠了。然而，很多情況下ProGuard很難分析正確，並且它可能移除它認為沒有被使用的代碼，但是你的應用程序實際上需要。這些情況包括：

  • 僅僅在AndroidManifest.xml文件引用的類

  • 在JNI被調用的方法

  • 動態引用的文件和方法

    默認的proguard.cfg文件試圖覆蓋一般情況，但是你可能遇到異常，例如ClassNotFoundException，當ProGuard刪除你的應用程序調用的一個整個類時發生。

    當ProGuard刪除你的代碼的時候，你能通過在proguard.cfg文件中添加一個-keep行來解決這個錯誤。例如：

    -keep public class

    當使用-keep選項的時候有許多選項和注意事項，所以它強烈要求你閱讀ProGuard Manual關於自定義你的配置文件的信息。Keep選項概覽和Examples章節尤其有幫助。ProGuard手冊的Troubleshooting章節概述了當你的代碼被刪除的時候可能遇見的其它問題 。

    解碼混淆棧跟蹤

    —————————————————————————————————————————————————————————————

    當你的被混淆的代碼輸出一個堆棧跟蹤的時候，這個方法名稱被混淆了，如果不是不可能的話，它也使得調試更難。幸運的是，每當ProGuard運行的時候，它輸出一個/bin/proguard/mapping.txt文件，它顯示了你的原始類，方法，和成員名稱映射到它們的被混淆的名稱。

    在Window上的retract.bat腳本或者在Linux或者Mac OS X的retrace.sh腳本，能將被混淆的堆棧轉換成可讀的。它被放置在/tools/proguard/目錄。運行retract工具的語法是：

    retrace.bat|retrace.sh [-verbose] mapping.txt []

    例如：

    retrace.bat -verbose mapping.txt obfuscated_trace.txt

    如果你沒有指定值，retrace工具從標准輸入讀取。

    發布程序調試注意事項

    保存每次你給你的用戶發布應用的mapping.txt文件。通過保留每次release構建的mapping.txt的復本，你確保了如果用戶遭遇到了一個Bug，你能調試問題，並且提交一個混淆過的堆棧跟蹤。項目的mapping.txt文件在你每次執行一個release構建的時候被覆蓋，所以你必須小心保存你需要的版本。

    例如，你發布應用程序，繼續開發應用程序新版本的新功能。然後你不久後使用ProGuard執行新的release構建。這次構建覆蓋了前面的mapping.txt文件。用戶提交了從來自當前發布的應用程序Bug報告，包含棧跟蹤信息。你不能在你的應用程序中調試用戶的棧跟蹤信息，因為和這個版本相關的mapping.txt文件在用戶的設備上不存在了。還有其它的情況你的mapping.txt文件能被覆蓋，所以確保你為你預測需要測試的每一個版本保存一個副本。

    如何保存這個mapping.txt文件你來決定。例如，你能重命名它們來包含版本或者構建號，或者你可以和你的源代碼一起對它們進行版本控制。