android 混淆器(ProGuard)

前言

本章内容为开发者指南(Dev Guide)/Developing/Tools/ProGuard，本章内容为"混淆器"，版本为Android3.0 r1，翻译来自："Jim"，欢迎与他交流："[e-mail]"，再次感谢"Jim" ！。

声明

　　欢迎转载，但请保留文章原始出处:)

　　　　JavaEye社区：http://www.iteye.com

Android中文翻译组：http://goo.gl/6vJQl

原文

http://developer.android.com/guide/developing/tools/proguard.html

混淆器(ProGuard)

　　在本文中(In this document)

　　　　Enabling ProGuard

　　　　Configuring ProGuard

　　　　Decoding Obfuscated Stack Traces

　　　　　　Debugging considerations for published applications

　　参见

　　　　ProGuard Manual ?

　　　　ProGuard ReTrace Manual ?

混淆器通过删除从未用过的代码和使用晦涩名字重命名类、字段和方法，对代码进行压缩，优化和混淆。结果是一个比较小的.apk文件，该文件比较难进行逆向工程。因此，当你的应用程序对安全敏感（要求高），例如当你授权应用程序的时候，混淆器是一种重要的保护手段。

混淆器被集成在android构建系统中，所以你不必手动调用它。同时混淆器仅在发布模式下进行构建应用程序的时候才会运行起来，所以在调试模式下构建程序时，你不必处理混淆代码。让混淆器运行起来是可选择的，但是推荐选上。

这个文档描述了怎样启用并配置混淆器，以及使用跟踪（retrace）工具对混淆的堆栈跟踪信息（stack traces）进行解码。

启用混淆器Enabling ProGuard

当你新建了一个Android工程之后，一个proguard.cfg文件会在工程的根目录下自动创建。这个文件定义了混淆器是怎样优化和混淆你的代码的，所以懂得怎样根据你的需要来定制是非常重要的。缺省的配置文件仅覆盖到了通常情况，所以根据你的需求，很可能需要编辑它。接下来的内容是关于通过定制混淆器配置文件来对混淆器配置。

为了让启用混淆器作为Ant或者Eclipse构建过程中一部分，可以在<project_root>/default.properties文件中，设置proguard.config属性。路径可以是绝对路径或者工程根目录的相对路径。

如果你让proguard.cfg文件在缺省位置（工程的根目录），你可以像这样指定位置：

proguard.config=proguard.cfg

同样，你可以把该文件放到任意的位置，并指定它的绝对路径。

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

当你在发布模式下，或者通过运行ant release，或者通过使用Eclipse中的Export Wizard构建你的应用程序的时候，构建系统都会自动地去检查proguard.config属性是否被设置了。如果被设置了，混淆器在把所有东西打包成.apk文件之前，自动地对应用程序字节码进行混淆处理。而在调试模式中构建则不会调用混淆器，因为那样调试会更加繁重。

运行混淆器之后输出的文件有：

dump.txt

描述.apk包中所有class文件的内部结构。

mapping.txt

列出了源代码与混淆后的类，方法和属性名字之间的映射。这个文件对于在构建之后得到的bug报告是有用的，因为它把混淆的堆栈跟踪信息反翻译为源代码中的类，方法和成员名字。更多信息，查看解码混淆过的堆栈跟踪信息。

seeds.txt

列出那些未混淆的类和成员。

usage.txt

列出从.apk中剥离的代码。

这些文件放在以下目录中：

l<project_root>/bin/proguard当你使用Ant时

l<project_root>/proguard当你使用Eclipse时

注意：每次在发布模式下构建时，这些文件都会被最新的文件覆盖。所以每次发布程序时候，为了反混淆来自构建时产生的bug报告，请保存这些文件的一个拷贝。对于为什么要保存这些文件的重要性的更多信息，请查看程序发布调试注意事项。

混淆器配置(Configuring ProGuard)

某些情况下，proguard.cfg文件的缺省配置可以满足需求了。但是，对于混淆器来说，大多数情况做出正确的分析是困难的，并且它或许会删除在它看来是无用的，但对于程序来说却确实需要的代码。一些例子如下：

l一个仅引用于AndroidManifest.xml文件的类。

l一个通过JNI调用的方法。

l动态引用的属性和方法。

缺省的proguard.cfg文件试图覆盖普通的情况，但是你可能碰到类似ClassNotFoundException的异常，这个异常出现在当你的程序去访问一个被混淆器移除了的类的时候。

你可以在proguard.cfg文件中添加-keep这一行来修复这些错误。例如：

-keeppublicclass<MyClass>

-Keep设置有很多可选项和注意地方，所以为了获得更多关于配置信息，强烈推荐你阅读混淆器用户手册。特别有用的有Keep选项综述和举例部分。在混淆器手册问题解决方案部分，介绍了代码在混淆过程中你可能碰到的其他常见问题。

解码混淆过的堆栈跟踪信息(Decoding Obfuscated Stack Traces)

当混淆代码并输出了一个堆栈调试信息时，这些方法名字是混淆过的，虽然可以进行调试，但是调试变得困难。幸运的是，每当混淆器运行时候，它都会输出到文件<project_root>/bin/proguard/mapping.txt中，该文件包含了从原始类，方法和属性名字到混淆后名字的映射。

Windows系统中retrace.bat脚本命令或者Linux和Mac OS X系统中retrace.sh脚本命令能把混淆后的堆栈调试信息转换为可以理解的文件。它被放在<sdk_root>/tools/proguard/目录下。运行retrace工具的命令语法是：

