在项目中经常看到日志里堆满了第三方 SDK 的文件权限警告。升级库又懒得动，甚至有的库已经停止维护。于是只能先把 Android 文件读写、分享的方案理清楚，等真的卡住再去源码层面自行修改。

一、目录选型教程

二、权限规则概览

. App 自己目录：不需要声明任何存储权限

val filesDir = context.filesDir // /data/data/.../files/
val cacheDir = context.cacheDir // /data/data/.../cache/
val externalFiles = context.getExternalFilesDir // /Android/data/.../files/
val externalCache = context.externalCacheDir // /Android/data/.../cache/

这些方法在所有 Android 版本均可直接读写。老实说，

. 访问相册图片 / 视频 / 音频

Android 13 及以上：

Android 12 以下：

官方说明的观点是。读取其他 App 创建的媒体文件必须声明对应媒体读取权限；而自己通过 MediaStore 写入的媒体文件则无需额外权限。

. 写入图片、视频、音频或下载文件

• Android 13+：直接使用 MediaStore API，无需任何存储权限。
• Android 12-：If you still target legacy external storage,add {@code WRITE_EXTERNAL_STORAGE} 或者改为写入自己的专属目录。

. PDF / Excel / ZIP / TXT 等普通文档——推荐使用 SAF

• {@code ACTION_CREATE_DOCUMENT} → 使用者自行选择保存位置。
• {@code ACTION_OPEN_DOCUMENT} → 使用者自行选择打开位置。

SFA 在 Android 4.4+ 可用。且在 Android 10+ 完全不需要传统存储权限，是解决「第三方 SDK 权限冲突」的优先考虑方案。

三、Manifest 中需要声明的权限集合

四、通用文件存储实现示例

. 保存 App 私有文件

fun savePrivateFile {
val file = File
file.writeText
}
fun readPrivateFile: String =
File.takeIf { it.exists }?.readText，: ""

. 保存外部专属文件

fun saveExternalLog: File?{
val dir = context.getExternalFilesDir?: return null
if ) dir.mkdirs
val file = File
file.writeText
return file
}
# 示例方法：
# /storage/emulated/0/Android/data/com.example.app/files/logs/app.log

. 保存图片到相册

fun saveImageToGallery(
context: Context。displayName: String,bitmapData: ByteArray
): Uri?{
val resolver = context.contentResolver
val values = ContentValues.apply {
put
put
if {
put
put
}
}
val uri = resolver.insert(
MediaStore.Images.Media.EXTERNAL_CONTENT_URI,values
)?其实，的观点是，return null
resolver.openOutputStream?.use { it.write }
if {
values.clear
values.put
resolver.update
}
return uri
}

. 保存任意文件到 Download 文件夹

fun saveFileToDownloads(
context: Context。fileName: String,mimeType: String,data: ByteArray
): Uri?{
if {
val resolver = context.contentResolver
val values = ContentValues.apply {
put
put
put(MediaStore.Downloads.RELATIVE_PATH。Environment.DIRECTORY_DOWNLOADS + "/MyApp")
put
}
val uri = resolver.insert(
MediaStore.Downloads.EXTERNAL_CONTENT_URI,values
)?这方面，return null
resolver.openOutputStream?.use { it.write }
values.clear
values.put
resolver.update
return uri
}
return null // 对低版本请走 legacy 方法或 SAF
}

@Suppress
fun saveFileToDownloadsLegacy: File {
val dir = Environment.getExternalStoragePublicDirectory
if ) dir.mkdirs
val file = File
file.writeBytes
return file
}
# 必须在 Manifest 中声明 WRITE_EXTERNAL_STORAGE 并在运行时申请该权限。
# 示例：
# 

. 使用 SAF：让使用者自行决定保存位置

// 打开程序保存对话框，让使用者挑选位置
fun launchCreateDocument {
val intent = Intent.apply {
addCategory
type = "application/pdf"
putExtra
}
activity.startActivityForResult
}
// 将字符串写入使用者选中的 Uri
fun writeStringToUri {
uri?这方面，return
context.contentResolver.openOutputStream?.use { it.write) }
}

. 使用 SAF：让使用者打开已有文档并读取内容

fun launchOpenDocument {
val intent = Intent.apply {
addCategory
type = "*/*"
}
activity.startActivityForResult
}
fun readBytesFromUri: ByteArray =
if ByteArray
else context.contentResolver.openInputStream?.use { it.readBytes }?: ByteArray

