Dart Frog框架如何处理文件上传

Dart Frog 默认不支持文件上传，因其设计遵循“轻量+显式”原则，需开发者手动解析 multipart/form-data 请求体；必须提取 boundary、用 MimeMultipartTransformer 流式处理、校验文件大小并安全写入磁盘。

Dart Frog 本身不内置文件上传解析能力，必须手动处理 Multipart/form-data 请求体——这是绝大多数开发者踩坑的起点。

为什么 Dart Frog 默认不支持文件上传？

Dart Frog 的设计哲学是“轻量+显式”，它把请求体解析（尤其是 multipart）交由开发者决定，避免隐式依赖和边界模糊。这意味着：context.request.body() 返回的是原始字节流，不是解析好的字段或文件对象。

• 直接调用 await context.request.body() 会得到一整块二进制数据，无法直接提取文件名、内容或字段
• 你不能像 express 或 Shelf 那样用 request.files 直接访问文件 —— Dart Frog 没有这个属性
• 必须自己解析 Content-Type 中的 boundary，再按规范切分 multipart 区段

如何在 Dart Frog 路由中安全解析上传文件？

推荐使用 package:mime + 手动流式解析，避免内存爆炸（尤其对大文件）。关键步骤如下：

• 先检查 context.request.headers['content-type'] 是否以 multipart/form-data 开头，并提取 boundary
• 用 MimeMultipartTransformer 将原始请求体流转换为 MimeMultipart 流
• 逐个 await for (var part in ...) 处理每个部分，通过 content-disposition 判断是否为文件字段
• 对文件部分，用 part.contentLength 做大小校验，再用 part.readBytes() 或流式写入磁盘（推荐 File.openWrite()）

import 'dart:io'; import 'package:dart_frog/dart_frog.dart'; import 'package:mime/mime.dart';  Future onRequest(RequestContext context) async {   final headers = context.request.headers;   final contentType = headers['content-type'];   if (contentType == null || !contentType.startsWith('multipart/form-data')) {     return Response(statusCode: 400, body: 'Expected multipart/form-data');   }    final boundary = HeaderValue.parse(contentType).parameters['boundary'];   if (boundary == null) {     return Response(statusCode: 400, body: 'Missing boundary');   }    final bodyStream = context.request.read();   final transformer = MimeMultipartTransformer(boundary);      try {     await for (final part in bodyStream.transform(transformer)) {       final disposition = part.headers['content-disposition'];       if (disposition != null && disposition.contains('filename=')) {         final filename = disposition.split('filename="')[1]?.split('"')[0] ?? 'unknown';         final bytes = await part.readBytes();                  // 示例：保存到临时目录         final file = File('/tmp/uploaded_$filename');         await file.writeAsBytes(bytes);         return Response(body: 'Saved as ${file.path}');       }     }     return Response(statusCode: 400, body: 'No file part found');   } catch (e) {     return Response(statusCode: 400, body: 'Parse error: $e');   } }

客户端传参与常见错误对照

前端必须严格匹配后端预期，否则 boundary 解析失败，整个请求变成乱码字节流：

• HTML 表单要加 enctype="multipart/form-data"，且 的 name 必须和服务端查找的字段名一致（如 filename= 后的 key）
• 用 fetch 或 Dio 上传时，务必用 FormData 构造体，不要手动拼 body 字符串
• 错误现象：Invalid boundary in multipart 或解析后 part.headers 为空 → 检查前端是否漏传 Content-Type，或 Dart Frog 是否被中间件（如 CORS）篡改了 header

真正麻烦的不是解析逻辑，而是边界处理：文件名编码（中文乱码）、空文件、超大文件阻塞事件循环、临时文件清理——这些都得自己补全，Dart Frog 不代劳。