retrace.bat|retrace.sh[-verbose]mapping.txt[<stacktrace_file>]

例如：

retrace.bat-verbose mapping.txt obfuscated_trace.txt

如果你没有为<stracktrace_file>指定值，那么retrace工具从标准输入读取。

已发布应用程序的调试注意事项(Debugging considerations for published applications)

保存好每一个已发布给用户的程序的mapping.txt文件。通过保存发布构建版本的mapping.txt文件拷贝，确保当用户碰到bug，并把混淆后的堆栈调试跟踪信息提交给你时，你可以进行调试从而修复问题。程序的mapping.txt文件在每次发布构建时都会被覆盖，所以你一定要注意保存正确的版本。

例如，假设你已经发布了一个应用程序并在继续在新的版本中开发添加新的功能。接着你马上启动混淆器并创建一个新的发布版本。该操作把mapping.txt文件覆盖了。一个用户提交了来自当前发布版本的bug报告，该报告包含了堆栈调试信息。你再也不能对用户的堆栈信息进行调试了，因为这个对应用户本机上版本的mapping.txt文件不存在了。其他覆盖mapping.txt文件的情况还有很多，所以对于每一个可能需要调试的版本，你都要确保有一份拷贝。

如何保存mapping.txt文件由你决定。例如，你可以根据版本和构建号来重命名它们，或者连同你的源代码进行版本控制。

另一篇文章：

参数：

-include {filename} 从给定的文件中读取配置参数

-basedirectory {directoryname} 指定基础目录为以后相对的档案名称

-injars {class_path} 指定要处理的应用程序jar,war,ear和目录

-outjars {class_path} 指定处理完后要输出的jar,war,ear和目录的名称

-libraryjars {classpath} 指定要处理的应用程序jar,war,ear和目录所需要的程序库文件

-dontskipnonpubliclibraryclasses 指定不去忽略非公共的库类。

-dontskipnonpubliclibraryclassmembers 指定不去忽略包可见的库类的成员。


保留选项
-keep {Modifier} {class_specification} 保护指定的类文件和类的成员

-keepclassmembers {modifier} {class_specification} 保护指定类的成员，如果此类受到保护他们会保护的更好

-keepclasseswithmembers {class_specification} 保护指定的类和类的成员，但条件是所有指定的类和类成员是要存在。

-keepnames {class_specification} 保护指定的类和类的成员的名称（如果他们不会压缩步骤中删除）

-keepclassmembernames {class_specification} 保护指定的类的成员的名称（如果他们不会压缩步骤中删除）

-keepclasseswithmembernames {class_specification} 保护指定的类和类的成员的名称，如果所有指定的类成员出席（在压缩步骤之后）

-printseeds {filename} 列出类和类的成员-keep选项的清单，标准输出到给定的文件

压缩
-dontshrink 不压缩输入的类文件

-printusage {filename}

-whyareyoukeeping {class_specification}

优化
-dontoptimize 不优化输入的类文件

-assumenosideeffects {class_specification} 优化时假设指定的方法，没有任何副作用

-allowaccessmodification 优化时允许访问并修改有修饰符的类和类的成员

混淆
-dontobfuscate 不混淆输入的类文件

-printmapping {filename}

-applymapping {filename} 重用映射增加混淆

-obfuscationdictionary {filename} 使用给定文件中的关键字作为要混淆方法的名称

-overloadaggressively 混淆时应用侵入式重载

-useuniqueclassmembernames 确定统一的混淆类的成员名称来增加混淆

-flattenpackagehierarchy {package_name} 重新包装所有重命名的包并放在给定的单一包中

-repackageclass {package_name} 重新包装所有重命名的类文件中放在给定的单一包中

-dontusemixedcaseclassnames 混淆时不会产生形形色色的类名

-keepattributes {attribute_name,...} 保护给定的可选属性，例如LineNumberTable, LocalVariableTable, SourceFile, Deprecated, Synthetic, Signature, and InnerClasses.

-renamesourcefileattribute {string} 设置源文件中给定的字符串常量

我这里加上了-keep public class com.emag.ui.GameCommunity{ public *;} 的参数，含义就是class com.emag.ui.GameCommunity这个类下面的所有public方法和字段都不需要混淆。

这里放上另外一份配置文件，希望对大家有所帮助：

这个是web的项目，使用ProGuard混淆打包的。

是webwork+spring+hibernate的架构的项目，所有需要很详细的配置。（经过n次失败后总结）

Example:

-injars <project>.jar

-outjars <project>_out.jar

-libraryjars <java.home>/lib/rt.jar

-libraryjars <project.home>/webroot/WEB-INF/lib/webwork.jar

.......

# 保留实现Action接口类中的公有的，友好的，私有的属性 和 公有的，友好的方法。其它的全部压缩，优化，混淆。

# 因为配置文件中的类名是一个完整的类名，如果经过处理后就有可能找不到这个类。

# 属性是jsp页面所需要的，如果经过处理jsp页面就无法得到action中的数据。

-keep public class * implements com.opensymphony.xwork.Action{

public protected private <fields>;

public protected <methods>;

}

# 保留实现了Serializable接口类中的公有的，友好的，私有的成员（属性和方法）

# 这个配置主要是对应实体类的配置。

-keep public class * implements java.io.Serializable{

public protected private *;

}