Flutter Web中如何使用dio.download实现文件下载

核心逻辑说明 #

Flutter Web 运行在浏览器沙箱环境中，不存在移动端、桌面端那种可直接写入的本地文件系统路径，也不允许网页指定用户设备上的文件存储目录，因此其他平台常用的./xx.html、/data/local/tmp/xxx.pdf这类路径写法在 Web 端完全不生效。

dio 内部已经对 Web 环境做了适配：调用dio.download时，Web 端不会尝试往你传入的路径写入文件，而是会自动将接口返回的文件流转换成浏览器可识别的 Blob 对象，触发浏览器原生的文件下载弹窗，这时候你传入的path参数仅作为下载文件的默认文件名使用。

正确传参规则 #

• 不要传任何带目录结构的路径，不要加./、/这类路径前缀
• 第二个参数直接填写你希望用户下载时默认显示的文件名即可，记得带上对应文件后缀
• 用户触发下载后，可以自行在浏览器弹窗里选择文件实际存放的位置，这个行为不受前端代码控制

可用示例代码 #

import 'package:dio/dio.dart';
import 'package:flutter/foundation.dart';

Future<void> downloadPdfFile(String fileUrl) async {
  final Dio dio = Dio();
  try {
    await dio.download(
      fileUrl,
      '项目交付文档.pdf', // Web端直接传默认文件名即可，无需写路径
      onReceiveProgress: (int received, int total) {
        if (total != -1) {
          final progress = (received / total * 100).toStringAsFixed(0);
          debugPrint('下载进度：$progress%');
        }
      },
    );
  } catch (e) {
    debugPrint('PDF下载失败：$e');
    rethrow;
  }
}

常见避坑 #

如果按照非Web端的写法传入带路径的参数（比如示例里的'./xx.html'），会导致下载时默认文件名出现多余的特殊字符，甚至触发部分浏览器的安全拦截，直接传纯文件名就可以正常触发下载。

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