Flutter Android端如何保存非图片文件以实现跨应用即时可见？

阿华AIGC实验室

2026-4-28

解决Flutter Android中文档无法在其他应用附件中显示的问题

这个问题我之前也踩过坑，核心原因其实是Android系统不会自动扫描应用保存的文件并更新媒体库索引——邮件客户端这类应用在选择附件时，依赖的是系统媒体库的文件列表，而非直接遍历文件系统。所以哪怕文件实实在在存在，没被系统索引到，其他应用就看不到它。下面是具体的解决思路和实现方案：

一、先选对存储路径

首先要确保你把文件存到外部公共存储目录，而不是应用的私有目录。应用私有目录（比如getApplicationDocumentsDirectory()）属于应用专属空间，其他应用没有访问权限，哪怕触发扫描也看不到。推荐用：

import 'package:path_provider/path_provider.dart';

// 获取外部公共文档目录
final directory = await getExternalPublicDirectory(DirectoryType.documents);
// 拼接目标文件路径
final filePath = '${directory.path}/your_document.pdf';

注意：Android 10+（API 29）开始的Scoped Storage机制限制了直接操作公共目录，高版本系统可能需要额外处理，后面会说到。

二、主动触发媒体扫描

保存文件后，必须手动通知系统扫描这个文件，把它加入媒体库索引。这里有两种常用方式：

1. 用第三方插件快速实现

推荐使用media_scanner插件，它已经封装好了原生的媒体扫描逻辑：
首先在pubspec.yaml里添加依赖：

dependencies:
  media_scanner: ^1.0.0

保存文件完成后，直接调用扫描方法：

import 'package:media_scanner/media_scanner.dart';

// 你的文件保存代码...

// 触发系统扫描该文件
await MediaScanner.loadMedia(filePath);

执行完这一步，系统就会把你的文件加入媒体库，邮件客户端这类应用就能在附件选择界面看到它了。

2. 自定义平台通道（不依赖插件）

如果不想用第三方插件，可以自己写原生代码调用Android的MediaScannerConnection：

Flutter侧定义方法通道：

import 'package:flutter/services.dart';

const _mediaScannerChannel = MethodChannel('com.your.app/media_scanner');

Future<void> triggerFileScan(String filePath) async {
  try {
    await _mediaScannerChannel.invokeMethod('scanFile', {'path': filePath});
  } on PlatformException catch (e) {
    print("文件扫描失败: ${e.message}");
  }
}

Android原生MainActivity里实现对应的方法：

import android.media.MediaScannerConnection;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;
import io.flutter.plugin.common.MethodChannel;

public class MainActivity extends FlutterActivity {
    private static final String CHANNEL = "com.your.app/media_scanner";

    @Override
    public void configureFlutterEngine(FlutterEngine flutterEngine) {
        super.configureFlutterEngine(flutterEngine);
        new MethodChannel(flutterEngine.getDartExecutor().getBinaryMessenger(), CHANNEL)
                .setMethodCallHandler(
                        (call, result) -> {
                            if (call.method.equals("scanFile")) {
                                String path = call.argument("path");
                                MediaScannerConnection.scanFile(
                                        this,
                                        new String[]{path},
                                        null,
                                        (scannedPath, uri) -> result.success("扫描完成")
                                );
                            } else {
                                result.notImplemented();
                            }
                        }
                );
    }
}

保存文件后调用triggerFileScan(filePath)即可完成扫描。

三、Android 10+的特殊处理

如果你的应用目标SDK是29及以上，Scoped Storage限制了直接操作公共目录，这时候可以通过MediaStore API来保存文件——用这种方式保存的文件会自动被系统索引，不需要手动触发扫描。

你可以通过自定义平台通道调用原生的MediaStore逻辑，示例原生代码：

import android.content.ContentValues;
import android.net.Uri;
import android.os.Environment;
import android.provider.MediaStore;
import java.io.OutputStream;

// 保存文件到公共文档目录
public Uri saveFileToMediaStore(String fileName, byte[] fileContent) {
    ContentValues values = new ContentValues();
    values.put(MediaStore.Files.FileColumns.DISPLAY_NAME, fileName);
    values.put(MediaStore.Files.FileColumns.MIME_TYPE, "application/pdf"); // 根据文件类型修改
    values.put(MediaStore.Files.FileColumns.RELATIVE_PATH, Environment.DIRECTORY_DOCUMENTS);

    Uri uri = getContentResolver().insert(MediaStore.Files.getContentUri("external"), values);
    try (OutputStream outputStream = getContentResolver().openOutputStream(uri)) {
        outputStream.write(fileContent);
        return uri;
    } catch (Exception e) {
        e.printStackTrace();
        return null;
    }
}