前端上传图片后端接收为空或格式异常

Question

常见问题：前端通过 `<input type="file" />` 选择图片并用 `FormData` 提交至后端时，后端（如 Spring Boot 的 `@RequestParam MultipartFile` 或 Express 的 `req.files`）接收到的文件为空或报“格式不支持”错误。根本原因常包括：① 前端未正确设置 `Content-Type: multipart/form-data`（如手动设置了该 header 反而导致浏览器无法自动构造边界）；② `FormData.append()` 时字段名与后端接收参数名不一致（如前端传 `image`，后端却写 `@RequestParam("file")`）；③ 图片过大触发 Nginx/Node.js/Kestrel 默认请求体限制；④ 前端未校验文件类型，上传了非图片（如 `.txt`），而后端强校验 `Content-Type`（如只接受 `image/*`）却忽略实际 MIME 探测，导致拦截。排查需从前端 Network 面板确认请求 payload 结构，再比对后端日志与配置。

Answer 1

```html

一、现象层：前端上传图片后端接收为空或报“格式不支持”

典型表现：用户选择 <input type="file" /> 后点击提交，Network 面板中请求状态为 200 但响应体含空文件/400 错误；Spring Boot 报 Required request part 'file' is not present；Express 中 req.files 为 undefined 或空对象。此为最表层可观测症状，需立即触发链路诊断。

二、协议层：multipart/form-data 的边界构造与 header 陷阱

• ✅ 正确做法：使用 fetch(url, { method: 'POST', body: formData }) —— 浏览器自动设置 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary...，且不手动覆盖 header
• ❌ 致命错误：显式设置 headers: { 'Content-Type': 'multipart/form-data' } → 导致浏览器放弃自动注入 boundary，服务端无法解析分段数据
• 🔍 验证方式：在 Chrome DevTools → Network → 点击请求 → Headers → 查看 Request Headers 中是否存在带 boundary= 的完整 Content-Type 字符串

三、契约层：前后端字段名一致性校验（命名契约）

场景	前端 FormData.append()	后端接收声明	是否匹配
A	formData.append('avatar', file)	@RequestParam("avatar") MultipartFile file	✅
B	formData.append('image', file)	@RequestParam("file") MultipartFile f	❌（参数名不一致）

注：Spring Boot 中 @RequestParam 值必须与 FormData.append(key, ...) 的 key 完全一致；Express + multer 中需配置 upload.single('image') 且路由 handler 中读取 req.file（非 req.files）。

四、基础设施层：反向代理与运行时请求体限制

常见阈值及突破路径：

• Nginx：默认 client_max_body_size 1m → 需在 http/server/location 块中设为 10m 或更高
• Spring Boot：spring.servlet.multipart.max-file-size=10MB & max-request-size=10MB（2.x+）
• Express + Multer：limits: { fileSize: 10 * 1024 * 1024 }
• Kestrel (ASP.NET Core)：ConfigureKestrel(... c => c.Limits.MaxRequestBodySize = 10_000_000)

五、语义层：MIME 类型校验的深度防御策略

仅依赖 file.type（前端 JS）或 req.file.mimetype（后端）存在严重缺陷——攻击者可篡改 Content-Type header。正确方案应结合：

1. 前端扩展名校验（file.name.endsWith('.jpg') || file.name.endsWith('.png')）
2. 后端二进制魔数探测（如 Java 使用 Tika / Node.js 使用 file-type 库读取前 4–8 字节）
3. 白名单策略：允许 image/jpeg, image/png, image/webp，拒绝 text/plain 即使扩展名为 .jpg

六、诊断流：端到端排查决策图

graph TD
  A[前端 Network 面板] --> B{是否有 boundary?}
  B -->|否| C[检查是否手动设置了 Content-Type]
  B -->|是| D{FormData key 是否匹配后端参数名?}
  D -->|否| E[修正 append key 或 @RequestParam 值]
  D -->|是| F[查看 Request Payload 是否含文件二进制块]
  F -->|否| G[检查 input 元素是否被动态移除/重置]
  F -->|是| H[查后端日志：文件大小超限？MIME 拦截？]
  H --> I[验证 Nginx/Spring/Express 限制配置]
  H --> J[启用 MIME 实际探测日志]

七、加固实践：生产级上传组件最小可行代码示例

// 前端：健壮上传函数
async function uploadImage(file) {
  if (!file || !['image/jpeg', 'image/png', 'image/webp'].includes(file.type)) {
    throw new Error('仅支持 JPG/PNG/WebP 格式');
  }
  const formData = new FormData();
  formData.append('avatar', file); // 与后端 @RequestParam("avatar") 严格对齐

  const res = await fetch('/api/upload', {
    method: 'POST',
    body: formData // ❗不设 headers！
  });
  return res.json();
}

// Spring Boot 后端：启用探测式校验
@PostMapping("/upload")
public ResponseEntity<String> handleUpload(
    @RequestParam("avatar") MultipartFile file) throws IOException {
  String actualType = MediaTypeDetector.detect(file.getInputStream()); // 自研或 Tika
  if (!actualType.startsWith("image/")) {
    throw new IllegalArgumentException("非法文件类型：" + actualType);
  }
  // ... 保存逻辑
}

```