IFormFile 为 null 的根本原因是请求未使用 multipart/form-data 编码；必须用 FormData 提交、禁用 [FromBody]、参数名与表单字段严格一致、Swagger 需点“Choose File”上传。
ASP.NET Core 中 IFormFile 为什么总为 null？
常见错误现象是前端明明传了文件，后端 IFormFile 参数始终是 null，连调试都进不了方法体。根本原因不是代码写错了，而是请求没走对路——必须用 multipart/form-data 编码提交，且不能用 JSON 方式发。
- 前端必须用
FormData构造请求，不能直接JSON.stringify文件对象 - 后端接口不能加
[FromBody]，否则模型绑定器会跳过文件字段 - 如果用 Swagger 测试，得点「Choose File」按钮上传，不能填字符串或 Base64
- Controller 方法参数名要和表单字段名严格一致（默认是
file，不是File或upload）
示例：前端正确写法
const fd = new FormData(); fd.append('file', input.files[0]); fetch('/api/upload', { method: 'POST', body: fd });
如何安全保存上传的 IFormFile 到磁盘？
别直接用 file.FileName 拼路径，这是典型攻击入口。浏览器可伪造任意文件名，比如 ../../../etc/passwd 或带 .exe 后缀的脚本。
- 用
Path.GetRandomFileName()生成新文件名，保留扩展名时只取白名单内的（如.pdf、.jpg） - 扩展名必须从
file.ContentType或二进制魔数判断，不能信file.FileName的后缀 - 目标目录要用
Path.Combine拼接，避免路径穿越；写入前确认父目录存在（Directory.CreateDirectory） - 大文件要流式写入，别全读进内存：
using var stream = file.OpenReadStream()
示例：安全保存片段
var ext = Path.GetExtension(file.FileName).ToLowerInvariant(); if (!new[] { ".jpg", ".png", ".pdf" }.Contains(ext)) throw new InvalidOperationException("不支持的文件类型"); var safeName = $"{Guid.NewGuid():N}{ext}"; var path = Path.Combine(uploadRoot, safeName); using var fs = System.IO.File.Create(path); await file.CopyToAsync(fs);
IFormFile 和 Stream 传参的区别在哪？
IFormFile 是 ASP.NET Core 封装好的上传文件抽象，自带元数据（FileName、ContentType、Length），适合常规上传场景；而直接接收 Stream 是底层方式，常用于大文件直传、分片合并或绕过模型绑定限制。
-
IFormFile默认有 128 MB 请求体限制（KestrelServerOptions.Limits.MaxRequestBodySize），改它要配Startup.cs或Program.cs -
Stream参数必须配合[DisableRequestSizeLimit]，且需手动处理边界、编码、多部分解析，容易出错 - 如果前端用
fetch发原始二进制流（body: fileArrayBuffer），后端就只能收Stream，没法自动转IFormFile
性能影响：小文件用 IFormFile 更省心；超 50 MB 的文件建议切片 + Stream 分段写，避免内存暴涨和超时。
为什么上传成功但返回 404 或 500？
这不是上传逻辑的问题，而是路由、中间件或响应处理环节掉了链子。
- 检查是否忘了在
Program.cs中调用app.UseRouting()和app.UseEndpoints()（.NET 6+） - 如果用了
[ApiController]特性，返回非IActionResult类型（比如直接return "ok"）会触发 500，必须包装成Ok("ok") - 文件保存路径权限不足（Linux 下 www-data 没写权限，Windows 下 IIS_IUSRS 无访问权）会导致写入失败，抛出未捕获异常 → 500
- 开发环境看到详细错误页，生产环境默认关了，记得开
app.UseDeveloperExceptionPage()（仅开发）快速定位
最容易被忽略的一点：上传接口如果放在 Controllers 文件夹外，或者类没继承 ControllerBase，即使路由匹配，也会因缺少模型绑定上下文而静默失败。
