Android中使用Coil通过Uri加载图片并启动时展示的问题

核心原因 #

你遇到的问题大多是因为Uri的临时权限失效，或者Uri存储/恢复方式不正确。系统返回的媒体文件Uri通常带有临时访问权限，App重启后这个权限会丢失，导致Coil无法读取图片资源。

解决方案 #

1. 申请持久化Uri权限 #

在选择图片的回调中，必须向系统申请持久化访问权限，这样App重启后仍能访问该Uri对应的资源。

示例代码（Jetpack Compose + ActivityResultContracts）：

// 注册图片选择回调
val pickImageLauncher = registerForActivityResult(ActivityResultContracts.OpenDocument()) { uri: Uri? ->
    uri?.let {
        // 申请持久化读写权限
        val persistFlags = Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION
        requireContext().contentResolver.takePersistableUriPermission(it, persistFlags)
        
        // 将Uri字符串存储到SharedPreferences（或其他持久化存储）
        val prefs = PreferenceManager.getDefaultSharedPreferences(requireContext())
        prefs.edit().putString("saved_image_uri", it.toString()).apply()
    }
}

// 触发选择图片
pickImageLauncher.launch(arrayOf("image/*"))

2. 正确恢复并加载Uri #

从存储中读取Uri字符串并解析为Uri对象，直接传入Coil的AsyncImage或rememberAsyncImagePainter即可。同时建议添加错误监听，方便排查加载失败的具体原因。

示例代码（Compose页面启动时加载）：

@Composable
fun SavedImageScreen() {
    val prefs = PreferenceManager.getDefaultSharedPreferences(LocalContext.current)
    val savedUriString = prefs.getString("saved_image_uri", null)
    val savedUri = savedUriString?.let { Uri.parse(it) }

    AsyncImage(
        model = savedUri,
        contentDescription = "已保存的图片",
        modifier = Modifier.fillMaxSize(),
        // 加载失败时显示提示，或打印错误日志
        error = {
            Column(Modifier.fillMaxSize(), horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.Center) {
                Text("图片加载失败")
                // 可选：打印错误信息
                LaunchedEffect(it) {
                    (it as? ImageLoadState.Error)?.throwable?.printStackTrace()
                }
            }
        }
    )
}

3. 排查常见问题 #

• 避免手动复制Uri：手动复制的Uri可能不包含正确的权限信息，必须使用系统返回的Uri并经过持久化权限申请后再存储。
• 检查Android版本权限：Android 10及以上使用MediaStore访问媒体文件无需READ_EXTERNAL_STORAGE，但仍需申请持久化Uri权限；Android 9及以下需要在Manifest中声明READ_EXTERNAL_STORAGE权限。
• 验证Uri有效性：可以在恢复Uri后，通过ContentResolver查询是否能获取到文件信息，确认Uri是否有效：

savedUri?.let {
    val cursor = requireContext().contentResolver.query(it, null, null, null, null)
    cursor?.use { c ->
        if (c.moveToFirst()) {
            // Uri有效，能获取到文件信息
        } else {
            // Uri无效
        }
    }
}

内容的提问来源于stack exchange，提问作者Equlo