AOSP系统应用移植到Android Studio:DocumentsUI定制与调试实践
最近在折腾一套基于 Android 11 的定制 ROM,需求是把系统自带的文件管理器——也就是 AOSP 里的 DocumentsUI——改出点新东西:调整选择交互、加文件筛选、改排序逻辑。最开始的开发方式很“传统”:直接改 packages/apps/DocumentsUI 源码,然后用 mmm 编译模块、adb sync 推到设备,或者干脆重新生成 system.img 刷模拟器。改一行代码,十分钟起步,改个字符串都熬得人没脾气。后来我干脆把这份系统应用完整移植到 AndroidStudio 里,用 Gradle 单独构建,装到模拟器上断点调试,迭代速度直接上了一个量级。这篇文章把整套移植动作拆开写,包含 framework 依赖怎么补齐、platform 签名怎么处理、AIDL 怎么衔接、最坑的几个运行期问题怎么绕。适合正在做 Framework 系统应用定制、想把系统应用拽进 IDE 里快速跑起来的人参考。
1. 移植前想清楚:这套方案到底解决什么问题
1.1 系统应用在 AOSP 里是怎么构建的,痛点在哪
AOSP 里的应用构建方式和普通 Android 项目完全不同。拿 DocumentsUI 来说,它的构建文件是 Android.bp,核心声明大致长这样:
这个 sdk_version: "system_current" 是关键。它表示 DocumentsUI 在编译时链接的不是普通开发者用的 public SDK,而是 System SDK。System SDK 里除了公开 API,还包含大量 @SystemApi 和部分 @hide 的接口。正是这个差异,导致你把它直接塞进 AndroidStudio 后,一编译就是几百个 cannot find symbol。
那为什么不老老实实继续在 AOSP 里开发?因为体验太差了:
- 改一行 UI 代码,要完整编一次模块,生成新的 APK,再打过 system.img 或
adb sync,等待时间长。 - 想打断点?不是不行,但配置 jdb 很绕,大多数时间是靠 Logcat 输出字符串定位问题。
- 代码跳转、重构、找调用关系,比 AndroidStudio 差了不止一个身位。
所以移植到 AndroidStudio 的核心诉求就一句话:用现代 IDE 的完整开发体验,去调试一个本该在大仓里开发的应用。 只要环境搭对了,改 UI、调逻辑、验证文件操作,基本都能在 IDE 里闭环完成。
1.2 什么样的系统应用适合搬进 AndroidStudio
也不是所有系统应用都适合这么搞。我自己判断一个应用能不能移植、值不值得移植,基本看四点:
- 是否有大量直接调用
com.android.internal.*隐藏类/方法的代码。调得越多,编译期补依赖越麻烦,运行期被 hidden API 限制的概率也越高。 - 是否依赖 SystemServer 内部服务或未公开的 AIDL 接口。比如改 SystemUI 这种要向 SystemServer 注册回调的,移植成本就很高。
- 是否有 JNI / native 库。有 native 代码意味着你还要处理
.so的编译产物和 ABI,移植工作量会涨一个量级。 - 代码量级和模块边界是否清晰。DocumentsUI 这种以 UI 为主、通过公开的 DocumentsProvider 与系统交互的应用,天然适合移植。
移植目标也别忘了:不是为了“绝对一致”,而是为了快速迭代。 最终正式验证仍要回到 AOSP 编译体系里跑一遍。这个定位想清楚后,后面很多取舍就轻松多了。
2. 前置准备与源码整理
2.1 从 AOSP 里要拿哪些东西
动手之前,先把材料备齐。我自己踩过坑之后,固定会拿这几样:
- 应用源码目录。DocumentsUI 在
packages/apps/DocumentsUI,直接把src、res、AndroidManifest.xml、aidl(如果有)都准备好。 - 签名文件。在
build/target/product/security/下,platform.pk8和platform.x509.pem。这是 AOSP 默认的平台签名,后面要转成 AndroidStudio 能直接用的 keystore。 - framework 的编译产物。在
out/target/common/obj/JAVA_LIBRARIES/framework_intermediates/classes.jar,这是完整 framework 实现,编译期当符号库用。 - System SDK stubs(如果有)。构建产物在
out/target/common/obj/PACKAGING/下找类似sdk_system_stubs_intermediates/classes.jar,它只保留系统 SDK 的接口签名,不会和常规 android.jar 冲突。 - 模拟器镜像。强烈建议直接编一个 userdebug 版本的 AOSP 镜像,能
adb root、adb remount,调试系统权限相关功能会省很多事。
你可能会问,为什么不用设备 /system/framework/framework.jar?因为那份是 dex 格式,不能直接给 Gradle 的 javac 当 classpath 用。从编译产物里拿 classes.jar 才是正道。
2.2 新建 AndroidStudio 工程,先别急着拷代码
很多人一上来就把整个源码目录拖进 AS,然后点 Sync,结果看到密密麻麻的报错直接失去信心。我的建议是:先建一个干净工程,把目录骨架理顺,再逐步引入源码。
建工程时注意几个点:
applicationId和包名都保持一致。比如com.android.documentsui,后面做平台签名安装时,系统才认你这个包。minSdk和你的调试镜像系统版本匹配,compileSdk用对应的 API level。比如调试 Android 11,compileSdk就用 30。targetSdk可以先保留在系统版本或稍微低一档。目标 SDK 太高会引入一堆新行为变更,初期调试反而碍事。- AGP 版本别太激进。7.4 左右搭配 JDK 11 比较稳。过新的 AGP 版本有时候要求 JDK 17,而系统应用源码往往还停留在 Java 8 语法特性上,容易平添麻烦。
工程建好后,再把 src、res、AndroidManifest.xml 拷进对应的 app/src/main/ 目录。第一轮编译大概率会报资源错误,先别慌,重点检查两类问题:
- 资源文件里有没有引用系统私有资源,比如
@*android:style/Theme.Material.*、@*android:color/xxx。SDK 的 android.jar 只包含公开资源,私有的会直接编译失败。 - Manifest 里有没有
sharedUserId="android.uid.system"、persistent、directBootAware这类系统属性。调试阶段,建议先把sharedUserId这一行临时注释掉。否则你每次安装,都会收到INSTALL_FAILED_SHARED_USER_INCOMPATIBLE。
2.3 Manifest 和权限的“调试版”改造思路
上面说的不是让你改坏正式代码,而是维护两套 Manifest 分支。我实际操作中,Git 里长期保留一个 debug 分支,里面做这些事:
- 去掉
sharedUserId="android.uid.system"。 - 暂时移除依赖平台签名的系统权限,比如
MANAGE_DOCUMENTS、WRITE_MEDIA_STORAGE。 - 给
application节点加android:debuggable="true"。 - 把
persistent、directBootAware这些标签先注释掉。
这样做的原因很简单:sharedUserId 不只是声明一个 UID,而是要求你的 APK 必须用与系统 framework 相同的证书签名。你如果还没转好平台 keystore,或者还没配好 Gradle 签名,直接装普通 debug 包必然失败。先去系统 VIP 身份跑通 UI,再逐步加权限验证系统能力,这是最平滑的路径。
3. 构建核心:Framework 依赖、隐藏 API 与 AIDL
3.1 让 AndroidStudio 看到 framework 的类:stub jar 还是完整 jar
移植最大的坎,就是编译期找不到隐藏 API。因为 AndroidStudio 默认用的 android.jar 是 SDK 裁剪版,里面只有公开 API。方法有三种,按推荐程度排个序:
第一种,用 System SDK stubs。把 AOSP 构建产物里的 sdk_system_stubs_intermediates/classes.jar 拷到 app/libs/,然后在 Gradle 里声明:
这个方案最干净。stubs 只包含类和方法签名,没有实现代码,不会和 SDK 自带的 android.jar 产生重复类冲突。
第二种,用完整 framework classes.jar。和上面一样拷到 libs,也配 compileOnly。好处是符号最全,坏处是它包含完整的 android.* 类定义,在一些 AGP 版本下会报重复类错误。如果真遇到,你需要把编译 classpath 里的默认 android.jar 移除,或者干脆换回 stubs。所以我建议直接从第一种开始。
第三种,老式“替换 android.jar”的写法。直接把 SDK 目录里的 android.jar 覆盖成 framework 版本。能跑通,但会污染 SDK 环境,换项目就乱,不推荐给新手。
这里要明白一个关键点:编译期用 jar 给符号,运行期用的是设备上的 framework,两者并不直接打包进 APK。 你加的 compileOnly 只是为了骗过 javac,真正干活的是系统运行时。
3.2 隐藏 API 编译过了,运行期还有一道闸
编译过了只是第一步。Android 9 之后,系统对隐藏 API 的反射调用做了强限制。如果你的应用还是普通应用身份,没有平台签名也没预置到系统分区,那运行期调用 @hide 方法时会直接抛 NoSuchMethodException 或 SecurityException。
应对思路也有三条路:
- 保持系统应用身份。平台签名、系统 UID、预置到
/system/priv-app或/system/app,这是最彻底的方案。系统应用不在 hidden API 黑名单限制范围内。 - 把调试包加到白名单。在设备上往
/system/etc/permissions/下放一个hiddenapi-package-whitelist.xml,声明你的包名在白名单里。这需要adb root和remount,适合 userdebug 镜像。 - 尽量走公开 API。这一点很多人忽略。就拿文件管理这个场景来说,
DocumentsContract、MediaStore、StorageManager有一大堆公开能力,能实现大部分功能。写移植代码时,优先用公开接口,把隐藏 API 的调用点限制在最小范围内。
一条很实用的排查经验:运行期间如果收到 NoSuchMethodError,先别急着怀疑代码写错,先确认这个类的方法是不是 @hide,再确认你的包当前是不是系统身份。
3.3 AIDL 文件和系统服务依赖怎么处理
DocumentsUI 这类应用一般不自带 AIDL 服务,但如果你移植的是别的文件管理应用,很可能内部会有 IFileManagerService.aidl。在 AS 里处理 AIDL,有一个明确的目录约束:app/src/main/aidl/,包路径要和 Java 代码一致。
我自己常用的处理方式是:
- 把
.aidl文件按包路径放进aidl目录。 - 如果 AIDL 文件里 import 了系统内部接口,比如
android.os.IFileTransfer这种在 framework 里才有的接口,直接用可能编不过。这时候最省事的办法是把 AIDL 生成的.java文件直接拷进src,让它作为一个普通 Java 类参与编译。 - 客户端绑定系统服务时,
bindService的 Intent 要显式指定系统服务所在包名,避免 Android 5.0 之后隐式绑定导致的ServiceNotFoundException。
AIDL 相关的报错往往比较隐晦,常见的是“找不到符号”和“Service 返回 null”。前者多半是 AIDL 生成的代码没参与构建,后者多半是 Intent 没指明包名,或者服务端压根没在运行。
3.4 第三方依赖版本为什么要向系统镜像对齐
系统应用在 AOSP 里用的 androidx 版本是固定的。DocumentsUI 的 Android.bp 里声明了 androidx.appcompat_appcompat、com.google.android.material_material 等,AOSP 构建系统会从预编译的 maven 仓库拉取对应版本。
到了 AS 里,如果你随手引了一个特别新的 androidx,编译没问题,但跑到系统镜像上就可能出现 ClassNotFoundException 或者版本不匹配的怪异行为。因为系统预置的是旧版本,新版类的实现不在设备上。
解决方式也很直接:
- 先看
Android.bp里用的具体版本号,去 Google Maven 找同一版本引入。 - 或者干脆把系统镜像里的对应 jar/aar 拉出来,放到
libs目录本地引用。 - 再或者,尽量只依赖
androidx.annotation这类元信息库,核心逻辑自己写,减少外部依赖面。
依赖对齐这件事,越早做越好。否则你会在调试过程中发现“AS 里一切正常,上系统就崩”,而这种问题往往极难排查。
4. 签名、权限与安装运行:移植成败的分水岭
4.1 从 platform.pk8 到 Gradle 能用的 keystore
当你的应用打算保留 sharedUserId="android.uid.system" 或者申请系统级权限时,必须用平台签名来安装。平台签名的本质,是你的 APK 用和系统 framework 相同的那对 RSA 密钥签名,系统 PMS 在解析签名时能匹配上,才授予你 system 身份。
AOSP 里给的是 platform.pk8(私钥)和 platform.x509.pem(证书),但 AndroidStudio 的 signingConfigs 只认 keystore。好在 AOSP 自带了转换工具 keytool-importkeypair,路径在 development/tools/ 下。
转换命令:
执行完会在当前目录生成 platform.keystore,store password 和 key password 都是 android。然后在 Gradle 里配置:
注意,这套平台签名只能用于 AOSP 默认镜像。如果你面对的是厂商 ROM,厂商会用自己生成的 platform key,你用 AOSP 默认 key 签的包是装不进去的。所以移植调试前,先确认你手上的系统镜像到底认哪把钥匙。
4.2 三种运行方式,我的推荐路径是这样
我实际调试时发现,移植后的 APK 有三种“活法”,各有各的适用场景。总结成表格更清楚:
| 方式 | 签名 | 系统权限 | 安装难度 | 推荐阶段 |
|---|---|---|---|---|
| 普通 debug 安装 | AndroidStudio 默认 debug key | 无 | 直接 adb install,但 Manifest 有系统权限会失败 |
纯 UI 和交互逻辑初调 |
| platform 签名安装 | 转换后的 platform.keystore | 有,但部分能力未预置时仍受限 | 需要先转 keystore 并配置 Gradle | 系统 API 和权限验证 |
| 编回 AOSP 镜像 | AOSP 构建系统自动处理 | 完整 | 需要编译刷机,迭代较慢 | 最终回归验证 |
我自己的推荐流程是:
- 调试分支里注释掉
sharedUserId,暂时不用平台签名,用普通 debug 包在模拟器上快速调 UI。 - 当需要验证某个系统调用,比如访问
DocumentsContract的 root 读取逻辑,再切到 platform 签名重新安装。 - 所有功能都验证完,把调试改动还原,合并回正式分支,用 AOSP 构建体系做最终回归。
这看起来多了一步,但在实际项目里能省下大量的“编译-刷机”时间,尤其是当你在频繁调整 UI 细节的时候。
4.3 安装后的权限授权和调试技巧
就算你已经用 platform 签名安装成功,部分运行时权限还是要主动申请,或者用 adb 直接授权。比如文件管理最常见的存储权限:
但记住:像 MANAGE_DOCUMENTS 这种 signature|privileged 级别的权限,光 pm grant 救不了。它要求应用必须预置在特权目录下才给。这类权限如果调试时实在绕不过去,方案只有两个:要么把 APK 推到 /system/priv-app/ 下,要么在 AOSP 里给调试包开一个权限白名单文件。这类操作都需要 root 权限,所以用 userdebug 模拟器是最好的选择。
调试时还有几个很实用的习惯:
- 开模拟器后先
adb root,再adb remount,这样后面推文件、改系统配置都方便。 - 顺手把动画关掉:
adb shell settings put global window_animation_scale 0,模拟器跑起来会流畅很多。 - AS 的 Layout Inspector 对系统应用一样能用,查布局层级比一遍遍看 Logcat 高效得多。
- 在代码里用
BuildConfig.DEBUG包一层日志,别把调试日志直接打成正式日志。系统应用如果输出太频繁,会影响整机性能。
5. 移植运行中的常见问题与排查实录
移植过程里踩过的坑,我整理成了一张速查表,每一条都附上我当时实际排查的思路。
| 错误现象 | 直接原因 | 解决思路 |
|---|---|---|
编译报 cannot find symbol |
隐藏 API 没进编译 classpath | 检查 libs 里的 framework-stubs 是否生效,compileOnly 是否配在正确模块 |
| 编译报 duplicate class | 完整 framework.jar 和 android.jar 冲突 | 换用 stubs jar,或通过构建配置移除默认 android.jar |
安装报 INSTALL_FAILED_SHARED_USER_INCOMPATIBLE |
声明了系统 sharedUserId,但签名不匹配 | 换 platform 签名,或调试期注释 sharedUserId |
安装报 INSTALL_FAILED_MISSING_SHARED_LIBRARY |
Manifest 里声明了设备上不存在的共享库 | 检查系统镜像版本和系统应用原本的依赖列表 |
运行时 SecurityException: Permission Denial |
调用了没有权限的接口,或身份不对 | 授权、换平台签名、或改走公开 API |
运行时 NoSuchMethodError |
调用 @hide 方法被 hidden API 限制 | 保持系统身份,或加入白名单 |
Activity 起不来,ClassNotFoundException |
类存在于编译期,但 APK 没打进去 | 检查混淆规则,检查 packagingOptions,确认没有 exclude |
| 打开文件目录列表为空 | DocumentsProvider 没绑定,或 root 没访问到 | 看 adb logcat 里 Provider 的报错,检查 MANAGE_DOCUMENTS 权限 |
下面挑几个我印象最深的展开说。
5.1 platform 签名装了却闪退,先看 UID 身份
有段时间我天真地以为只要 platform 签名安装成功,就完整获得了系统权限。结果启动即崩,抓 log 看到 SecurityException: Permission Denial: getSharedUserId from pid=...。后来才意识到:sharedUserId 的声明和 platform 签名必须同时存在,而且系统在解析 UID 时,还要看你是否真的以系统 UID 运行。签名对了,但如果 Manifest 里没声明对应 UID,或者声明的 UID 和签名不匹配,系统照样不给面子。
排查这类问题,最直接的方法是用:
看到输出是 userId=1000,说明已经是 system 身份。如果还是 10xxx 的普通应用 UID,回头看 Manifest 和签名配置。
5.2 编译过了,装上了,按钮没反应
移植 DocumentsUI 时最容易遇到的一类问题:界面能起来,但点目录、点文件都没反应。这时候别急着在 UI 代码里疯狂打断点,先看 Logcat 里有没有这样的话:
这个场景我栽过两回。第一回是调试期把 MANAGE_DOCUMENTS 拿了,而 DocumentsProvider 需要这个权限才能注册到系统。第二回是 targetSdk 设得比系统版本高,Android 11 的分区存储机制在作怪,导致 Provider 拿不到外部存储路径。解决办法分别是:恢复系统权限清单,或者把 targetSdk 降一档。
5.3 AIDL 服务绑定失败,可能和包名可见性有关
另一个高频问题,是应用作为系统组件时,通过 AIDL 绑定自己熟悉的系统服务,移植到 AS 后突然绑不上了。原因基本都在 Android 11 的包可见性机制:普通应用默认看不到系统的一些包,bindService 直接返回 false。
如果你在调试版里保留了系统 UID,这个问题通常不存在。但如果按我推荐的“调试期去掉系统 UID”方案跑普通安装,就很可能撞上。解决方式是在 Manifest 的 queries 节点里显式声明你要访问的系统服务包名:
否则你会在 bindService 返回 false 上浪费半天时间,而逻辑本身根本没有问题。
5.4 模拟器启动特别慢,run 之后界面不显示
如果你和我一样用 AOSP 镜像调试,会发现它比标准的 Google APIs 模拟器镜像慢不少,Starting up 阶段可能卡很久。这属于正常现象,但有几个加速技巧:
- 冷启动后第一次开 AS 的 Run,耐心等三到五分钟,不要反复点 Stop 重启。
- 如果 run 之后界面一直不显示,先看
adb logcat里有没有Process: com.android.documentsui, PID: ...,有的话就是应用本身卡了,去查 ANR 日志;完全没有进程,说明安装或启动就被拦了。 - 模拟器配置里尽量开 GPU 加速,关掉不必要的硬件性能限制,AOSP userdebug 镜像在纯软件渲染下确实很慢。
这个坑不算移植本身的问题,但经常在移植后的首次调试时冒出来,提前知道能少走很多弯路。
6. 回到 AOSP:怎么把调试成果安全合回去
移植不是目的,把改动高效合回正式构建才是闭环。我自己的固定流程是:
- 在 Git 里维护
debug-port分支,里面保存所有“为移植调试”服务的改动,包括sharedUserId注释、权限裁剪、BuildConfig.DEBUG日志开关。 - 正式分支只保留业务逻辑改动,不保留任何调试专用分支内容。
- 回 AOSP 后,把
Android.bp的依赖列表和 Manifest 恢复原状,跑一次mmm packages/apps/DocumentsUI,确认编译通过。 - 在 userdebug 设备上
adb install -r替换原来预置的应用,快速看主要功能是否正常。
还有一个建议,如果你在 AS 里引入了新的第三方库,记得同步更新 Android.bp 里的 static_libs 或者 libs。AOSP 构建体系是不认 Gradle 依赖的,漏掉这一步,合进去就会链接失败。
最后分享一点个人经验:这类移植项目,最忌讳一上来就想“一步到位”。先搭环境,跑一个最小可运行的 APK;再逐步打开 sharedUserId、系统权限、隐藏 API;最后才把业务逻辑全部迁过来。每一步都验证过再往下走,远比一次性解决所有问题高效。我自己第一次移植,就因为在 Manifest 里保留了系统 UID,又没配好签名,卡了整整一个下午。把调试分支和正式分支分开之后,后面的开发节奏一下子就顺了。