Dio升级后MultipartFile模式下图片上传丢失如何适配旧代码

核心问题根因 #

• Dio 3.0及以上版本移除了旧版的UploadFileInfo类，全面改用MultipartFile能力实现文件序列化
• 升级后图片无法上传的共性原因：未正确将文件路径转换为合规的MultipartFile实例、同步调用未等待异步初始化完成、结构嵌套错误导致文件字段被FormData解析时忽略，最终表现为普通业务字段传递正常，但图片资源没有进入请求体

具体代码改造方案 #

替换原有基于UploadFileInfo的实现，核心调整点为通过MultipartFile.fromFile异步构造每个图片的文件流实例，再传入FormData：

Future add(name, desc, address, images) async {
  Map ad_data;
  // 批量等待所有图片转换为MultipartFile实例
  final List<MultipartFile> imageMultipartList = await Future.wait(
    images.map((imageItem) => MultipartFile.fromFile(
      imageItem.path,
      // 必须显式指定文件名，否则服务端无法正确解析文件流
      filename: basename(imageItem.path),
    ))
  );

  await dio.post(
    "${host}/add",
    data: FormData.fromMap({
      "name": "$name",
      "desc": "$desc",
      "address": "$address",
      // 多图数组字段直接传入MultipartFile列表即可
      "image[]": imageMultipartList,
    }),
  ).then((response) {
    ad_data = response.data;
  });
  return ad_data;
}

高频踩坑排查点 #

• 不要直接将原始File对象传入FormData，File对象会被序列化为普通字符串值，不会触发文件上传逻辑
• MultipartFile.fromFile属于异步IO操作，必须通过await或者Future.wait完成全量实例初始化后再构造FormData，未完成初始化的空实例会在序列化时被丢弃
• 创建MultipartFile时必须传入filename参数，部分Nginx、后端框架会在检测不到文件名时直接截断对应字段的二进制流
• 根据后端接口要求调整字段名：如果后端要求的多图字段不带数组后缀[]，要对应修改为匹配的字段名，否则即使文件正确传递也会因为字段不匹配被后端忽略
• 旧版的FormData.from()构造方法在新版Dio中已标记为废弃，替换为语义更清晰的FormData.fromMap()即可完全兼容原有传值逻辑

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