ASP.NET Core 静态文件服务入门：一行 `UseStaticFiles()` 让 wwwroot 立即可用
ASP.NET Core 静态文件服务入门：一行 UseStaticFiles() 让 wwwroot 立即可用
基于 practical-aspnetcore 仓库中 serve-static-files-1 示例项目编写。本文以该示例的完整源码、配置与静态资源为事实依据，深入讲解 ASP.NET Core 中最常用的静态文件中间件用法，并串联仓库内其余 7 个同主题示例，给出从入门到进阶的完整路线。
一句话导读
ASP.NET Core 应用若要为浏览器提供 HTML、CSS、图片等静态资源，只需调用一次 app.UseStaticFiles()。本文以一个仅 3 行代码的最小示例为切入点，讲清 wwwroot 默认目录、URL 访问规则与底层中间件机制，并顺带给出 StaticFileOptions 高级配置和多目录、目录浏览、访问日志等延伸方案。
最小实现：3 行代码开启静态文件服务
本示例的全部服务端代码位于 projects/file-provider/serve-static-files-1/Program.cs：
var app = WebApplication.Create();
app.UseStaticFiles();
app.Run();
三段代码各司其职：
| 代码 | 作用 |
|---|---|
WebApplication.Create() |
创建最小化 WebApplication 实例，构建主机、加载配置与日志基础设施 |
app.UseStaticFiles() |
注册静态文件中间件，将 wwwroot 目录映射为可公开访问的 Web 根目录 |
app.Run() |
启动应用并监听端口（默认 http://localhost:5000） |
这是全仓库最简单的一个示例项目，原文档 README.md 也明确说明：整个示例的核心就是这一行 app.UseStaticFiles();。其项目文件 serve-static-files.csproj 采用 Microsoft.NET.Sdk.Web SDK，目标框架为 net10.0，未引用任何额外 NuGet 包——静态文件中间件内置于 ASP.NET Core 共享框架中，开箱即用。
为什么不需要配置 ContentRoot？
WebApplication.Create() 默认将当前工作目录设为 ContentRoot，并将 ContentRoot 下的 wwwroot 子目录设为 WebRoot。UseStaticFiles() 无参调用时，内部自动以 WebRootFileProvider（一个指向 wwwroot 的 PhysicalFileProvider）作为默认 FileProvider。因此只要目录名叫 wwwroot，静态文件就会被自动识别，无需任何配置。
wwwroot：默认的静态资源目录
示例项目在 wwwroot 下放置了两个静态文件：
- wwwroot/index.html：页面主体，内部引用
hello.css - wwwroot/hello.css：定义
body字号与h1标题颜色
index.html 内容如下：
<html>
<link rel="stylesheet" type="text/css" href="hello.css">
<body>
<h1>Static File</h1>
This is a static file located at wwwroot folder
</body>
</html>
hello.css 内容如下：
body {
font-size: large;
}
h1 {
color: blueviolet;
}
注意 index.html 中通过相对路径 href="hello.css" 引用样式表——静态文件之间同样按 Web 根目录的 URL 相对关系解析，这与传统 Web 服务器行为一致。
目录结构速览
serve-static-files-1/
├── Program.cs # 3 行代码的服务入口
├── serve-static-files.csproj # Microsoft.NET.Sdk.Web / net10.0
└── wwwroot/ # 默认 Web 根目录
├── index.html
└── hello.css
URL 访问规则：必须带文件名访问
这是原文档强调的关键实操点，也是初学者最容易踩的坑：
必须访问
http://localhost:5000/index.html，而不是http://localhost:5000/。
原因在于：UseStaticFiles() 只负责"按请求的文件名查找并返回对应文件"，它不会把根路径 / 自动映射为 index.html。这与经典 IIS/Nginx 的"默认文档"行为不同：
| 请求 URL | 结果 |
|---|---|
http://localhost:5000/ |
返回 404（没有任何端点处理根路径） |
http://localhost:5000/index.html |
返回 wwwroot 下的 index.html |
http://localhost:5000/hello.css |
返回 wwwroot 下的 hello.css |
如果需要"访问根路径直接得到首页"，需要额外注册默认文档中间件 app.UseDefaultFiles()，或在最小 API 中显式 MapGet("/", ...) 返回首页内容。仓库目录中的 serve-static-files-3 示例即演示了 UseDefaultFiles 的组合用法（见下文进阶部分）。
运行验证方式
在 serve-static-files-1 目录下执行：
dotnet run
然后浏览器打开 http://localhost:5000/index.html，即可看到蓝紫色标题的 "Static File" 页面；http://localhost:5000/ 则返回 404。也可用 curl 验证：
curl -I http://localhost:5000/index.html # 返回 200 OK
curl -I http://localhost:5000/ # 返回 404
UseStaticFiles 底层做了什么
从代码结构可以推断，UseStaticFiles() 注册的是一个 StaticFileMiddleware，其核心工作流程为：
- 路径映射：将请求路径（如
/index.html）拼接在 WebRoot 目录之上； - 文件查找：通过
IFileProvider（默认指向wwwroot的PhysicalFileProvider）查找文件； - 存在性校验：文件不存在时直接放行（
next()），交给后续中间件；存在则以 200 返回； - Content-Type 推断：根据扩展名通过
FileExtensionContentTypeProvider推断 MIME 类型（如.html→text/html、.css→text/css）； - 支持 HTTP 缓存语义：处理
If-Modified-Since/ETag，命中缓存时返回 304； - Range 支持：对断点续传请求（
Range头）返回 206 部分内容。
这一"查找不到就放行"的设计意味着静态文件中间件可以与其他路由、中间件共存：静态请求被它处理，动态请求继续走后续管线。
可配置的能力边界
UseStaticFiles() 有一个重载 UseStaticFiles(StaticFileOptions)。虽然本示例未使用，但仓库内的 serve-static-files-7 与 serve-static-files-8 展示了其关键选项的用法：
app.UseStaticFiles(new StaticFileOptions
{
// 1. 更换文件提供器：把静态文件指向 wwwroot 之外的目录
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot2")),
// 2. 更换请求前缀：该目录下的文件通过 /2/xxx 访问
RequestPath = new PathString("/2"),
// 3. 响应钩子：在每个静态文件被返回前执行（如记录访问日志）
OnPrepareResponse = ctx =>
{
app.Logger.LogInformation($"Serving static file: {ctx.File.Name}");
}
});
FileProvider：任意实现了IFileProvider的提供器，不仅限于PhysicalFileProvider——这也解释了仓库中 file-provider-custom 为什么可以自己写一个"总是返回同一段文字"的假文件提供器来演示IFileProvider接口契约；RequestPath：虚拟路径前缀，让同一应用从多个物理目录供文件时互不冲突；OnPrepareResponse：StaticFileResponseContext回调，可读取ctx.File（IFileInfo）、ctx.Context（HttpContext），用于日志、自定义响应头等；ServeUnknownFileTypes/DefaultContentType：默认情况下中间件只处理它能识别 Content-Type 的已知扩展名，对未知类型文件默认拒绝返回，可通过这两个选项放开（本仓库示例未启用，属框架内置行为）。
同主题进阶示例：一个功能一个工程
projects/file-provider/README.md 把静态文件能力拆成了 8 个递进示例，本示例是其中第 1 个。沿着该列表可以系统学习：
| 示例 | 相对路径 | 核心能力 |
|---|---|---|
| 1 静态文件基础 | serve-static-files-1 | 本文主题，一行代码启用静态文件 |
| 2 目录浏览 | serve-static-files-2 | UseDirectoryBrowser() 列出并浏览 wwwroot 内容 |
| 3 文件服务器 | serve-static-files-3 | UseFileServer(enableDirectoryBrowsing: true) 组合 UseStaticFiles + UseDefaultFiles + UseDirectoryBrowser |
| 4/5 自定义目录格式化器 | serve-static-files-4 / serve-static-files-5 | 实现 IDirectoryFormatter 定制目录浏览页（前者仅扁平目录，后者支持子目录与文件） |
| 6 指定路径的目录浏览 | serve-static-files-6 | DirectoryBrowserOptions.RequestPath = "/browse" 挂到指定虚拟路径 |
| 7 多目录静态文件 | serve-static-files-7 | 同时服务 wwwroot 与 wwwroot2，后者通过 /2/ 前缀访问 |
| 8 静态文件访问日志 | serve-static-files-8 | 用 OnPrepareResponse 记录每次被服务的文件名 |
例如 serve-static-files-3/Program.cs 展示了"一站式"方案：
var app = WebApplication.Create();
app.UseFileServer(enableDirectoryBrowsing: true);
app.Run();
UseFileServer 内部按顺序组合了默认文档、静态文件与目录浏览三个中间件，是多数站点首页直达 + 静态资源 + 调试用目录浏览需求的标准答案。而 serve-static-files-6/Program.cs 则演示了把目录浏览单独挂到 /browse 路径的做法，避免暴露整个目录树。
小结
serve-static-files-1 用最少的代码量说明了一个最常用的框架能力：静态文件中间件开箱即用、默认根目录为 wwwroot、必须按文件名访问。在此基础上：
- 想让根路径直达首页 → 改用/叠加
UseDefaultFiles()（见 serve-static-files-3）； - 需要多目录、外部目录 → 配置
StaticFileOptions.FileProvider + RequestPath（见 serve-static-files-7）； - 需要记录静态资源访问 → 配置
OnPrepareResponse（见 serve-static-files-8）； - 想理解整个文件提供抽象 → 继续阅读 file-provider-physical 与 file-provider-custom。
从这一行 app.UseStaticFiles(); 出发，即可完整掌握 ASP.NET Core 的静态文件服务全貌。