Question

混淆器（ ProGuard ）

译者邮箱： litaojun@gmail.com

版本：Android 3.0 r1

原文

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 中剥离的代码。

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

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

<project_root>/proguard 当你使用 Eclipse 时

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

混淆器配置 ( Configuring ProGuard )

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

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

一个通过 JNI 调用的方法。

动态引用的属性和方法。

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

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

-keep public class <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 文件由你决定。例如，你可以根据版本和构建号来重命名它们，或者连同你的源代码进行版本控制。