静态文件404需检查UseStaticFiles()位置是否在UseRouting()之后；须配置FileProvider暴露非wwwroot目录；ContentTypeProvider需补充新扩展名映射；注意Cache-Control缓存与发布时wwwroot文件是否正确包含。
静态文件没返回 404？检查 UseStaticFiles() 是否在 UseRouting() 之后
ASP.NET Core 6+ 默认模板里，UseStaticFiles() 必须放在 UseRouting() 和 UseEndpoints()（或 UseAuthorization()）之间，否则中间件链根本不会走到它。常见错误是把它写在 UseRouting() 前面，结果所有 /css/app.css 请求全被路由系统拦下，直接 404。
正确顺序示例：
app.UseRouting(); app.UseStaticFiles(); // ← 这里 app.UseAuthentication(); app.UseAuthorization(); app.MapControllers();
-
UseStaticFiles()是一个终端中间件（不自动调用 next），所以位置错就彻底失效 - 如果用了
UseEndpoints()（旧版），它必须在UseEndpoints()之前；新版MapControllers()同理 - 开发环境默认启用，但发布到 IIS 或 Linux 时，别假设它“自动生效”——Kestrel 本身不处理静态文件，全靠这个中间件
想让 /wwwroot 外的目录可访问？用 StaticFileOptions 配置 FileProvider
默认只服务 wwwroot 下的文件。要暴露其他目录（比如 uploads/ 或 client-dist/），不能靠改路径别名，得显式配置 FileProvider 和请求路径前缀。
例如暴露项目根下的 public/ 目录为 /static：
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(Path.Combine(env.ContentRootPath, "public")),
RequestPath = "/static"
});
-
RequestPath是 URL 前缀（必须以/开头），不是磁盘路径 -
PhysicalFileProvider的路径必须是绝对路径，用env.ContentRootPath拼接，别硬写相对路径 - 多个
UseStaticFiles()调用是允许的，但注意顺序——先匹配上的会拦截后续规则 - Windows 上大小写不敏感，Linux 上敏感，
FileProvider不做转换，文件名大小写必须严格匹配
图片/字体 404 但 HTML 正常？查 ContentTypeProvider 是否支持扩展名
Kestrel 静态中间件依赖 IContentTypeProvider 推断响应头 Content-Type。如果它不认识某个后缀（比如 .webp、.woff2），会返回空 Content-Type，某些浏览器或 CDN 可能因此拒绝加载。
添加缺失类型的方法：
var provider = new FileExtensionContentTypeProvider();
provider.Mappings[".webp"] = "image/webp";
provider.Mappings[".woff2"] = "font/woff2";
app.UseStaticFiles(new StaticFileOptions
{
ContentTypeProvider = provider
});
- 默认映射表有限，
.js、.css、.png没问题，但新格式常被漏掉 - 不要覆盖整个
Mappings字典，用provider.Mappings.Add()或上面这种赋值方式追加 - 如果用的是 Nginx/Apache 做反向代理，它们也可能根据后缀设
Content-Type，和 Kestrel 行为不一致时容易混淆问题源头
部署后 CSS/JS 不更新？别只刷新浏览器，确认 Cache-Control 和文件哈希
开发时改完 CSS 刷新就生效，但上线后常遇到用户还在用旧 JS。这不是中间件配置问题，而是浏览器缓存 + 缺少文件指纹导致的。
- Kestrel 默认对静态文件加
Cache-Control: public,max-age=31536000（1年），前提是文件没变过——它靠文件最后修改时间判断，不是内容 - 简单改时间戳或重启应用不会触发更新，因为物理文件没变，ETag 和 Last-Modified 都不变
- 真正可靠的方案是构建时生成带哈希的文件名（如
app.a1b2c3.js），再配合UseStaticFiles()的默认行为（它支持基于文件名的强缓存） - 如果没法改构建流程，临时办法是加查询参数（
app.js?v=1.2.3），但 Kestrel 不解析 URL 查询参数，需前端控制或用 Nginx 重写
最易被忽略的一点：wwwroot 下的文件在发布时是否真的被复制过去？检查 .csproj 里有没有漏掉
