本文详细讲解如何在 flutter 中正确上传多个文件至 php 后端，解决因字段名不一致、临时文件路径错误及请求头配置不当导致的“仅单文件上传成功”问题，并提供可运行的前后端代码示例与关键注意事项。
本文详细讲解如何在 flutter 中正确上传多个文件至 php 后端，解决因字段名不一致、临时文件路径错误及请求头配置不当导致的“仅单文件上传成功”问题，并提供可运行的前后端代码示例与关键注意事项。
在 Flutter 中使用 http.MultipartRequest 上传多个文件时，常见误区是为每个文件分配独立的字段名（如 "file", "file2", "file3"），但若 PHP 端未严格对应或存在逻辑错误，极易导致仅首文件被处理。更健壮且符合 HTTP 规范的做法是：统一使用相同字段名（如 file），让服务器通过数组方式接收多文件——这不仅简化前端逻辑，也提升后端可维护性。
✅ 正确的 Flutter 实现（推荐方案）
import 'package:http/http.dart' as http;
import 'dart:io';
Future<void> uploadMultipleFiles(List<File> files) async {
final request = http.MultipartRequest('POST', Uri.parse('https://your-server.com/upload.php'));
// 为每个文件添加同名字段 'file'，PHP 将自动识别为 $_FILES['file'] 数组
for (var file in files) {
if (await file.exists()) {
final multipartFile = await http.MultipartFile.fromPath('file', file.path);
request.files.add(multipartFile);
}
}
// ⚠️ 注意：不要手动设置 Content-Type！http 包会自动生成带 boundary 的 multipart/form-data 头
// 手动设置反而会破坏 boundary，导致服务端无法解析
try {
final response = await request.send();
final result = await http.Response.fromStream(response);
print('Upload status: ${result.statusCode}');
print('Response body: ${result.body}');
} catch (e) {
print('Upload failed: $e');
}
}✅ 对应的 PHP 后端（健壮处理多文件）
<?php
header('Content-Type: application/json; charset=utf-8');
$uploadDir = 'upload/';
if (!is_dir($uploadDir)) {
mkdir($uploadDir, 0755, true);
}
$response = ['success' => true, 'uploaded' => []];
// 检查是否收到文件数组
if (!isset($_FILES['file']) || !is_array($_FILES['file']['name'])) {
http_response_code(400);
echo json_encode(['error' => 'No files received or invalid format']);
exit;
}
$files = $_FILES['file'];
$fileCount = count($files['name']);
for ($i = 0; $i < $fileCount; $i++) {
$name = basename($files['name'][$i]);
$tmpPath = $files['tmp_name'][$i];
$size = $files['size'][$i];
$error = $files['error'][$i];
if ($error === UPLOAD_ERR_OK && $size > 0) {
$targetPath = $uploadDir . uniqid() . '_' . $name; // 避免重名
if (move_uploaded_file($tmpPath, $targetPath)) {
$response['uploaded'][] = [
'original_name' => $name,
'saved_as' => basename($targetPath),
'size' => $size
];
} else {
$response['success'] = false;
$response['errors'][] = "Failed to save {$name}";
}
} else {
$response['success'] = false;
$response['errors'][] = "Upload error for {$files['name'][$i]}: code {$error}";
}
}
http_response_code($response['success'] ? 200 : 500);
echo json_encode($response);
?>⚠️ 关键注意事项
-
不要手动设置
Content-Type：http.MultipartRequest内部已生成含唯一boundary的multipart/form-data头；手动覆盖将导致解析失败。 -
PHP 中必须用数组方式访问
$_FILES['file']：字段名统一为'file'，PHP 自动构建多维数组（name[],tmp_name[]等），而非分别定义file1/file2。 -
校验
$_FILES结构：直接print_r($_FILES)可快速验证是否接收到多文件数组。 -
安全加固建议：
- 验证
$_FILES['file']['error']值为UPLOAD_ERR_OK； - 检查文件扩展名与 MIME 类型（勿仅依赖客户端）；
- 使用
uniqid()或 UUID 重命名文件，防止路径遍历或覆盖攻击。
- 验证
通过以上结构化实现，即可稳定支持任意数量的文件并发上传，兼顾可读性、健壮性与安全性。