五、运行时动态申请存储相关权限

fun requestStoragePermission {
when {
Build.VERSION.SDK_INT>= Build.VERSION_CODES.TIRAMISU -> {
// Android 13+ 已经细分为 READ_MEDIA_*
ActivityCompat.requestPermissions(
activity,arrayOf(
Manifest.permission.READ_MEDIA_IMAGES,Manifest.permission.READ_MEDIA_VIDEO,Manifest.permission.READ_MEDIA_AUDIO
),REQUEST_CODE_STORAGE
)
}
Build.VERSION.SDK_INT>= Build.VERSION_CODES.M -> {
ActivityCompat.requestPermissions(
activity,arrayOf。REQUEST_CODE_STORAGE
)
}
else -> { /* 不需要运行时请求 */ }
}
}

场景 需求类型 推荐实现方式 保存登录信息／配置信息 小体积、安全性高 filesDir + Kotlin I/O API 缓存临时数据 可随时被程序清理 cacheDir 或者 getExternalCacheDir 日志、大缓存或导出临时文件 使用者不必直接看到 context.getExternalFilesDir 或 getExternalCacheDir 无需任何运行时权限 图片／视频／音频保存到相册 希望使用者能在程序相册里看到 MediaStore Images / Video / Audio API Android 13+ 完全免权⽤；低版本加 READ_/WRITE_EXTERNAL_STORAGE PDF／Excel／ZIP 等普通文档导出 交给使用者自行决定保存位置 SAF – ACTION_CREATE_DOCUMENT + writeStringToUri 兼容所有 Android 4.4+。无需传统存储权限 从手机中挑选已有文档上传或预览 SAF – ACTION_OPEN_DOCUMENT + readBytesFromUri 下载后让使用者直接查看或分享 MediaStore.Downloads 或 SAF + Intent.FLAG_GRANT_READ_URI_PERMISSION 安装 APK 、调用相机拍照或分享图片给微信/QQ 等第三方 App FileProvider + content:// URI + intent.addFlags 必须使用，否则会抛出 FileUriExposedException ⚠️ 除非你在实现「全盘扫描」类功能，否则不要尝试遍历整个外部存储。不过，只有 MediaStore 或 SAF 能合法访问其他 App 的私有目录。

七、FileProvider —— 安全共享本地文件给其他 App 的必备利器

"FileProvider 不负责把文件写进去，它只负责把已经存在的本地方法包装成安全的 content:// URI 并授予目标 App 临时访问权。" 以下场景必须使用它：

• 安装 APK 时启动安装页面；
• 调用程序相机拍照并要求将照片保存在自己指定的位置；
• 分享到微信/QQ/DingTalk/E‑mail/Browse 等第三方应用；
• 打开 PDF / Excel / Word 等非 MediaStore 类型的文档；
• 把本地日志发给技术支持人员。

• 读取或写入自己 app 私有目录；无需任何额外 URI 包装。
• 通过 MediaStore 插入获取到的 URI 本身已经是 content:// 格式；
• 使用 SAF 打开的文档一样返回 content:// URI。

九、FileProvider 配置步骤 ​:

 

>

h three= ""id= provider-config-xml"">res/xml/file_paths.xml：

pre code= ' language - xml '>& lt?xml version ="1.0" encoding ="utf-8"?>



&lt，其实，/ paths &
gt;

h # 十 、完整代码示例——分享位于 APP 专属目录下的 PDF 文件 

pre code= ' language - kotlin '>
// 假设 pdf 位于： getExternalFilesDir/test.pdf
val pdfFile = File,"test.pdf")
val pdfUri = FileProvider.getUriForFile(
this,"${packageName}.fileprovider"。pdfFile ) 

val intent = Intent.apply {
setDataAndType
addFlags
}
startActivity

h two id= 'relation-with-media-store-saf' strong="">十一 、FileProvider 与 MediaStore / SAF 的关系表：


'
'

'
'

'
'

','否','content://com.android.providers.media.documents/...','' )'
'

'
'

'
'


'方案'







整理完后你会发现大部分业务都可以避开繁琐的传统存储权限，只要合理选择「私有」「专属」「MediaStore」或「SAF」四种方案即可。如果真的碰到第三方 SDK 报错无法兼容，再回头去源码层面改成基于 {@link ContentResolver} 的方式或者自行实现一个轻量级 {@link FileProvider} 来解决冲突。