You need to enable JavaScript to run this app. Retrofit实现PDF下载时Android10小米9出现只读文件系统写入异常
优惠活动
大模型
产品
解决方案
定价
更多

Retrofit实现PDF下载时Android10小米9出现只读文件系统写入异常

问题根因定位
  • 首次抛出EROFS (Read-only file system)的核心原因:最初调用saveToFile("1606998235369.pdf")时传入的是裸文件名,没有拼接合法的绝对可写路径。Android 10正式落地分区存储(Scoped Storage)机制后,这类无路径前缀的文件名会被系统解析到只读的系统挂载根目录,就算已经授予了存储权限,应用也没有这个根目录的写入权限,因此直接触发只读文件系统异常。
  • 已获取存储权限仍报错的本质:Android 10及以上版本,WRITE_EXTERNAL_STORAGE权限不再提供全局公共存储的自由写入能力,仅在清单中临时设置requestLegacyExternalStorage="true"关闭分区存储的过渡场景下,这个权限才会生效。小米基于Android 10的MIUI系统对存储权限的管控比原生系统更严格,就算权限弹窗显示已授予,也不会开放对无明确路径位置的写入权限。
  • 改用应用专属外部目录后运行异常的可能原因:getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)返回的应用私有外部目录本就不需要任何存储权限即可读写,如果这一步仍报错,通常是外部存储未完成挂载、临时文件创建时父目录不存在导致的创建失败,或是旧的裸路径调用逻辑没有完全移除,仍在触发原路径的崩溃。
适配Android 10的PDF下载稳定实现方案

方案1:保存到应用私有目录(无权限需求,兼容性最好)

这种方式从Android 10到最新版本的系统都不需要申请任何存储权限,完全绕开分区存储的限制,是最稳定的实现路径:

  • 首先调整Retrofit接口定义,避免一次性把整个PDF读入内存触发OOM,使用流式接收:
@Streaming
@GET
suspend fun downloadPdf(@Url pdfUrl: String): Response<ResponseBody>
  • 配套的流式保存实现,替换之前的字节数组写入逻辑:
private suspend fun ResponseBody.saveToPrivateDownload(context: Context, fileName: String): File {
    // 构建应用私有外部下载目录下的PDF缓存目录
    val targetDir = File(context.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS), "pdf_cache").apply {
        if (!exists()) mkdirs()
    }
    val targetFile = File(targetDir, fileName)
    // 自动管理流的开闭,边下载边写入
    byteStream().use { input ->
        FileOutputStream(targetFile).use { output ->
            input.copyTo(output)
        }
    }
    return targetFile
}
  • 调用时通过协程切到IO线程执行文件读写操作,完成后再切回主线程做UI提示,避免主线程做IO触发ANR。

方案2:保存到系统公共Download目录(用户可直接在文件管理器访问)

如果需要让保存的PDF对其他应用、用户可见,Android 10以上不要使用老式的公共目录绝对路径(该路径在Android 10以上已为只读),直接通过MediaStore API写入:

private fun savePdfToPublicDownload(context: Context, pdfBytes: ByteArray, fileName: String): Uri? {
    val resolver = context.contentResolver
    val saveValues = ContentValues().apply {
        put(MediaStore.Downloads.DISPLAY_NAME, fileName)
        put(MediaStore.Downloads.MIME_TYPE, "application/pdf")
        put(MediaStore.Downloads.RELATIVE_PATH, Environment.DIRECTORY_DOWNLOADS)
    }
    // 插入下载记录获取可写的Uri
    val targetUri = resolver.insert(MediaStore.Downloads.EXTERNAL_CONTENT_URI, saveValues) ?: return null
    resolver.openOutputStream(targetUri)?.use { output ->
        output.write(pdfBytes)
        output.flush()
    }
    return targetUri
}

这种方式同样不需要申请任何存储权限,完全符合分区存储的规则,保存的文件会直接出现在系统下载目录中。

原有实现的避坑点
  • 禁止在主线程执行文件读写操作,原崩溃栈显示逻辑运行在main线程,就算路径正确,大文件IO也会触发ANR
  • 不要将裸文件名直接传入File()构造器,必须通过系统提供的可写目录路径拼接文件名,否则会被系统解析到只读路径
  • 切换到应用私有目录后,可直接移除原有的READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE权限申请,这类权限对私有目录写入无意义,还会在Android 13以上版本触发不必要的权限弹窗
  • 调用File.createTempFile()前,必须确保传入的父目录存在,否则会抛出文件不存在异常

内容的提问来源于stack exchange,提问作者Костянтин Лотиш

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.15 06:45:03