本文详解 Flutter 移动端如何正确上传本地选择的图片（如 JPG、PDF）至 PHP 服务端，重点解决 Uint8List 无法直接作为 JSON 字段发送的类型错误，并提供基于 http.MultipartRequest 的标准文件上传方案。
本文详解 flutter 移动端如何正确上传本地选择的图片（如 jpg、pdf）至 php 服务端，重点解决 `uint8list` 无法直接作为 json 字段发送的类型错误，并提供基于 `http.multipartrequest` 的标准文件上传方案。
在 Flutter 中通过 FilePicker 获取本地文件后，开发者常误将 Uint8List（即二进制字节流）直接塞入 JSON 请求体中发送，例如：
body: { "bill_image": imgbytes } // ❌ 错误：JSON 不支持二进制类型这会导致运行时抛出 type 'Uint8List' is not a subtype of type 'String' in type cast 异常——因为 http.post() 默认以 application/json 方式序列化请求体，而 JSON 规范不支持原始字节数据。
✅ 正确做法是使用 multipart/form-data 编码方式上传文件，它专为表单文件提交设计，可同时传输文本字段与二进制文件。以下是完整、健壮的实现步骤：
1. 构建 Multipart 请求
import 'package:http/http.dart' as http;
import 'dart:io';
final url = Uri.parse('http://10.0.2.2:8000/api/addSurvey');
final request = http.MultipartRequest('POST', url)
..headers['Authorization'] = token
..headers['Content-Type'] = 'multipart/form-data'; // 可选（MultipartRequest 会自动设置）
// 添加图片文件（注意：filename 建议带扩展名，便于 PHP 识别 MIME 类型）
if (myfile != null) {
final bytes = await myfile.readAsBytes();
final file = await http.MultipartFile.fromBytes(
'bill_image', // ← PHP $_FILES['bill_image'] 中的键名
bytes,
filename: 'upload_${DateTime.now().millisecondsSinceEpoch}.jpg',
);
request.files.add(file);
}
// 如需附加其他文本参数（如 survey_id、user_id），使用 request.fields：
request.fields['survey_id'] = '123';
request.fields['notes'] = 'Submitted via mobile';2. 发送并处理响应
try {
final response = await request.send();
final result = await http.Response.fromStream(response);
if (result.statusCode == 200) {
print('✅ 文件上传成功：${result.body}');
// 解析 JSON 响应（如 {"success": true, "file_id": 42}）
} else {
print('❌ 上传失败，HTTP 状态码：${result.statusCode}');
print('响应内容：${result.body}');
}
} on Exception catch (e) {
print('⚠️ 网络异常：$e');
}⚠️ 关键注意事项
- PHP 端必须使用 $_FILES 接收：不能依赖 $_POST['bill_image']；需通过 $_FILES['bill_image']['tmp_name'] 获取临时路径，并用 move_uploaded_file() 保存或读取内容存入数据库（如 BLOB 字段或存储路径）。
- 调试建议：在 PHP 中先 var_dump($_FILES); exit; 确认字段名与结构匹配。
- 权限与跨域：确保 PHP 服务允许 POST 请求及 multipart 数据；本地开发时（如 10.0.2.2 指向宿主机），需确认 Android 模拟器网络可达且 PHP 服务未限制来源。
- 大文件优化：对 PDF/DOC 等较大文件，建议添加加载状态提示、超时设置（request.send().timeout(...)）及分片上传预案。
掌握 multipart 上传模式，是 Flutter 与 PHP（或其他后端）进行文件交互的基础能力。避免将二进制数据硬编码进 JSON，始终让协议各司其职：JSON 传结构化元数据，Multipart 传原始文件。
立即学习“PHP免费学习笔记（深入）”；
