Blazor Server 静态资源 404 问题根源与正确配置方案

Blazor Server 应用中 _framework/blazor.server.js 返回 404，通常并非因缺失引用或路由配置错误，而是因 UseStaticFiles() 被传入自定义 StaticFileOptions 导致 Blazor 内置静态文件服务被覆盖——这是 .NET 5+ 中一个已知行为限制。

blazor server 应用中 `_framework/blazor.server.js` 返回 404，通常并非因缺失引用或路由配置错误，而是因 `usestaticfiles()` 被传入自定义 `staticfileoptions` 导致 blazor 内置静态文件服务被覆盖——这是 .net 5+ 中一个已知行为限制。

在 ASP.NET Core 中，Blazor Server 依赖内置的静态文件中间件来提供 _framework/ 下的核心运行时脚本（如 blazor.server.js）。该服务由 AddServerSideBlazor() 自动注册，并必须通过无参 app.UseStaticFiles() 启用——这是关键前提。

然而，当开发者显式调用 app.UseStaticFiles(new StaticFileOptions { ... })（例如为设置 Cache-Control 头），ASP.NET Core 会注册一个新的、独立的静态文件中间件实例，而该实例默认不包含 _framework 路径的映射规则。由于中间件执行顺序是线性的，后注册的 UseStaticFiles() 会“遮蔽”Blazor 所需的静态资源服务，导致 /_framework/blazor.server.js 始终 404。

✅ 正确做法：保留无参 UseStaticFiles() 作为首个静态文件中间件，确保 Blazor 资源可访问；再按需添加带配置的 UseStaticFiles() 实例，作用于特定子路径：

// ✅ 正确顺序：先无参，再带配置app.UseStaticFiles(); // ← 必须存在，且位于 UseRouting() 之后、UseEndpoints() 之前// ✅ 为 /wwwroot/css/ 等自定义路径添加缓存策略（示例）app.UseStaticFiles(new StaticFileOptions{    FileProvider = new PhysicalFileProvider(Path.Combine(env.WebRootPath, "css")),    RequestPath = "/css",    OnPrepareResponse = ctx =>    {        ctx.Context.Response.Headers.Append("Cache-Control", "public, max-age=604800");    }});// ✅ 同理可配置 js、images 等路径app.UseStaticFiles(new StaticFileOptions{    FileProvider = new PhysicalFileProvider(Path.Combine(env.WebRootPath, "js")),    RequestPath = "/js",    OnPrepareResponse = ctx => ctx.Context.Response.Headers.Append("Cache-Control", "public, max-age=604800")});

⚠️ 注意事项：

• app.UseStaticFiles() 必须出现在 app.UseRouting() 之后、app.UseEndpoints() 之前；
• 不要删除或注释掉无参调用——它是 Blazor 运行时资源（_framework/）的唯一供应者；
• 若项目使用了 webBuilder.UseStaticWebAssets()（如你已在 Program.cs 中配置），它仅影响 Razor 类库中的静态资源，不影响 _framework 路径，不可替代无参 UseStaticFiles()；
• 验证是否生效：启动应用后直接访问 https://localhost:port/_framework/blazor.server.js，应返回 JS 文件内容（HTTP 200），而非 404；
• 若仍失败，请检查 _Layout.cshtml 中 <script src="_framework/blazor.server.js"> 是否位于 </body> 闭合前，且未被其他脚本阻塞加载。

总结：Blazor Server 的静态资源服务具有“独占性”，其工作依赖于框架自动注入的默认静态文件中间件。任何对 UseStaticFiles() 的参数化调用都会创建新实例并破坏该机制。遵循“一个无参主入口 + 多个带路径限定的定制实例”的模式，即可兼顾 Blazor 功能完整性与前端资源缓存优化需求。