Flutter FileSystemEntity在三星设备上无法加载全部文件问题排查

核心原因 #

• 大小写后缀匹配问题：三星设备上WhatsApp存储的媒体文件、系统生成的媒体文件后缀常为大写格式（.JPG/.JPEG/.PNG/.MP4），你当前代码只匹配小写后缀，会导致文件过滤时全部被排除。
• 权限适配缺失：
  1. Android 13及以上版本Permission.storage已废弃，需单独申请READ_MEDIA_IMAGES、READ_MEDIA_VIDEO权限，三星One UI对存储权限的管控比原生安卓更严格，未申请对应权限时会直接返回空目录列表。
  2. 你要访问的WhatsApp Business目录属于其他应用的公共存储目录，Android 11以上作用域存储规则下，普通存储权限无法访问该类目录，需申请MANAGE_EXTERNAL_STORAGE（管理所有文件）权限，多数非三星厂商对该权限的限制较宽松，但三星默认会拒绝第三方应用的该权限申请，需引导用户手动开启。
• 路径拼接逻辑兼容性问题：三星部分机型的内置/外置存储路径前缀和原生安卓存在差异，你直接通过split("Android")拼接路径的逻辑可能生成不存在的无效路径，导致目录判断await Directory(path).exists()直接返回false。
• 隐藏目录访问限制：你访问的.Statuses是点开头的隐藏目录，One UI部分版本默认禁止第三方应用枚举隐藏目录的内容，需额外适配。

修复方案 #

1. 修复文件后缀匹配逻辑，改为不区分大小写判断：

// 原视频匹配逻辑替换为
List<FileSystemEntity> videoFiles = dirFiles.where((f) => f.path.toLowerCase().contains('.mp4')).toList();
// 原图片匹配逻辑替换为
List<FileSystemEntity> imageFiles = dirFiles.where((element) =>
    element.path.toLowerCase().contains('.jpg') ||
    element.path.toLowerCase().contains('.jpeg') ||
    element.path.toLowerCase().contains('.png')).toList();

2. 适配存储权限：

• 在项目android/app/src/main/AndroidManifest.xml中添加对应权限声明：

<!-- Android 12及以下通用存储权限 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<!-- Android 13及以上媒体权限 -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<!-- 访问第三方应用公共目录所需的全文件管理权限 -->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

• 权限申请逻辑改为分安卓版本适配，申请对应权限后引导用户手动开启管理所有文件权限。

3. 优化路径拼接逻辑：不要硬编码拆分路径，可优先读取系统公共存储根路径，再拼接WhatsApp对应目录，避免厂商定制路径导致的不兼容问题。
4. 若仍无法读取，可改用存储访问框架（SAF）引导用户授权访问对应.Statuses目录，绕过厂商权限限制。

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