必须显式调用UseStaticFiles()启用静态文件服务，它需置于UseRouting()之后、UseEndpoints()之前；默认仅服务wwwroot目录，自定义路径需配置StaticFileOptions和FileProvider，并手动设置ContentTypeProvider与缓存头。
静态文件中间件必须显式启用
ASP.NET Core 默认不提供任何静态文件服务，哪怕 wwwroot 目录存在且文件就位，直接访问也会返回 404。必须在 Program.cs 中调用 UseStaticFiles() 才能启用。
常见错误是只配置了目录但忘了注册中间件，或者把 UseStaticFiles() 放在 UseRouting() 或 UseEndpoints() 之后——它必须在请求处理管道的早期位置，通常紧接在 UseRouting() 之前或之后（推荐之后）。
-
UseStaticFiles()默认只服务wwwroot下的文件 - 若要服务其他目录，需传入
StaticFileOptions并设置FileProvider - 不支持目录遍历（如
..路径），这是默认安全行为，不可绕过
wwwroot 是约定路径，不是硬编码路径
wwwroot 是项目模板默认的静态文件根目录，但它只是 WebRootPath 的默认值，并非框架强制路径。你可以通过 IWebHostEnvironment.WebRootPath 读取当前配置，也可以在构建主机时用 UseWebRoot("my-static") 修改。
注意：修改 WebRootPath 不会自动让 UseStaticFiles() 生效于新路径——你仍需显式传入对应 IFileProvider：
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(Path.Combine(env.ContentRootPath, "my-static")),
RequestPath = "/static"
});
-
RequestPath指定 URL 前缀（如访问/static/logo.png），不以/结尾 - 多个
UseStaticFiles()调用可并存，但需确保RequestPath不冲突 - 若未设
RequestPath，则映射到根路径（/），此时会覆盖默认wwwroot行为
缓存头和 MIME 类型需手动控制
ASP.NET Core 不自动设置强缓存头（如 Cache-Control: public, max-age=31536000），也不识别所有文件扩展名对应的 MIME 类型。例如 .webp、.avif、.woff2 默认返回 application/octet-stream，可能被浏览器拒绝加载。
解决方式是在 StaticFileOptions 中配置 OnPrepareResponse 和 ContentTypeProvider：
var provider = new FileExtensionContentTypeProvider();
provider.Mappings[".webp"] = "image/webp";
provider.Mappings[".avif"] = "image/avif";
app.UseStaticFiles(new StaticFileOptions
{
ContentTypeProvider = provider,
OnPrepareResponse = ctx =>
{
if (ctx.File.Exists && ctx.Context.Request.Path.StartsWithSegments("/static"))
{
ctx.Context.Response.Headers.Append("Cache-Control", "public, max-age=31536000");
}
}
});
-
FileExtensionContentTypeProvider是可变对象，修改前应确保无并发写入 -
OnPrepareResponse在响应头写入前触发，适合加缓存、CSP 或自定义头 - 对 HTML 文件（如
index.html）不要加强缓存，否则更新后用户可能看不到新内容
开发环境与生产环境的 MIME 类型差异
Windows 上 IIS 或 IIS Express 可能使用系统注册表或 applicationHost.config 提供额外 MIME 映射，而 Kestrel 完全依赖 FileExtensionContentTypeProvider。这意味着同一文件在开发（IIS Express）和部署（Kestrel）时可能返回不同 Content-Type，导致前端报错（比如 Failed to load module script）。
排查方法：用 curl -I http://localhost:5000/foo.js 查看响应头，对比 Content-Type 是否为 application/javascript；若为 text/plain，说明 .js 未被识别——这通常意味着你覆盖了默认 ContentTypeProvider 但没保留原有映射。
- 构造自定义
FileExtensionContentTypeProvider时，建议先复制默认实例：new FileExtensionContentTypeProvider(knownProvider) - Kestrel 不读取 Windows MIME 注册表，一切必须显式配置
- CI/CD 部署脚本中若替换
wwwroot内容，需同步验证静态资源 HTTP 响应头是否符合预期
静态文件看似简单，但 MIME 类型缺失、缓存策略错配、路径映射重叠这几个点，在跨环境部署时最容易引发隐性故障。尤其当引入新格式资源（如 WebAssembly 的 .wasm 文件）时，漏配 ContentTypeProvider 会导致浏览器静默失败。
