Android 11如何申请权限将文件下载到指定目录？

Question

在Android 11（API 30）中，应用无法通过传统方式直接写入外部存储的任意目录，即使申请了`WRITE_EXTERNAL_STORAGE`权限。开发者常遇到的问题是：如何在无需用户手动选择文件夹的前提下，将文件下载并保存到如`/Download/MyApp/`这样的指定子目录？由于Scoped Storage的限制，直接使用`FileOutputStream`会触发安全异常。该如何正确使用`MediaStore API`或`Storage Access Framework`实现自动下载至自定义目录，同时兼顾用户体验与权限合规性？

Answer 1

Android 11（API 30）下实现自动下载至自定义目录的合规方案

1. 背景与问题剖析：Scoped Storage 的引入与影响

从 Android 10（API 29）开始，Google 引入了 Scoped Storage 模型，旨在提升用户隐私和数据安全。到了 Android 11（API 30），这一机制进一步强化，应用对公共外部存储的访问受到严格限制。

• 传统方式使用 FileOutputStream 写入如 /Download/MyApp/ 的路径会触发 SecurityException。
• 即使声明了 WRITE_EXTERNAL_STORAGE 权限，在 API 30+ 上也无法绕过作用域存储限制。
• 开发者面临的核心挑战是：如何在不依赖用户手动选择文件夹的前提下，实现文件自动下载并保存到特定子目录？

2. 技术演进路径：从 File 到 MediaStore 与 SAF

为应对 Scoped Storage 的约束，Android 提供了两种主流替代方案：

1. MediaStore API：适用于媒体类文件（图片、音频、视频）及通用文件（通过 Downloads Collection）。
2. Storage Access Framework (SAF)：提供树形目录访问能力，适合需要持久化访问任意目录的场景。

两者各有适用边界，选择取决于业务需求与用户体验权衡。

3. 方案一：使用 MediaStore API 实现自动写入 Download 子目录

对于大多数非敏感应用，推荐优先使用 MediaStore.Downloads 集合创建结构化路径。

val contentValues = ContentValues().apply {
    put(MediaStore.Downloads.DISPLAY_NAME, "my_file.pdf")
    put(MediaStore.Downloads.MIME_TYPE, "application/pdf")
    put(MediaStore.Downloads.RELATIVE_PATH, "Download/MyApp/")
    put(MediaStore.Downloads.IS_PENDING, 1)
}

val resolver = context.contentResolver
val uri = resolver.insert(MediaStore.Downloads.EXTERNAL_CONTENT_URI, contentValues)

uri?.let { downloadUri ->
    resolver.openOutputStream(downloadUri).use { output ->
        // 执行下载逻辑，写入数据
        output?.write(fileData)
    }

    // 标记完成
    contentValues.clear()
    contentValues.put(MediaStore.Downloads.IS_PENDING, 0)
    resolver.update(downloadUri, contentValues, null, null)
}

此方法无需额外权限（WRITE_EXTERNAL_STORAGE 在 API 30+ 已失效），完全符合 Google Play 政策。

4. 方案二：Storage Access Framework 实现持久化目录访问

若需长期管理自定义目录（如同步工具、备份应用），可结合 SAF 与 DocumentTree 实现。

步骤	说明
1. 请求目录授权	Intent(Intent.ACTION_OPEN_DOCUMENT_TREE)
2. 用户选择 /Download/MyApp	返回持久化 URI
3. 使用 takePersistableUriPermission	获取长期访问权限
4. 后台自动写入	通过 DocumentFile API 创建/写入文件

5. 流程图：SAF 持久化目录访问流程

graph TD
    A[启动应用] --> B{是否已获目录权限?}
    B -- 是 --> C[使用 DocumentFile 写入]
    B -- 否 --> D[发起 ACTION_OPEN_DOCUMENT_TREE]
    D --> E[用户选择 /Download/MyApp]
    E --> F[takePersistableUriPermission]
    F --> G[缓存 URI]
    G --> C
    C --> H[文件成功保存]

6. 关键技术点对比分析

以下为不同方案在权限、用户体验、维护成本上的综合比较：

方案	权限要求	用户交互	适用场景	合规性
MediaStore	无特殊权限	无感知	常规下载	高
SAF + Tree	首次需用户授权	一次弹窗	长期管理目录	高
Legacy Mode	requestLegacyExternalStorage	无	迁移到 API 30 的旧应用	低（仅过渡）

7. 最佳实践建议与注意事项

• 避免滥用 MANAGE_EXTERNAL_STORAGE（All Files Access），该权限审核严格且易被拒。
• 优先使用 RELATIVE_PATH 在 Downloads 中构建层级结构，例如："Download/MyApp/Images/"。
• 处理好 IS_PENDING 状态，防止文件被媒体扫描器提前索引。
• SAF 授权后应持久化 URI 并监听 onActivityResult 结果。
• 测试时注意模拟器与真实设备的行为差异，尤其是 OEM 厂商定制系统。
• 考虑降级兼容：对 API < 30 设备仍可使用传统 File 路径。
• 使用 ContentResolver 统一接口抽象 I/O 操作，提升代码可维护性。
• 监控 Google Play 政策更新，及时调整存储策略。
• 日志记录关键路径异常，便于线上问题排查。
• 结合 WorkManager 实现后台可靠下载任务调度。