Android DocumentsUI 移植到 Android Studio 实战:从 AOSP 到独立工程
1. 为什么要把 Framework 里的文件应用单独拎出来
做过 Android 系统开发的朋友大概率都碰过这么一个场景:客户或者产品跑过来提需求,说系统自带的文件管理器太素了,想加个云盘入口、想改个侧边栏、想支持自定义文件类型图标,甚至想直接换一套 UI。这时候你有两条路——一条是去应用层从零写一个文件管理器,另一条是把 AOSP 里的 DocumentsUI 抠出来,移植到 Android Studio 里改。
第一条路听起来自由,实际上坑很深。文件管理器的核心难点从来不是界面,而是那一堆和系统底层耦合的能力:StorageManager 的挂载点监听、MediaStore 的索引查询、DocumentsProvider 的跨进程调用、SAF(Storage Access Framework)的权限模型、多用户和存储卷的适配。这些逻辑在 AOSP 的 DocumentsUI 里已经打磨了十几年,你从零写一遍,光是处理各种 content:// URI 的边界情况就能耗掉几个月。
第二条路就是把 packages/apps/DocumentsUI 这个模块从 AOSP 源码树里搬出来,变成一个可以用 Android Studio 打开、编译、调试的独立工程。这件事的价值在于:你保留了 Framework 级别的成熟实现,同时获得了应用层开发的全部便利——断点调试、Layout Inspector、热重载、Gradle 依赖管理,不用再在几十 G 的 AOSP 源码树里 mm 一下等半天。
但这条路也不是没有代价。DocumentsUI 原本是作为系统应用编译的,它依赖大量 @hide API、com.android.internal 包下的类、系统签名权限,还有 AOSP 特有的构建规则(Android.bp)。直接扔进 Android Studio,Gradle 会给你报几百个错。所以移植的核心工作,就是把这些系统级依赖一层层剥开、替换、打桩,让它能在标准 Android 构建体系下跑起来。
这篇文章适合三类人看:一是做 ROM 定制、需要深度改造系统文件应用的系统工程师;二是想学习 SAF 和 DocumentsProvider 机制、拿官方实现当教材的应用开发者;三是接私活需要快速交付一个定制文件管理器的独立开发者。不管你属于哪一类,下面的内容都是从实际移植过程中踩出来的,不是纸上谈兵。
2. 移植前的整体思路与方案选型
2.1 先搞清楚 DocumentsUI 到底依赖了什么
在动手之前,你得先对 DocumentsUI 的依赖结构有个清醒的认识。我把它拆成四层来看:
第一层是 Android 框架公开 API,比如 Activity、Fragment、RecyclerView、ContentResolver 这些,这部分移植过来零成本,Gradle 直接就能解析。
第二层是 系统隐藏 API(@hide),比如 com.android.internal.util.Preconditions、android.os.UserHandle 的部分方法、StorageManager 的隐藏接口。这些在标准 SDK 里是看不到的,编译时会直接报 "cannot find symbol"。
第三层是 系统签名权限和系统应用能力,比如 android.permission.MANAGE_DOCUMENTS、android.permission.WRITE_MEDIA_STORAGE,这些权限普通应用申请不到,需要在 AndroidManifest.xml 里声明,同时在运行时做降级处理。
第四层是 AOSP 构建系统特有的东西,比如 Android.bp、Android.mk、R.java 的生成方式、overlay 资源目录、privapp-permissions 白名单。这些在 Gradle 体系里全都不存在,需要转换成对应的 build.gradle 配置。
理解这四层依赖,你就知道移植不是简单的"复制粘贴 + 改改包名",而是一次系统性的依赖重构。
2.2 三种移植策略的取舍
实际操作中,我见过三种做法,各有优劣:
策略一:整树搬迁,最小改动。 把 DocumentsUI 整个目录复制出来,保留原有的包名 com.android.documentsui,然后逐个解决编译错误。优点是改动最小,后续跟 AOSP 上游同步容易;缺点是包名和系统应用冲突,装到真机上可能覆盖系统自带版本,调试时容易混淆。
策略二:改包名,彻底独立。 把包名改成 com.yourcompany.documentsui,所有 R 类引用、import 全部跟着改。优点是干净独立,可以和系统版本共存;缺点是改动量大,AOSP 里有些地方硬编码了包名(比如 DocumentsProvider 的 authority),改起来容易漏。
策略三:混合方案,保留核心包名,只改应用 ID。 这是我个人最推荐的做法。applicationId 改成自己的,但 Java 包名保持 com.android.documentsui 不变。这样既避免了和系统应用冲突,又不用大规模改 import,工作量可控。
选哪种,取决于你的目标。如果只是学习研究,策略一最省事;如果要交付商业产品,策略三最稳妥。
2.3 Gradle 版本和 AGP 的匹配问题
移植过程中一个很容易被忽视的坑是 Gradle 和 Android Gradle Plugin(AGP)的版本匹配。DocumentsUI 在不同 Android 版本上用的构建配置差异很大。比如 Android 10 的 DocumentsUI 还在用 Android.mk,Android 11 之后全面转向 Android.bp,而 Android.bp 里的 sdk_version、static_libs 这些配置,在 Gradle 里没有直接对应物。
我的建议是:不要盲目追新。如果你移植的是 Android 12 或 13 的 DocumentsUI,用 AGP 7.4 + Gradle 7.5 这套组合比较稳,JDK 用 11。如果用 AGP 8.x,它会强制要求 namespace 配置,而 DocumentsUI 的 AndroidManifest.xml 里原本是没有 package 属性的(AOSP 构建时通过 Android.bp 指定),你得手动补上。
另外,国内网络环境下 Gradle 发行版下载经常卡住,could not install gradle distribution from 'gradle-8.13-bin.zip' 这个报错很多人都遇到过。解决办法是在 gradle-wrapper.properties 里把 distributionUrl 换成国内镜像,或者干脆用本地已经下载好的 Gradle 离线包,在 Android Studio 设置里指定本地 Gradle 路径。
3. 核心细节解析与实操要点
3.1 工程目录结构的重组
从 AOSP 抠出来的 DocumentsUI 目录大概长这样:
要变成 Android Studio 工程,标准结构应该是:
关键动作是把 src/ 挪到 app/src/main/java/ 下,res/ 挪到 app/src/main/res/ 下。注意 protos/ 目录如果存在,说明 DocumentsUI 用了 Protocol Buffers 做跨进程数据传输,你需要在 build.gradle 里加 protobuf 插件,否则编译会报找不到生成的类。
3.2 隐藏 API 的三种处理方式
这是移植过程中最耗时的部分。DocumentsUI 里大量使用了 @hide API,处理方式有三种:
方式一:反射调用。 对于调用频率低、性能不敏感的接口,用反射是最省事的。比如 StorageManager.getStorageVolumes() 在某些版本上是隐藏的,你可以写个工具类包一层反射。缺点是代码丑、容易在混淆后出问题,而且 Android 9 之后反射隐藏 API 会受到 hiddenapi 限制。
方式二:编译期 stub。 这是最推荐的做法。自己建一个 stubs 模块,把用到的隐藏类和方法按原签名声明一遍,编译时用 compileOnly 引入,运行时这些类由系统提供。比如 com.android.internal.util.Preconditions,你只需要在 stub 里声明 checkNotNull、checkArgument 这几个静态方法即可。这样代码里可以正常 import 和调用,编译通过,运行时也不会出错。
方式三:源码内联。 对于逻辑简单、不依赖系统状态的隐藏类,直接把源码复制过来改个包名。比如 com.android.internal.util.ArrayUtils,里面就是一堆数组操作,复制过来完全没问题。
我的经验是:优先用 stub,其次内联,最后才反射。stub 方案既保持了代码的可读性,又不会引入运行时风险。
3.3 系统权限的降级处理
DocumentsUI 在 AndroidManifest.xml 里声明了一堆系统权限:
这些权限普通应用申请不到,但声明了也不会导致安装失败,只是运行时会被静默拒绝。问题在于,DocumentsUI 的某些代码路径假设自己拥有这些权限,比如直接调用 StorageManager 的挂载接口。移植后这些调用会抛 SecurityException。
处理办法是在这些调用点加 try-catch,捕获异常后走降级逻辑。比如原本直接挂载存储卷,降级后改成跳转到系统设置让用户手动操作。这部分改动需要你逐个方法去审查,没有捷径。
注意:不要试图用
android:sharedUserId="android.uid.system"来绕过权限问题。这样做需要系统签名,而且会导致应用无法在普通设备上安装,调试极其痛苦。
3.4 资源引用的坑
DocumentsUI 的资源文件里引用了大量系统内部资源,比如 @android:style/Theme.DeviceDefault、@*android:color/system_accent。带 * 前缀的是私有资源,标准 SDK 里访问不到。
解决办法有两个:一是把用到的私有资源值复制到自己的 res/values/ 里,改成自己的资源名;二是用 Resources.getSystem().getIdentifier() 动态获取。前者更稳定,后者更灵活但容易在系统版本升级后失效。
我一般用前者,因为文件管理器的 UI 相对固定,把颜色、尺寸这些值抄过来一劳永逸。
4. 实操过程与核心环节实现
4.1 从 AOSP 提取源码的完整步骤
假设你已经有一份 AOSP 源码树,路径是 ~/aosp,目标 Android 版本是 13。
第一步,确认模块位置:
你应该能看到 Android.bp、src/、res/ 等目录。如果这个目录不存在,说明你的 AOSP 没有同步这个模块,需要先 repo sync packages/apps/DocumentsUI。
第二步,复制到工作目录:
第三步,重组目录结构:
第四步,处理 protos 目录(如果存在):
如果有 .proto 文件,说明用到了 protobuf。在 app/build.gradle 里加:
4.2 build.gradle 的关键配置
这是移植的核心文件,我贴一份经过验证的配置:
几个关键点解释一下:
namespace 是 AGP 8.x 强制要求的,值填 Java 包名。applicationId 填你自己的,避免和系统应用冲突。minSdk 建议不低于 29,因为 DocumentsUI 在 Android 10 之后才稳定支持分区存储,低版本适配成本很高。
compileOnly files('libs/framework-stubs.jar') 这一行是引入隐藏 API stub 的。这个 jar 需要你自己打,下面讲怎么生成。
4.3 生成 framework-stubs.jar
最直接的办法是从 AOSP 编译产物里拿。编译完 AOSP 后,在 out/target/common/obj/JAVA_LIBRARIES/framework_intermediates/ 下能找到 classes.jar,这里面包含了所有 @hide 类。
但直接拿整个 classes.jar 有个问题:它包含了 android.* 下的所有类,会和 SDK 里的 android.jar 冲突。解决办法是用 jarjar 或者手动筛选,只保留 com.android.internal.* 和你实际用到的隐藏类。
我一般用这个脚本筛选:
这样生成的 stub jar 体积小,冲突少。
4.4 逐个击破编译错误
配置好之后,第一次 Sync 大概率会报几百个错。别慌,按类型分批处理:
错误类型一:找不到符号(cannot find symbol)。 这是隐藏 API 没 stub 到。看报错信息里的类名,去 AOSP 源码里找到对应文件,把方法签名抄到 stub 里。
错误类型二:资源找不到(resource not found)。 私有资源引用问题。在 res/values/ 下新建 private_res.xml,把用到的值定义一遍。
错误类型三:包不存在(package does not exist)。 通常是 com.android.internal.R 这种。这个类在 AOSP 里是自动生成的,标准工程里没有。解决办法是把用到 com.android.internal.R 的地方改成自己的 R,或者用 Resources.getSystem().getIdentifier() 动态获取。
错误类型四:方法签名不匹配。 不同 Android 版本 API 有差异。比如 StorageManager.getStorageVolumes() 在 Android 10 返回 List<StorageVolume>,Android 11 改成了 List<StorageVolume> 但加了新参数。这种情况需要你根据目标版本调整调用代码。
我处理这些错误的顺序是:先解决 import 问题,再解决资源问题,最后解决 API 签名问题。因为 import 错误会掩盖后面的错误,一层层剥洋葱效率最高。
4.5 真机调试与权限适配
编译通过只是第一步,装到真机上跑起来才是真正的考验。
第一次启动大概率会崩,常见原因有几个:
一是 DocumentsApplication 初始化时调用了系统级服务。比如它可能尝试注册 DocumentsProvider 的监听器,但普通应用没有这个权限。解决办法是在 Application.onCreate() 里加权限检查,没有权限就跳过相关初始化。
二是 Activity 启动时 Intent 里缺少必要参数。DocumentsUI 原本是被系统通过特定 Intent 拉起的,直接点图标启动会缺少 EXTRA_INITIAL_URI 之类的参数。你需要在 DocumentsActivity 里加默认值处理。
三是存储权限没授予。虽然 DocumentsUI 用的是 SAF 框架,理论上不需要 READ_EXTERNAL_STORAGE,但某些代码路径会直接查询 MediaStore,这时候就需要运行时权限。在 AndroidManifest.xml 里声明,然后在 MainActivity 里动态申请。
调试时建议用 adb logcat 过滤 AndroidRuntime 和你的包名,崩溃堆栈一目了然。
5. 常见问题与排查技巧实录
5.1 编译期问题速查表
| 报错信息 | 根本原因 | 解决方案 |
|---|---|---|
cannot find symbol: class Preconditions |
隐藏 API 未 stub | 在 stub 模块声明 com.android.internal.util.Preconditions |
resource style/Theme.DeviceDefault not found |
私有资源引用 | 复制资源值到本地 res/values/ |
package com.android.internal.R does not exist |
内部 R 类缺失 | 改用本地 R 或动态获取资源 ID |
Could not install Gradle distribution |
网络问题 | 换国内镜像或使用本地 Gradle 离线包 |
Namespace not specified |
AGP 8.x 要求 | 在 build.gradle 加 namespace |
Duplicate class android.support.v4.* |
依赖冲突 | 统一用 AndroidX,移除旧 support 库 |
5.2 运行期问题排查
问题一:启动即崩,报 SecurityException: MANAGE_DOCUMENTS。
这是最常见的。DocumentsUI 在 onCreate 里会检查自己是否有 MANAGE_DOCUMENTS 权限,没有就抛异常。解决办法是找到这个检查点,改成 try-catch 或者直接注释掉。具体位置在 DocumentsActivity.java 的 onCreate 方法里,搜 MANAGE_DOCUMENTS 就能找到。
问题二:文件列表空白,什么都不显示。
大概率是 DocumentsProvider 没注册成功。DocumentsUI 通过 ContentResolver 查询所有已注册的 DocumentsProvider,如果你的应用没有系统权限,查询结果为空。解决办法是在 AndroidManifest.xml 里自己注册一个 DocumentsProvider,或者手动构造 Root 对象填充数据。
问题三:点击文件没反应。
Intent 解析失败。DocumentsUI 打开文件时通过 Intent.ACTION_VIEW 拉起对应的应用,如果设备上没有能处理该 MIME 类型的应用,就会静默失败。调试时可以在 onClick 里打日志,看 Intent 是否构造成功。
问题四:侧边栏的存储卷列表为空。
StorageManager.getStorageVolumes() 返回空列表。这是因为普通应用拿不到存储卷信息。降级方案是硬编码常见路径,比如 Environment.getExternalStorageDirectory(),或者用 MediaStore 查询。
5.3 几个独家避坑技巧
技巧一:用 BuildConfig 区分系统版和移植版。 在代码里加 if (BuildConfig.IS_PORTED) { ... } 判断,系统版走原逻辑,移植版走降级逻辑。这样一份代码可以同时维护两个版本。
技巧二:把隐藏 API 调用集中到一个 Compat 类里。 所有反射、stub 调用都封装在这个类里,其他代码只调 Compat 的方法。这样将来适配新系统版本时,只需要改一个文件。
技巧三:资源冲突用 tools:replace 解决。 如果和依赖库的资源名冲突,在 AndroidManifest.xml 的 <application> 标签里加 tools:replace="android:theme,android:label"。
技巧四:调试时关掉 R8 混淆。 minifyEnabled false 是必须的,否则隐藏 API 的反射调用会全部失效,报 NoSuchMethodException。
技巧五:用 adb shell dumpsys package 检查权限授予情况。 命令是 adb shell dumpsys package com.yourcompany.documentsui | grep permission,能看到哪些权限被授予、哪些被拒绝。
6. 移植后的扩展与定制方向
移植成功只是起点,真正有价值的是后续的定制。基于这套工程,你可以做几件事:
一是换 UI。DocumentsUI 的布局文件都在 res/layout/ 下,DirectoryFragment、RootsFragment、SearchFragment 这几个是核心。你可以直接改 XML,或者用 Compose 重写界面层,底层逻辑不动。
二是加云盘入口。实现一个自定义的 DocumentsProvider,在里面接入云盘 SDK,然后在 AndroidManifest.xml 里注册。DocumentsUI 会自动发现并展示你的 Provider,不需要改它的代码。
三是改文件类型识别。DocumentsUI 通过 MimeType 判断文件类型和图标,相关逻辑在 MimePredicate 和 IconUtils 里。你可以扩展 MIME 映射表,支持更多自定义格式。
四是接入 AI 能力。最近很火的端侧大模型,可以在文件管理器里加一个"智能分类"入口,用 GGUF 格式的模型做本地推理,把文件按内容自动归类。这个方向技术上可行,但要注意模型体积和推理性能的平衡。
五是适配多设备形态。DocumentsUI 原本主要面向手机,移植后可以适配平板、折叠屏、车机。res/layout-sw600dp/ 下加一套平板布局,res/layout-land/ 下加横屏布局,工作量不大但效果明显。
我个人在实际操作中的体会是,移植这件事最难的从来不是技术本身,而是耐心。几百个编译错误一个个解决,几十个运行时崩溃一个个排查,没有捷径可走。但一旦跑通,你就拥有了一个可以自由改造的文件管理器底座,后续所有的定制需求都变得可控。最后再分享一个小技巧:移植过程中每解决一类问题就提交一次 Git,这样万一改崩了可以快速回滚,比从头再来省事得多。