Flutter使用http包MultipartFile上传图片API返回空响应怎么解决？

架构老林

2026-9-24

问题描述

我正使用Flutter的http包开发图片上传功能，以下是上传图片到服务端的代码：

Future<String> uploadNewImage(String imagePath) async {
  var postUri = Uri.parse("https://test.vahupu.com/g2.php?mode=fileupload");
  var request = http.MultipartRequest("POST", postUri);
  request.files.add(
    await http.MultipartFile.fromPath(
      "file",
      imagePath,
      filename: imagePath.split("/").last,
    ),
  );
  var response = await request.send();
  if (response.statusCode == 200) {
    var responseString = await response.stream.bytesToString();
    var responseJson = json.decode(responseString);
    if (responseJson.isEmpty) {
      showErrorDialog("Server Error");
      return "";
    } else {
      showErrorDialog("Image Uploaded Succesfully");
      return responseJson["filepath"];
    }
  } else {
    showErrorDialog("Something Went Wrong");
  }
  return "";
}

其中imagePath来自image_picker包获取的图片资源，对应代码如下：

Future _getImgFromGallery() async {
  XFile? image = await picker.pickImage(
    source: ImageSource.gallery,
    imageQuality: 50,
  );
  if (image != null) {
    String imageName = await uploadNewImage(
      image.path,
    );
    if (imageName != "") {
      widget.addOrRemoveImage(imageNameList, image.path);
    }
  }
}

该上传接口在Thunderclient（POSTMAN的替代工具）中测试可以正常运行，测试截图如下：
Thunderclient上传图片测试截图
但上述代码在Flutter应用中运行时上传失败，API返回空响应，请问是什么原因？该如何排查解决？

原因排查与解决方法

常见原因

缺少必要的请求头：部分服务端要求请求必须携带Accept: application/json等头字段，当前代码没有配置自定义请求头，服务端识别为非法请求返回空内容。
文件MIME类型识别错误：MultipartFile.fromPath默认根据文件后缀猜测MIME类型，识别错误时会被服务端的文件校验规则拦截。
没有异常捕获逻辑：代码没有包裹try-catch，网络请求失败、JSON解析出错时会直接中断执行，收到的空响应实际是代码异常导致的返回值。
端侧网络权限缺失：安卓端没有配置网络权限、iOS端ATS配置限制了网络请求，都会导致请求失败返回空。
Web端跨域限制：如果是Flutter Web项目，服务端没有配置CORS规则时，浏览器会拦截响应内容返回空。

排查步骤

加日志打印原始响应信息：在response.stream.bytesToString()之后先打印完整的响应字符串和状态码，确认是服务端真的返回空，还是JSON解析环节出错。
抓包对比请求差异：用Charles、Fiddler等抓包工具，分别抓取Thunderclient和Flutter端的请求包，对比请求头、表单参数的差异，直接定位不一致的字段。

修复方案

补充必要请求头，显式指定文件MIME类型：

import 'package:mime/mime.dart';
import 'package:http_parser/http_parser.dart';

Future<String> uploadNewImage(String imagePath) async {
  try {
    var postUri = Uri.parse("https://test.vahupu.com/g2.php?mode=fileupload");
    var request = http.MultipartRequest("POST", postUri);
    // 补充请求头
    request.headers['Accept'] = 'application/json';
    // 显式指定文件MIME类型
    final mimeType = lookupMimeType(imagePath);
    final contentType = mimeType != null ? MediaType.parse(mimeType) : MediaType('image', 'jpeg');
    request.files.add(
      await http.MultipartFile.fromPath(
        "file",
        imagePath,
        filename: imagePath.split("/").last,
        contentType: contentType,
      ),
    );
    var response = await request.send();
    if (response.statusCode == 200) {
      var responseString = await response.stream.bytesToString();
      // 打印原始响应方便排查
      print("原始响应内容：$responseString");
      var responseJson = json.decode(responseString);
      if (responseJson.isEmpty) {
        showErrorDialog("Server Error");
        return "";
      } else {
        showErrorDialog("Image Uploaded Succesfully");
        return responseJson["filepath"];
      }
    } else {
      showErrorDialog("请求失败，状态码：${response.statusCode}");
    }
  } catch (e) {
    // 捕获异常打印错误信息
    print("上传出错：$e");
    showErrorDialog("上传出错：$e");
  }
  return "";
}

检查端侧配置：
- 安卓端在android/app/src/main/AndroidManifest.xml中添加网络权限：<uses-permission android:name="android.permission.INTERNET" />
- 若为Flutter Web项目，联系服务端开发配置CORS规则，允许你的前端域名访问接口。

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