Flutter Retrofit+Dio上传FormData/批量图片失败问题排查

• 检查Retrofit接口的注解与参数

  • 确认formdata_receiving方法上方是否正确添加了@MultiPart()注解，没加的话不会生成multipart类型请求
  • 批量文件参数必须用@PartList()注解，不能用单个@Part()，且参数名要和后端接收的字段严格一致，比如后端接收字段是files，参数名就不能写成fileList
  • 正确写法示例：

    @POST(ApiUrl.formdataReceiving)
    @MultiPart()
    Future<Response> formdataReceiving(
      @PartList() List<MultipartFile> files,
      @Part() String? desc,
    );
    

• 借助LoggingInterceptor分析请求日志

  • 查看请求头是否包含Content-Type: multipart/form-data; boundary=xxx，没有的话说明注解配置有误
  • 检查FormData中是否加载了所有目标文件，有没有空文件、路径错误的情况
  • 确认请求体的multipart分段是否完整，每个文件的文件名、大小是否正常

• 排查Dio配置问题

  • 检查是否有自定义拦截器篡改了FormData结构，比如强行将请求转为JSON格式
  • 确认Dio的transformer是否被自定义修改，默认transformer处理multipart请求是正常的，自定义可能导致解析异常
  • 上传大文件需调大超时时间，默认超时可能不够，比如设置connectTimeout: 30000, receiveTimeout: 60000

• 检查MultipartFile的构造逻辑

  • 批量创建文件对象时，要确保文件路径有效、已获取读取权限，比如Android需申请READ_EXTERNAL_STORAGE，iOS需配置相册权限
  • 正确创建文件示例：

    List<MultipartFile> uploadFiles = [];
    for (String path in selectedFilePaths) {
      final file = await MultipartFile.fromFile(
        path,
        filename: path.split('/').last,
      );
      uploadFiles.add(file);
    }
    

  • 禁止传入空的MultipartFile，会导致整个FormData解析失败

• 确认后端接口适配性

  • 核实后端是否支持批量文件接收的参数格式，比如是否接受数组类型的文件字段
  • 询问后端是否设置了文件大小、数量限制，超过限制会直接导致上传失败

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