Android 10+ 文件操作适配：3种SD卡写入方案对比与Scoped Storage实战-平芜编程栈

Android 10+ 文件操作适配：3种SD卡写入方案深度解析与实战指南

1. 理解Scoped Storage的核心变革

Android 10引入的分区存储机制（Scoped Storage）彻底改变了应用访问外部存储的方式。这项变革的核心目标是保护用户隐私和数据安全，防止应用随意访问其他应用的私有数据。在传统模式下，一个简单的文件管理器应用就能扫描整个设备存储，这显然存在严重的安全隐患。

新机制下，应用对存储空间的访问被划分为三个明确区域：

应用私有目录：每个应用独有的沙盒空间，路径通常为/storage/emulated/0/Android/data/<package_name>/。在这里，应用拥有完整的读写权限，无需任何额外授权。
媒体集合：包括图片、视频、音频等公共媒体文件，通过MediaStore API访问。应用可以读取这些文件，但写入需要用户授权。
下载集合：包含Documents、Downloads等特定目录，通过Storage Access Framework(SAF)访问。

关键限制变化：

// 传统方式 - Android 9及以下有效 val file = File("/storage/emulated/0/CustomFolder/data.txt") file.createNewFile() // 在Android 10+上会抛出异常

2. 三种SD卡写入方案对比分析

2.1 方案一：直接申请MANAGE_EXTERNAL_STORAGE权限

这是最"暴力"的解决方案，通过声明MANAGE_EXTERNAL_STORAGE权限获取近似root的存储访问能力。但Google Play对这类应用有严格审核：

适用场景：

文件管理器类应用
系统备份/恢复工具
杀毒软件等安全应用

实现步骤：

在AndroidManifest.xml中添加声明：

<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

检查并请求权限：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { if (!Environment.isExternalStorageManager()) { val intent = Intent(Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION) startActivity(intent) } }

优缺点对比：

优点	缺点
完全绕过Scoped Storage限制	需要用户手动在系统设置中授权
保持传统File API使用方式	Google Play审核严格，非核心功能会被拒绝
兼容旧代码成本低	可能被部分应用商店标记为高风险

提示：小米等厂商设备需要额外提交功能证明材料才能上架应用商店

2.2 方案二：使用DocumentFile API适配

DocumentFile是Android系统提供的兼容性API，它在File类基础上增加了对内容URI的支持，成为Scoped Storage下的推荐方案。

典型使用场景：

// 获取Downloads目录的DocumentFile实例 val downloadsUri = Uri.parse("content://com.android.externalstorage.documents/tree/primary%3ADownloads") val downloadsDir = DocumentFile.fromTreeUri(context, downloadsUri) // 创建新文件 val newFile = downloadsDir?.createFile("text/plain", "log.txt") newFile?.uri?.let { uri -> context.contentResolver.openOutputStream(uri)?.use { os -> os.write("Hello Scoped Storage".toByteArray()) } }

关键优势：

自动适配不同Android版本
支持URI持久化权限
提供与File类相似的API接口

性能对比测试数据：

操作类型	File API(ms)	DocumentFile(ms)
创建100个1KB文件	120	180
读取100个文件属性	80	150
递归遍历目录(100文件)	50	300

2.3 方案三：通过SAF让用户选择目录

Storage Access Framework(SAF)是Android 4.4引入的系统级文件选择器，在Scoped Storage下成为访问非媒体文件的唯一官方推荐方案。

完整实现流程：

val intent = Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply { flags = Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION or Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION putExtra(DocumentsContract.EXTRA_INITIAL_URI, initialUri) } startActivityForResult(intent, REQUEST_CODE_DIRECTORY_PICK)

