Flutter中如何通过Form-Data单Key发送多文件至REST API

下面提供两种常用方案，分别基于http包和dio包实现，核心都是将多个文件绑定到同一个Form-Data Key（如images[]）。

方案一：使用官方http包 #

先确保已将http依赖添加到pubspec.yaml，再通过MultipartRequest循环把文件添加到同一Key下：

import 'package:http/http.dart' as http;
import 'dart:io';

Future<void> uploadImages(List<File> imageFiles) async {
  // 构建POST请求实例
  final request = http.MultipartRequest(
    'POST',
    Uri.parse('替换为你的API接口地址'),
  );

  // 循环添加所有图片到"images[]"这个Key
  for (final file in imageFiles) {
    request.files.add(
      await http.MultipartFile.fromPath(
        'images[]',
        file.path,
        filename: file.path.split('/').last, // 保留文件名后缀，方便后端识别类型
      ),
    );
  }

  // 可选：添加其他表单字段
  request.fields['batch_id'] = '20240520';

  // 发送请求并处理响应
  final response = await request.send();
  if (response.statusCode == 200) {
    print('上传成功');
    final responseBody = await response.stream.bytesToString();
    print('返回内容：$responseBody');
  } else {
    print('上传失败，状态码：${response.statusCode}');
  }
}

方案二：使用dio包（更简洁高效） #

dio是Flutter生态中流行的网络请求库，支持更便捷的FormData构建和进度监听：

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

Future<void> uploadImagesWithDio(List<File> imageFiles) async {
  final dio = Dio();
  final multipartFiles = <MultipartFile>[];

  // 把本地文件转换为MultipartFile
  for (final file in imageFiles) {
    multipartFiles.add(
      await MultipartFile.fromFile(
        file.path,
        filename: file.path.split('/').last,
      ),
    );
  }

  // 构建FormData，同一个Key对应文件列表
  final formData = FormData.fromMap({
    'images[]': multipartFiles,
    'description': '批量上传的图片集', // 额外表单参数
  });

  try {
    final response = await dio.post(
      '替换为你的API接口地址',
      data: formData,
      // 可选：监听上传进度
      onSendProgress: (sent, total) {
        print('上传进度：${(sent / total * 100).toStringAsFixed(2)}%');
      },
    );
    if (response.statusCode == 200) {
      print('上传成功');
      print('返回数据：${response.data}');
    }
  } catch (e) {
    print('上传出错：$e');
  }
}

关键注意点 #

• 确认后端接口支持接收同一Key下的多文件，比如PHP中可通过$_FILES['images[]']获取文件数组，Java/Spring可通过@RequestParam("images[]") List<MultipartFile>接收
• 必须保留文件名后缀（如.jpg、.png），避免后端无法识别文件类型
• 大文件上传建议添加进度监听，提升用户体验

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