recover-kotlin-names.sh完全教程：一条命令生成混淆名到真实名的映射表-开发者社区

recover-kotlin-names.sh完全教程：一条命令生成混淆名到真实名的映射表

【免费下载链接】android-reverse-engineering-skillClaude Code skill to support Android app's reverse engineering项目地址: https://gitcode.com/GitHub_Trending/an/android-reverse-engineering-skill

本文以开源项目android-reverse-engineering-skill为例，详解如何使用recover-kotlin-names.sh这个脚本：反编译一个经过 R8 混淆的 Kotlin 应用后，一条命令即可挖掘源码中残留的原始类名，生成一张「混淆名 → 真实名」的类名映射表，让满屏的a.b.c重新变回LoginRepository这样的可读代码。

为什么需要恢复类名：R8 混淆绕不开的坎

现代 Android 应用绝大多数用 Kotlin 编写，且上架前会经过 R8 / ProGuard 混淆。用 jadx 反编译后，你会看到大量单字母包和单字母类名，例如nq.e、a.a.b……读这种代码如同看天书。

但有一个好消息：R8 能改名 JVM 符号，却删不掉 Kotlin 元数据字符串——Kotlin 运行时在反射、协程等场景下必须依赖原始全限定名。于是，两个注解会把「开发商原本写下的类名」原样泄漏在反编译源码中：

注解来源	出现位置	泄漏的信息
`@DebugMetadata(c = "...")`	几乎每个`suspend`协程 lambda	外部类的原始全限定名
`@Metadata(d2 = {...})`	每个 Kotlin 类	文件内部类引用的 JVM 描述符（如`Lcom/example/Foo;`）
`/* renamed from: ... */`注释	jadx 偶尔输出	原始类名

recover-kotlin-names.sh的作用，就是自动扫描这三类信号，一次性生成映射表。

💡 完整原理可参考 kotlin-name-recovery.md

环境准备：装好依赖再开工

脚本本身只依赖Python 3（纯正则扫描，零额外依赖）。但前提是你手上已有一份反编译好的源码目录，整条链路需要：

Java JDK 17+ 和 jadx（用于反编译，脚本会自动检测缺失项）
获取项目代码：

git clone https://gitcode.com/GitHub_Trending/an/android-reverse-engineering-skill.git

运行依赖检查脚本，确认工具链完整：

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/check-deps.sh

缺失依赖的安装方法见 setup-guide.md。

一条命令生成映射表：完整三步

第 1 步：反编译 APK

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/decompile.sh app.apk

第 2 步：运行名称恢复脚本

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/recover-kotlin-names.sh \ app-decompiled/sources/ output/names/

第一个参数是反编译源码目录，第二个是输出目录（省略时默认写到源码目录旁的mapping/）。

第 3 步：查看三种交付物

脚本会生成三种格式的映射（输出定义见 recover-kotlin-names.sh#L26-L34）：

文件	格式	适合场景
`output/names/mapping.tsv`	Tab 分隔：混淆名 / 真实名 / 源文件	人眼浏览，可直接用表格软件打开
`output/names/mapping.json`	`{ "a.b.c": "com.example.X" }`	脚本自动化消费
`output/names/by_package/`	按真实包名拆分的索引文件	快速了解某个模块的类结构

mapping.tsv内容示例：

obf_fqn real_fqn file nq.e com.example.feature.account.AccountRepositoryImpl nq/e.java nq.f com.example.feature.account.AccountViewModel nq/f.java

运行结束时，脚本还会打印统计：共恢复多少个类名、分别来自哪种信号源（debug_meta / d2 / renamed）、涉及多少个真实包。

恢复率：能找回多少真实类名？

真实项目中，脚本通常能恢复30% ~ 50%的类；更关键的是，你真正想读的那部分类几乎能 100% 找回：

类类型	恢复率
`Repository`/`Impl`	约 100%
`*ViewModel`	约 100%
`UseCase`/`Interactor`	约 100%
普通`data class`DTO	约 80%
纯 Java 工具类	较低（无 Kotlin 元数据）

也就是说：核心业务类全部恢复真名，剩下的单字母类大多是 lambda 和内部类，不影响阅读主线。

查询映射表：lookup-name.sh 的 4 种用法

映射表生成后，用配套脚本 lookup-name.sh 查询（路径同plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/目录）：

1️⃣ 混淆名查真名— 代码里遇到nq.e时：

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ -o nq.e # nq.e -> com.example.feature.account.AccountRepositoryImpl # sibling: nq.d （同一类拆分出的 lambda / 内部类）

2️⃣ 按真实名模糊搜索：

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ Repository

3️⃣ 列出某个真实包下的所有类：

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ -p com.example.feature

4️⃣ 带真名标注的源码搜索— 最常用，可替代普通 grep：

bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ --grep '"api/' app-decompiled/sources/ # 每条命中结果末尾自动追加 // 真实类名

推荐完整工作流：指纹 → 反编译 → 恢复 → 查询

结合项目内置的 Phase 0–4 工作流，推荐执行顺序如下：

先做指纹：用 fingerprint.sh 几秒钟判断框架类型、HTTP 技术栈和混淆等级；若报告显示中/高混淆且应用是 Kotlin，务必在追调用链之前恢复类名
反编译：decompile.sh
恢复类名：recover-kotlin-names.sh一条命令
查询阅读：用lookup-name.sh --grep替代普通 grep；遇到混淆名随时用-o解析

完整工作流定义见 SKILL.md 中的 Phase 3.5 章节。

局限与注意事项：哪些类恢复不了

方法名和字段名不会被恢复— Kotlin 元数据只保留类级别信息，方法名仍需 jadx-gui 交互重命名或靠模式推断
纯 Java 类没有@Metadata，会保持混淆状态
被深度内联的类可能出现在错误的文件名之下 — 把恢复结果当作强提示而非绝对结论
建议反编译时同时开启--deobf参数：它处理无元数据信号的字段和方法，恢复脚本处理类名，两者互补

recover-kotlin-names.sh完全教程：一条命令生成混淆名到真实名的映射表