blob: 0e8cc7a5809382fdf721be6c9efea278ba03b20a (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
page.title=ProGuard
parent.title=Tools
parent.link=index.html
page.type=工具
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>本文内容</h2>
<ol>
<li><a href="#enabling">启用 ProGuard</a></li>
<li><a href="#configuring">配置 ProGuard</a></li>
<li>
<a href="#decoding">解码混淆后的堆栈跟踪信息</a>
<ol>
<li><a href="#considerations">调试已发布应用时应注意的事项</a></li>
</ol>
</li>
</ol>
<h2>另请参见</h2>
<ol>
<li>
<a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard 手册 »</a>
</li>
<li>
<a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/retrace/introduction.html">ProGuard ReTrace 手册 »</a>
</li>
</ol>
</div>
</div>
<p>ProGuard 工具通过移除无用的代码以及使用语义隐晦的名称来重命名类、字段和方法，从而达到压缩、优化和混淆代码的目的。最终您将获得一个较小的 <code>.apk</code> 文件，此文件更难于进行反向工程。由于 ProGuard 会使应用更难于进行反向工程，因此当应用使用对安全性要求极高的功能时（例如，当您<a href="{@docRoot}google/play/licensing/index.html">向应用授予许可</a>时），您必须使用此工具。</p>
<p>ProGuard 已集成到 Android 构建系统，所以您无需手动调用此工具。只有当您在发布模式下构建应用时，ProGuard 才会运行，因此当您在调试模式下构建应用时，就无需处理混淆后的代码。是否运行 ProGuard 完全由您决定，但我们强烈建议您运行该工具。</p>
<p>本文介绍如何启用和配置 ProGuard，以及如何使用 <code>retrace</code> 工具解码混淆后的堆栈跟踪信息。</p>
<h2 id="enabling">启用 ProGuard</h2>
<p>当您创建 Android 项目时，系统会在该项目的根目录中自动生成一个 <code>proguard.cfg</code> 文件。此文件将定义 ProGuard 会如何优化和混淆代码，因此您必须了解如何根据自己的需求对其进行自定义。默认的配置文件只涵盖一般的使用情形，因此您极有可能需要根据自己的需求对其进行修改。请参阅下文<a href="#configuring">配置 ProGuard</a> 这一部分，了解如何自定义 ProGuard 配置文件。</p>
<p>要启用 ProGuard，让其作为 Ant 或 Eclipse 构建环境的一部分运行，请在 <code><project_root>/project.properties</code> 文件中设置 <code>proguard.config</code> 属性。该路径可以是绝对路径，也可以是项目根目录的相对路径。</p>
<p class="note"><strong>注意</strong>：在使用 Android Studio 时，您必须将 Proguard 添加到 <code>gradle.build</code> 文件的构建类型中。有关详情，请参阅 <a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Running-ProGuard">Gradle 插件用户指南</a>。
<p>如果您将 <code>proguard.cfg</code> 文件留在默认位置（项目的根目录中），则可以按如下格式指定其位置：</p>
<pre class="no-pretty-print">
proguard.config=proguard.cfg
</pre>
<p>
您也可以将此文件移到任何所需的位置，然后按如下格式指定其绝对路径：
</p>
<pre class="no-pretty-print">
proguard.config=/path/to/proguard.cfg
</pre>
<p>当您在发布模式下构建应用时，无论是通过运行 <code>ant release</code> 还是通过使用 Eclipse 中的“导出向导”，构建系统都会自动检查是否设置了 <code>proguard.config</code> 属性。<em></em>如果已设置该属性，ProGuard 会自动处理应用的字节码，然后再将所有内容打包到 <code>.apk</code> 文件中。在调试模式下进行构建时之所以不调用 ProGuard，是因为该工具会加大调试难度。</p>
<p>ProGuard 在运行后会输出以下文件：</p>
<dl>
<dt><code>dump.txt</code></dt>
<dd>描述 <code>.apk</code> 文件中所有类文件的内部结构</dd>
<dt><code>mapping.txt</code></dt>
<dd>列出原始与混淆后的类、方法和字段名称之间的对应关系。如果您从发布版本收到问题报告，则必须使用此文件，因为通过它可将混淆后的堆栈跟踪信息转换为原始的类、方法和成员名称。有关详情，请参阅<a href="#decoding">解码混淆后的堆栈跟踪信息</a>。</dd>
<dt><code>seeds.txt</code></dt>
<dd>列出未混淆的类和成员</dd>
<dt><code>usage.txt</code></dt>
<dd>列出从 <code>.apk</code> 删除的代码</dd>
</dl>
<p>这些文件都位于以下目录中：</p>
<ul>
<li><code><project_root>/bin/proguard</code>（如果您使用的是 Ant）。</li>
<li><code><project_root>/proguard</code>（如果您使用的是 Eclipse）。</li>
</ul>
<p class="caution"><strong>注意</strong>：每当您在发布模式下构建版本时，这些文件都会被 ProGuard 最新生成的文件覆盖。请在每次发布应用时为这些文件保存一份副本，以便反混淆来自发布版本的问题报告。如需详细了解为何要保存这些文件，请参阅<a href="#considerations">调试已发布应用时应注意的事项</a>。
</p>
<h2 id="configuring">配置 ProGuard</h2>
<p>在某些情况下，<code>proguard.cfg</code> 文件中的默认配置足以满足您的需求。不过，在很多情况下，ProGuard 很难做出正确分析，因此可能会移除它认为无用而实际上您的应用却需要的代码。部分示例如下：</p>
<ul>
<li>一个只在 <code>AndroidManifest.xml</code> 文件中引用的类</li>
<li>一个通过 JNI 调用的方法</li>
<li>动态引用的字段和方法</li>
</ul>
<p>默认的 <code>proguard.cfg</code> 文件旨在涵盖一般的使用情形，但您可能会遇到异常情况，例如 <code>ClassNotFoundException</code>（此异常情况会在 ProGuard 删除您的应用调用的整个类时发生）。</p>
<p>您可以通过在 <code>proguard.cfg</code> 文件中添加一个 <code>-keep</code> 行，来修复因 ProGuard 在删除代码而造成的错误。例如：</p>
<pre>
-keep public class <MyClass>
</pre>
<p>在使用 <code>-keep</code> 选项时，您既有许多选择也有不少需要注意的方面，因此我们强烈建议您阅读 <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard 手册</a>，详细了解如何自定义您的配置文件。该手册中的“Keep 选项概述”和“示例”部分尤其有用；<em></em><em></em><a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/troubleshooting.html">问题排查</a>部分则概述了在 ProGuard 删除代码后您可能会遇到的其他常见问题。</p>
<h2 id="decoding">解码混淆后的堆栈跟踪信息</h2>
<p>当混淆后的代码输出堆栈跟踪信息时，方法名称会被混淆，即便仍能进行调试，难度也会很大。幸运的是，ProGuard 在每次运行时都会输出一个 <code><project_root>/bin/proguard/mapping.txt</code> 文件，其中会显示与混淆后的名称相对应的原始的类、方法和字段名称。</p>
<p>Windows 上的 <code>retrace.bat</code> 脚本以及 Linux 或 Mac OS X 上的 <code>retrace.sh</code> 脚本可以将混淆后的堆栈跟踪信息转换成可读文件，此文件位于 <code><sdk_root>/tools/proguard/</code> 目录中。执行 <code>retrace</code> 工具的语法如下：</p>
<pre>retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]</pre>
<p>例如：</p>
<pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre>
<p>如果您不为“<stacktrace_file>”指定值，<code>retrace</code> 工具会从标准输入中读取。<em></em></p>
<h3 id="considerations">调试已发布应用时应注意的事项</h3>
<p>每次向用户发布应用时，都请保存所发布版本的 <code>mapping.txt</code> 文件。这样一来，如果用户遇到问题，并向您提交混淆后的堆栈跟踪信息，您就可以利用为每个发布版本保存的 <code>mapping.txt</code> 文件副本调试问题。每当您构建发布版本时，项目的 <code>mapping.txt</code> 文件都会被覆盖，因此您必须谨慎保存所需的版本。</p>
<p>例如，假设您发布了某个应用，并继续开发该应用的新功能，以便将来发布新版本。之后不久您使用 ProGuard 构建发布版本。此版本覆盖了之前的 <code>mapping.txt</code> 文件。之后，某位用户提交了问题报告，其中包含来自当前已发布的应用的堆栈跟踪信息。但您已无法调试该用户的堆栈跟踪信息，因为与该用户设备上的版本相关联的 <code>mapping.txt</code> 文件已被覆盖。除此之外，其他一些情况也可能会导致您的 <code>mapping.txt</code> 文件被覆盖。因此，如果您预计需要进行调试，请务必在每次发布应用时都保存一份副本。</p>
<p>如何保存 <code>mapping.txt</code> 文件由您自行决定。例如，您可以将其重命名以使其名称中包含版本号，也可以对其（连同源代码一起）进行版本管理。</p>
|
