在ASP.NET Web Forms或MVC项目中，文件上传是后台管理系统的常见需求。它的本质是把客户端浏览器选中的文件通过HTTP multipart请求发送到服务器，由服务端代码接收并保存到磁盘或云存储。理解这套机制后，我们就可以写出稳定且安全的上传接口。
一、前端表单的写法
无论使用Web Forms还是MVC，前端都必须把表单的enctype设置为multipart/form-data，否则浏览器只会发送文件名而不会发送文件内容。下面是一个最简单的HTML表单示例，它允许用户选择一个文件并提交到服务器端的Upload接口。
<form action="/Home/Upload" method="post" enctype="multipart/form-data">
<input type="file" name="file" />
<input type="submit" value="上传" />
</form>
在ASP.NET MVC里，我们通常会用Razor辅助方法生成表单，这样能和后端路由更好地结合。注意Html.BeginForm的第四个参数就是设置编码类型，漏掉这一步是导致上传接收不到文件的典型错误。
@using (Html.BeginForm("Upload", "Home", FormMethod.Post, new { enctype = "multipart/form-data" }))
{
<input type="file" name="file" />
<button type="submit">上传</button>
}
二、后端接收文件的控制器代码
在MVC的Controller中，我们可以通过Request.Files获取所有上传的文件，也可以直接在Action参数中声明HttpPostedFileBase类型来自动绑定。后者代码更简洁，也方便做单元测试。下面展示使用参数绑定的写法。
using System.IO;
using System.Web;
using System.Web.Mvc;
public class HomeController : Controller
{
[HttpPost]
public ActionResult Upload(HttpPostedFileBase file)
{
if (file == null || file.ContentLength == 0)
{
return Content("未选择文件或文件为空");
}
// 获取文件名并做简单清洗，防止路径注入
string fileName = Path.GetFileName(file.FileName);
string savePath = Path.Combine(Server.MapPath("~/Uploads"), fileName);
// 确保目录存在
if (!Directory.Exists(Server.MapPath("~/Uploads")))
{
Directory.CreateDirectory(Server.MapPath("~/Uploads"));
}
file.SaveAs(savePath);
return Content("上传成功，保存路径：" + savePath);
}
}
如果你的页面需要一次上传多个文件，可以把参数改成集合形式。前端使用相同的name属性，后端用IEnumerable<HttpPostedFileBase>接收，再循环调用SaveAs即可。这种写法在图文混排或附件批量提交时非常实用。
[HttpPost]
public ActionResult UploadMultiple(IEnumerable<HttpPostedFileBase> files)
{
foreach (var item in files)
{
if (item != null && item.ContentLength > 0)
{
string name = Path.GetFileName(item.FileName);
string path = Path.Combine(Server.MapPath("~/Uploads"), name);
item.SaveAs(path);
}
}
return Content("批量上传完成");
}
三、文件类型与大小的安全校验
直接把用户传来的文件存到磁盘会带来安全隐患，比如有人把.aspx或.exe伪装成图片上传。我们需要在保存前校验扩展名和白名单，同时限制文件尺寸，避免大文件把服务器磁盘写满。下面的代码演示了一个基础的防护逻辑。
private bool IsValidFile(HttpPostedFileBase file, out string error)
{
error = string.Empty;
string ext = Path.GetExtension(file.FileName).ToLower();
string[] allowExt = { ".jpg", ".png", ".gif", ".pdf", ".docx" };
if (!allowExt.Contains(ext))
{
error = "不支持的文件类型";
return false;
}
if (file.ContentLength > 10 * 1024 * 1024)
{
error = "文件不能超过10MB";
return false;
}
return true;
}
除了代码层判断，还建议在Web.config中配置请求长度上限，这样超大文件在到达控制器前就被框架拒绝，能减少不必要的资源消耗。示例如下，把maxRequestLength设为10240代表10MB，maxAllowedContentLength则是IIS层面的限制。
<configuration>
<system.web>
<httpRuntime maxRequestLength="10240" executionTimeout="360" />
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="10485760" />
</requestFiltering>
<security>
</system.webServer>
</configuration>
四、Web Forms中的上传方式
如果你维护的是老项目，用的是ASP.NET Web Forms，那么可以使用FileUpload服务器控件。它在页面上呈现为标签，但在后端通过HasFile和SaveAs方法操作，比原生Request更直观。
<%@ Page Language="C#" %>
<script runat="server">
protected void btnUpload_Click(object sender, EventArgs e)
{
if (FileUpload1.HasFile)
{
string path = Server.MapPath("~/Uploads/") + FileUpload1.FileName;
FileUpload1.SaveAs(path);
Label1.Text = "已保存至 " + path;
}
else
{
Label1.Text = "请先选择文件";
}
}
</script>
<html>
<body>
<form id="form1" runat="server">
<asp:FileUpload ID="FileUpload1" runat="server" />
<asp:Button ID="btnUpload" runat="server" Text="上传" OnClick="btnUpload_Click" />
<asp:Label ID="Label1" runat="server"></asp:Label>
</form>
</body>
</html>
Web Forms的FileUpload控件本质上还是封装了HttpPostedFile，所以校验逻辑和MVC是通用的。区别在于事件模型：Web Forms依赖服务器端回发，而MVC更偏向原生HTTP语义。新项目一般推荐MVC或 Razor Pages，维护成本更低。
五、常见错误与排查思路
很多开发者遇到过Request.Files.Count为0的情况，绝大多数原因都是表单没有写enctype。另一个常见问题是Server.MapPath指向的目录没有写权限，此时SaveAs会抛出拒绝访问异常，需要给IIS用户配置文件夹的修改权。
建议把上传目录放在站点根目录外的独立磁盘，并在代码中做软链接或绝对路径映射，这样即便上传了脚本文件也难以被直接执行。
还有一点容易被忽略：中文文件名在部分浏览器里会出现乱码。可以在保存前用HttpUtility.UrlDecode处理，或者统一重命名为Guid加扩展名，从根源上避免编码问题。经过以上步骤，一个基础且安全的ASP.NET文件上传功能就完成了。
ASP.NET文件上传HttpPostedFile修改时间：2026-08-05 12:00:40