处理选择结果并获取持久权限：

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { if (requestCode == REQUEST_CODE_DIRECTORY_PICK && resultCode == RESULT_OK) { data?.data?.let { treeUri -> // 获取持久访问权限 contentResolver.takePersistableUriPermission( treeUri, Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION ) // 保存URI供后续使用 Prefs.saveDirectoryUri(treeUri.toString()) } } }

fun createFileInSelectedDir(context: Context, fileName: String, mimeType: String): Uri? { val treeUri = Uri.parse(Prefs.getDirectoryUri()) return DocumentsContract.createDocument( context.contentResolver, treeUri, mimeType, fileName ) }

SAF的限制与注意事项：

Android 11+禁止访问Android/data和Android/obb目录
不同设备厂商可能定制文件选择器界面
获取的URI在应用卸载后失效
批量操作性能较差，不适合高频IO场景

3. 实战：文件下载功能的多版本适配

以下是一个完整的文件下载实现，兼容Android 5.0到最新版本：

class FileDownloader(private val context: Context) { companion object { private const val REQUEST_CODE_DIRECTORY = 1024 private const val DOWNLOAD_DIR = "Download" } fun downloadFile(url: String, fileName: String) { when { // Android 10+ 使用SAF方案 Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q -> { if (Prefs.hasDirectoryUri()) { downloadWithSAF(Uri.parse(Prefs.getDirectoryUri()), url, fileName) } else { requestDirectoryPermission() } } // Android 6-9 使用传统权限方案 Build.VERSION.SDK_INT >= Build.VERSION_CODES.M -> { if (checkSelfPermission(WRITE_EXTERNAL_STORAGE) == PERMISSION_GRANTED) { downloadLegacy(url, fileName) } else { requestPermissions(arrayOf(WRITE_EXTERNAL_STORAGE), REQUEST_CODE_PERMISSION) } } // Android 5及以下版本 else -> downloadLegacy(url, fileName) } } private fun downloadWithSAF(directoryUri: Uri, url: String, fileName: String) { try { val docFile = DocumentFile.fromTreeUri(context, directoryUri) val newFile = docFile?.createFile(getMimeType(fileName), fileName) newFile?.uri?.let { uri -> val outputStream = context.contentResolver.openOutputStream(uri) OkHttpClient().newCall(Request.Builder().url(url).build()).enqueue( object : Callback { override fun onFailure(call: Call, e: IOException) { // 处理下载失败 } override fun onResponse(call: Call, response: Response) { response.body?.byteStream()?.use { input -> outputStream?.use { output -> input.copyTo(output) } } } } ) } } catch (e: Exception) { // 处理异常 } } private fun downloadLegacy(url: String, fileName: String) { val downloadDir = Environment.getExternalStoragePublicDirectory(DOWNLOAD_DIR) if (!downloadDir.exists()) downloadDir.mkdirs() val targetFile = File(downloadDir, fileName) OkHttpClient().newCall(Request.Builder().url(url).build()).enqueue( object : Callback { override fun onFailure(call: Call, e: IOException) { // 处理下载失败 } override fun onResponse(call: Call, response: Response) { response.body?.byteStream()?.use { input -> FileOutputStream(targetFile).use { output -> input.copyTo(output) } } } } ) } private fun getMimeType(fileName: String): String { return when { fileName.endsWith(".pdf") -> "application/pdf" fileName.endsWith(".txt") -> "text/plain" // 其他MIME类型判断 else -> "application/octet-stream" } } }

4. 疑难问题排查与性能优化

4.1 常见问题解决方案

问题一：SAF返回的URI权限丢失

现象：应用重启后无法访问之前获取的目录URI

解决方案：

// 在Application或主Activity的onCreate中恢复权限 Prefs.getDirectoryUri()?.let { uriString -> val uri = Uri.parse(uriString) try { contentResolver.takePersistableUriPermission( uri, Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION ) } catch (e: SecurityException) { // URI权限已失效，需要重新获取 Prefs.clearDirectoryUri() } }

问题二：大文件操作超时

当通过ContentResolver操作大文件时，可能会因IPC通信超时导致失败。建议采用分块写入策略：

fun writeLargeFile(uri: Uri, inputStream: InputStream) { val buffer = ByteArray(1024 * 1024) // 1MB缓冲区 var outputStream: OutputStream? = null try { outputStream = contentResolver.openOutputStream(uri) var bytesRead: Int while (inputStream.read(buffer).also { bytesRead = it } != -1) { outputStream?.write(buffer, 0, bytesRead) outputStream?.flush() // 定期刷新缓冲区 } } finally { outputStream?.close() inputStream.close() } }

4.2 性能优化建议

批量操作优化：

// 不好的实践：逐个文件操作 files.forEach { file -> val docFile = parentDir.createFile(mimeType, file.name) copyFileToDocument(file, docFile) } // 优化方案：批量处理 val batch = ArrayList<Pair<File, DocumentFile>>() files.forEach { file -> val docFile = parentDir.createFile(mimeType, file.name) batch.add(file to docFile) } // 使用线程池并行处理 val executor = Executors.newFixedThreadPool(4) batch.forEach { (file, docFile) -> executor.submit { copyFileToDocument(file, docFile) } } executor.shutdown()

缓存策略：

// 建立DocumentFile到本地路径的映射缓存 val documentCache = LruCache<String, DocumentFile>(100) fun getCachedDocument(path: String): DocumentFile? { return documentCache.get(path) ?: run { val doc = queryDocument(path) doc?.let { documentCache.put(path, it) } doc } }

IO操作最佳实践：

使用缓冲流（BufferedInputStream/BufferedOutputStream）
避免在主线程执行文件操作
对频繁访问的文件考虑内存映射(MappedByteBuffer)

5. 版本兼容性处理与测试要点

5.1 多版本兼容策略

建议采用如下兼容性方案矩阵：

Android版本	推荐方案	备选方案
5.0及以下	传统File API	-
6.0-9.0	WRITE_EXTERNAL_STORAGE权限+File API	DocumentFile
10.0-12.0	DocumentFile/SAF	MANAGE_EXTERNAL_STORAGE(特殊场景)
13.0+	SAF优先	DocumentFile(私有目录)

5.2 关键测试场景

权限测试矩阵：

测试场景	预期结果
授予MANAGE_EXTERNAL_STORAGE权限	可访问所有存储位置
拒绝MANAGE_EXTERNAL_STORAGE权限	只能访问授权目录
撤销SAF目录授权	相关操作应失败并提示
从备份恢复应用	URI权限应保持有效

跨厂商兼容性测试：

重点关注以下厂商的特殊行为：

小米：可能对SAF有定制修改
华为：EMUI的文件管理器差异
三星：One UI对存储权限的特殊处理
OPPO/Vivo：可能限制后台文件操作

性能测试指标：

100个1MB文件的批量写入时间
目录遍历响应时间(包含1000个文件)
低内存设备上的稳定性表现
长时间运行的资源泄漏检测

在实际项目中，我们发现采用分层架构能有效处理这些兼容性问题。将文件操作抽象为统一接口，不同版本实现具体细节：

interface StorageManager { fun createFile(fileName: String): Boolean fun copyFile(source: Uri, destName: String): Boolean fun listFiles(): List<FileInfo> } // Android 10+实现 class ScopedStorageManager(val context: Context) : StorageManager { override fun createFile(fileName: String): Boolean { // 使用SAF或DocumentFile实现 } } // 传统实现 class LegacyStorageManager : StorageManager { override fun createFile(fileName: String): Boolean { // 使用File API实现 } } // 统一入口 fun getStorageManager(context: Context): StorageManager { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { ScopedStorageManager(context) } else { LegacyStorageManager() } }