Services.Configure<FormOptions>

Services.Configure<FormOptions>() 是 ASP.NET Core 里专门用来调整“表单提交”行为参数的入口，一句话：

把默认的表单解析规则（大小限制、缓冲区、 multipart 边界等）改成适合你业务的值，防止上传大文件或大量字段时被框架误拦。

---

1. FormOptions 关键属性速查

---

表格

复制

属性	默认值	用途
MultipartBodyLengthLimit	134,217,600 字节 (128 MB)	单个 multipart 分段最大长度
MultipartBoundaryLengthLimit	128 字符	multipart 边界字符串最大长度
ValueLengthLimit	4,194,304 字节 (4 MB)	单个表单字段值最大长度
KeyLengthLimit	2,048 字符	表单字段名最大长度
MemoryBufferThreshold	65,536 字节 (64 KB)	超过此大小就写磁盘临时文件，防内存爆
BufferBody	false	是否把整个表单先缓冲到磁盘（true 可重读，但耗 IO）
MultipartHeadersCountLimit	16	每段 multipart 的头数量上限
MultipartHeadersLengthLimit	16,384 字节	每段头总长度上限

---

2. 常见场景代码

---

① 上传 500 MB 大视频

csharp

复制

builder.Services.Configure<FormOptions>(o =>
{
    o.MultipartBodyLengthLimit = 524_288_000;   // 500 MB
    o.MemoryBufferThreshold    = 1_048_576;     // 1 MB 后再写盘
});

 

② 字段名/值超长（如 Base64 图片埋字段）

csharp

复制

builder.Services.Configure<FormOptions>(o =>
{
    o.ValueLengthLimit = 10_000_000;  // 10 MB
    o.KeyLengthLimit   = 10_000;      // 10 k 字符
});

 

③ 需要重复读取 Form（自定义中间件先读一次）

csharp

复制

builder.Services.Configure<FormOptions>(o =>
{
    o.BufferBody = true;   // 先整包落盘，后续可 Seek 重读
});

 

---

3. 注意顺序 & 作用域

---

• 必须在 builder.Services 阶段注册，早于 Build()。
• 只对 表单提交 (Content-Type: application/x-www-form-urlencoded 或 multipart/form-data) 生效；
  JSON/Protobuf 上传不受此限制。
• 若使用 IIS/NGINX，反向代理也有大小限制 (maxAllowedContentLength / client_max_body_size)，需要同步改。

---

一句话总结
Services.Configure<FormOptions>() 就是：
“改表单解析安全阈值，让大文件、长字段、深 multipart 都能顺利进来，不被框架误杀 400/413。”