React Native Track Player 在 Android 12+ 上播放本地文件的技术解析

在 React Native 应用开发中，音频播放是一个常见需求。react-native-track-player 作为 React Native 生态中功能强大的音频播放库，为开发者提供了丰富的音频控制能力。然而，在 Android 12 及以上版本中，播放本地存储的音频文件会遇到一些特殊的权限和访问问题，这需要开发者特别注意。

问题背景

随着 Android 系统版本的升级，Google 不断加强对应用访问设备存储的限制。特别是在 Android 10(API 29)引入分区存储(Scoped Storage)后，Android 12 进一步收紧了应用对设备文件的访问权限。这些变更直接影响了 react-native-track-player 在 Android 设备上播放本地文件的能力。

核心问题分析

在 Android 12+ 设备上，应用尝试通过传统文件路径(如 file:///data/user/0/...)访问音频文件时，即使文件确实存在且权限声明完整，播放器也可能无法正常工作。这主要表现在：

1. 播放器状态停留在"ready"状态，但无实际音频输出
2. 控制台无任何错误信息输出
3. 文件路径验证通过，但播放器无法加载内容

技术解决方案

1. 使用 MediaStore API

Android 推荐的应用访问媒体文件的方式是通过 MediaStore API。这种方式不需要请求 MANAGE_EXTERNAL_STORAGE 权限，也不会受到 Google Play 审核的额外审查。

Uri audioUri = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI;

通过查询 MediaStore 获取音频文件的 URI，而不是直接使用文件路径，可以确保应用在最新 Android 版本上正常访问媒体文件。

2. 文件存储位置选择

对于需要长期保存的音频文件，应存储在以下位置之一：

• 应用的专属存储空间(Internal Storage)
• 共享的媒体目录(如 Music/或 Podcasts/)
• Downloads/目录(临时文件)

避免直接使用 /data/user/0/ 等系统内部路径，这些路径在 Android 高版本上受到严格限制。

3. 权限配置

在 AndroidManifest.xml 中，需要正确声明存储权限：

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

注意：从 Android 10 开始，WRITE_EXTERNAL_STORAGE 权限对媒体文件的写入不再有效，应使用 MediaStore API。

4. react-native-track-player 配置

在 React Native 代码中，确保正确初始化播放器并设置适当的选项：

await TrackPlayer.setupPlayer();
await TrackPlayer.updateOptions({
  android: {
    alwaysPauseOnInterruption: true,
    appKilledPlaybackBehavior: AppKilledPlaybackBehavior.ContinuePlayback,
  },
  // 其他配置...
});

最佳实践建议

1. 对于应用专属的音频文件，优先存储在应用的内部存储目录
2. 对于用户可见的音频文件，使用 MediaStore API 访问
3. 避免使用 MANAGE_EXTERNAL_STORAGE 权限，除非绝对必要
4. 测试时使用真实的 Android 设备，模拟器可能无法完全复现存储权限问题
5. 实现完善的错误处理机制，捕获并处理可能的文件访问异常

兼容性考虑

针对不同 Android 版本，应考虑实现不同的文件访问策略：

• Android 10 以下：可以使用传统文件路径
• Android 10-11：需要逐步迁移到分区存储
• Android 12+：必须使用 MediaStore API 或应用专属存储

通过遵循这些指导原则，开发者可以确保 react-native-track-player 在各种 Android 版本上都能可靠地播放本地音频文件，同时满足最新的平台安全要求。