Flutter在Android 11及以上版本中重命名文件失败的问题解决

问题原因 #

1. Android 13的Scoped Storage机制限制：READ_MEDIA_IMAGES/READ_MEDIA_VIDEO仅授予读取媒体文件的权限，不包含修改、重命名文件的权限，直接通过File.rename()操作公共媒体目录（如DCIM、相册）的文件会被系统拦截。
2. 三星Galaxy S23 Ultra的系统权限管控更严格：对第三方应用操作公共媒体文件的限制比原生Android更苛刻，即使权限配置正确，也会触发PathAccessException。

解决办法 #

1. 优先使用MediaStore API修改媒体文件 #

Android 10及以上推荐通过MediaStore API操作公共媒体库的文件，这是符合Scoped Storage规范的方式，可借助Flutter的media_store插件实现。

2. 申请MANAGE_MEDIA特殊权限（仅Android 13+） #

如果需要批量管理媒体文件，可申请MANAGE_MEDIA权限，该权限允许应用完全控制媒体文件，但需引导用户到应用设置页面手动开启（无法通过常规弹窗申请）。使用permission_handler的示例：

import 'package:permission_handler/permission_handler.dart';

Future<void> requestManageMediaPermission() async {
  final status = await Permission.manageMedia.request();
  if (status.isDenied) {
    // 引导用户到设置页面开启权限
    await openAppSettings();
  }
}

3. 操作应用私有目录文件 #

如果文件是应用生成或存储在私有目录（如getApplicationDocumentsDirectory()），直接使用File.rename()即可，无需额外权限。

正确重命名方式 #

场景1：重命名公共媒体库文件（图片/视频） #

使用MediaStore API更新文件名：

import 'package:media_store/media_store.dart';
import 'package:path/path.dart' as path;

Future<bool> renamePublicMedia(String oldFilePath, String newFileName) async {
  final mediaStore = MediaStore();
  // 根据文件类型选择对应Uri：图片用externalContentUri，视频用videoMediaUri
  final baseUri = path.extension(oldFilePath).toLowerCase() == '.jpg' 
      ? MediaStore.images.externalContentUri 
      : MediaStore.video.externalContentUri;

  // 查询文件对应的MediaStore记录ID
  final cursor = await mediaStore.query(
    baseUri,
    projection: [MediaStore.MediaColumns._ID],
    selection: "${MediaStore.MediaColumns.DATA} = ?",
    selectionArgs: [oldFilePath],
  );

  if (cursor.moveToFirst()) {
    final mediaId = cursor.getInt(0);
    final contentUri = Uri.parse("${baseUri.path}/$mediaId");

    // 更新文件名
    final updateValues = {
      MediaStore.MediaColumns.DISPLAY_NAME: newFileName,
    };

    await mediaStore.update(contentUri, updateValues);
    return true;
  }
  return false;
}

场景2：重命名应用私有目录文件 #

直接使用Dart IO操作：

import 'dart:io';
import 'package:path_provider/path_provider.dart';

Future<void> renamePrivateFile(String oldFileName, String newFileName) async {
  final appDir = await getApplicationDocumentsDirectory();
  final oldFile = File('${appDir.path}/$oldFileName');
  final newFile = File('${appDir.path}/$newFileName');

  if (await oldFile.exists()) {
    await oldFile.rename(newFile.path);
  }
}

注意事项 #

• 避免直接用File.rename()操作公共媒体目录文件，这是Scoped Storage明确禁止的行为。
• MANAGE_MEDIA权限是高风险权限，仅在必要时使用，优先采用MediaStore API的方案。
• 操作前需确认文件路径正确，路径错误也可能触发权限异常提示。

内容的提问来源于stack exchange，提问作者Joel G Mathew