📚 课程目录第4章映射文件剖析

第四章：映射文件剖析——mapping.txt 的生成、结构与解读方法

mapping.txt，这玩意儿在 R8 混淆流程里，说穿了就是个翻译字典。你把类名、方法名、字段名全打乱了，堆栈里全是 a.a.a、b.b.b，光看谁能看懂？这时候 mapping 文件就是救命稻草。我个人习惯，每次发版前都把它归档备份，别问为什么，吃过亏就懂了。

4.1 mapping.txt 是怎么生出来的？

R8 默认就会生成 mapping 文件，但你需要显式告诉它要保留。

在 Gradle 的 build.gradle（模块级别）里，你通常能看到类似这样的配置：

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                          'proguard-rules.pro'
            // R8 默认会在输出目录生成 mapping.txt
        }
    }
}

如果你用的是 R8 命令行，参数 -printmapping 就是钥匙：

r8 --release --output out/ --pg-conf proguard-rules.pro --printmapping mapping.txt input.jar

生成的位置？默认在 build/outputs/mapping/release/ 下面。嗯，这里要注意——每次构建都会覆盖，所以一定要做好版本关联。我在项目里有一次因为 mapping 文件和 APK 对不上，客户反馈的崩溃堆栈死活解不开，后来不得不重新打一个同等混淆版本的包来对比，折腾了一整天。

4.2 mapping.txt 长什么样？

打开一看，其实挺有规律的。它分几大块：

文件头：开头会有 R8 版本号、日期、混淆规则摘要等元信息。
类映射：最核心的部分，格式为 原类名 -> 混淆后类名:，后面跟着成员映射。
方法映射：在类映射下方缩进，原返回值原方法名(参数) -> 混淆后方法名。
字段映射：类似方法，原类型原字段名 -> 混淆后字段名。
行号映射：可选部分，当保留行号信息时会出现，用于把混淆后的行号映射回原行。

来看个实际例子：

com.example.app.LoginActivity -> com.example.app.a.a:
    void onCreate(android.os.Bundle) -> a
    int userId -> b
    android.widget.Button loginButton -> c
    void handleLogin() -> b

明白了吧？LoginActivity 被缩成了 a.a，里面的 onCreate 变成了 a，userId 字段变成了 b。你拿到崩溃堆栈，看到 a.a.a，对应回去就是 LoginActivity.onCreate。

4.3 解读地图——怎么快速还原崩溃堆栈？

解读 mapping 文件说到底就是“查字典”。但手动查太慢，我一般用工具：

官方 retrace.jar：Android SDK 自带，在 tools/proguard/lib/retrace.jar。命令很简单：

java -jar retrace.jar mapping.txt stacktrace.txt

输出就是还原后的堆栈。

线上解析服务：比如 Firebase Crashlytics、Bugly 都支持上传 mapping 文件自动反混淆，省心。
自己写脚本：如果 mapping 文件超大，或者你需要批量处理，我会用 Python 解析，一个正则搞定：

import re

def parse_mapping(mapping_path):
    mapping = {}
    with open(mapping_path) as f:
        current_class = None
        for line in f:
            # 匹配类映射
            m = re.match(r'^(.+?) -> (.+?):$', line)
            if m:
                original_class = m.group(1)
                obfuscated_class = m.group(2)
                current_class = obfuscated_class
                mapping[current_class] = {'class': original_class, 'members': {}}
                continue
            # 匹配成员映射
            if current_class:
                m = re.match(r'^\s+(.+?) (.+?) -> (.+)$', line)
                if m:
                    full_sig = f"{m.group(1)} {m.group(2)}"
                    obfuscated_name = m.group(3)
                    mapping[current_class]['members'][obfuscated_name] = full_sig
    return mapping

我的小技巧：把 mapping 文件和 APK 的版本号一起写进文件名，比如 mapping-v2.1.3.txt，这样永远不会搞混。

4.4 核心结构一张图

下面我用 SVG 给你画一个 mapping.txt 的完整结构解析。注意看层级关系和映射流程——理解了这张图，你以后看 mapping 文件就像看菜单一样简单。

4.5 解读实战——从一个崩溃堆栈到最终定位

假设线上抓到的堆栈长这样：

java.lang.NullPointerException
    at com.example.app.a.a.a(SourceFile:18)
    at com.example.app.a.a.onCreate(SourceFile:33)
    at android.app.Activity.performCreate(Activity.java:7344)

我们来一步一步破解：

混淆堆栈条目	查 mapping 动作	还原结果
`com.example.app.a.a.a`	查类映射： `a.a` → `LoginActivity` 查方法映射： `a` → `handleLogin`	`LoginActivity.handleLogin`
`com.example.app.a.a.onCreate`	方法名 `onCreate` 没被混淆（配置了 keep）	`LoginActivity.onCreate`
行号 `18`	查行号映射（如果有）	可能对应源文件第 152 行

你看，几分钟就能定位到一个具体的业务方法。我在团队里推了一个规范：所有崩溃堆栈必须先经过 mapping 还原再提交工单，省得大家对着 a.a.a 瞎猜。

注意！ 如果 mapping 文件是用 -keepattributes SourceFile,LineNumberTable 生成的，行号映射才会包含。否则 SourceFile 会显示 “Unknown”，行号变成 0。这时候你只能靠方法名来猜，但至少比完全黑盒强。

4.6 常见坑与避坑指南

mapping 文件与 APK 版本不匹配：我曾经碰到过一个实习生直接拿上个版本的 mapping 文件来解当前崩溃，结果还原出来的类名全是错的。记住：每个 APK 必须对应它自己构建时生成的 mapping 文件。
多 module 项目：每个 module 如果独立混淆，会生成各自的 mapping 文件。聚合的 mapping 文件需要你在打包时手动合并，或者用 -applymapping 统一。我在一个超大项目里吃过亏，后来写了个 Gradle 任务自动收集所有子模块的 mapping 合并成一个。
R8 与 ProGuard 的 mapping 格式差异：绝大部分字段一致，但 R8 在新版本里会多一行 # R8 version 开头的信息，解析脚本最好兼容一下。
行号偏移：混淆后行号会被压缩，通常会从 1 或 2 开始重新编排。别以为原文件第 18 行就是第 18 行，你得查行号映射表才行。

嗯，再补一个经验：如果你需要在 CI/CD 里自动化解混淆，建议把 mapping 文件作为构建产物归档到 OSS 或 S3，命名规则统一为 ${APP_NAME}-${VERSION_CODE}-${BUILD_TIME}.txt。这样以后任何时候都能回溯。

总结一句话：mapping.txt 就是混淆世界的暗号本，用好它，崩溃定位效率至少提升 50%。但别忘了——保护好自己的 mapping 文件，坏人拿到它就能反编译出你的原始代码结构，安全上的门一定要注意。