Blazor WASM托管项目添加自定义环境返回404问题求解

编辑说明：我已重写本帖补充更多问题信息，并附上可复现问题的示例项目链接。

我正尝试为托管型Blazor WebAssembly（WASM）应用新增用于测试的自定义运行环境，将该环境命名为Express，已搭建可复现问题的演示项目。

基于官方Blazor WASM托管模板新建项目后，我首先在Blazor客户端项目的wwwroot目录下新增2个HTML页面，共3个HTML文件分别对应不同运行环境：

在该简易演示项目中，各HTML文件的唯一差异为Blazor的启动配置。以index.express.html中加载Blazor的代码为例：

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
    Blazor.start({
        environment: "Express"
    });
</script>

在实际业务项目中各环境页面还有其他差异（例如<base>元素配置），当前演示已足够复现问题。

服务端侧我新增了对应的appsettings配置文件：

同时我修改了服务端的launchSettings.json文件，将ASPNETCORE_ENVIRONMENT环境变量设置为Express：

"BlazorHostedDemo.Server": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
  "applicationUrl": "https://localhost:7261;http://localhost:5261",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Express" 
  }
},

我原本认为以上配置已足够让Kestrel Web服务器启用Express环境。

随后我修改了Blazor应用加载的默认文件名逻辑，使其随运行环境自动切换对应页面文件：

var filename = app.Environment.IsDevelopment()
                   ? "index.development.html"
                   : app.Environment.IsEnvironment("Express")
                       ? "index.express.html"
                       : "index.html";

app.MapFallbackToFile(filename);

完成以上修改后，我预期Kestrel会使用Express环境并加载index.express.html文件，但实际并未生效。经确认Kestrel确实已加载正确的Express环境：

但Kestrel访问默认页面时返回404错误，无法找到index.express.html文件：

经排查该问题并非文件名错误或文件缺失导致：即使我将Express环境的回退文件设置为默认的index.html，依然会返回相同的404错误：

app.MapFallbackToFile("index.html");

我还注意到：如果将launchSettings.json中的环境改回Development，则任意HTML文件都可以正常加载对外提供服务。

我不清楚Visual Studio中按F5启动项目时的具体执行逻辑，原本预期客户端wwwroot目录和客户端DLL文件会被复制到服务端项目的输出目录，但实际并未发生。看起来静态文件中间件仅在环境为Development时，会从客户端项目的wwwroot目录返回HTML文件，切换到自定义环境后该逻辑不会生效。

我曾尝试向MapFallbackToFile方法传入自定义StaticFileOptions对象，直接指向客户端wwwroot的物理路径，此时HTML文件可以被正常提供服务，但后续会出现无法找到blazor js文件、项目名对应自动生成CSS文件的问题。

请问我的配置存在什么错误？如何在Visual Studio 2022中为Blazor应用正确配置可正常使用的自定义运行环境？

问题根因 #

默认托管型Blazor WASM模板的本地调试静态资源映射规则，仅在ASPNETCORE_ENVIRONMENT值为Development时生效。切换到自定义环境后，服务端不会自动将客户端项目的wwwroot目录加入静态文件搜索路径，也不会自动处理_framework路径下的Blazor运行时资源，因此所有客户端静态资源（包括自定义HTML页、Blazor JS文件、自动生成的样式文件）都会返回404。

修复步骤 #

• 调整服务端中间件配置
  打开服务端项目的Program.cs，检查UseStaticFiles和UseBlazorFrameworkFiles中间件是否被包裹在if (app.Environment.IsDevelopment())判断块中，如果是就将这两个中间件移出判断块，确保所有环境下都会加载：

  // 路由、授权相关配置按原有顺序保留即可
  app.UseStaticFiles();
  app.UseBlazorFrameworkFiles();
  
  // 保留原有的回退页判断逻辑
  var filename = app.Environment.IsDevelopment()
                     ? "index.development.html"
                     : app.Environment.IsEnvironment("Express")
                         ? "index.express.html"
                         : "index.html";
  
  app.MapFallbackToFile(filename);
  

• 修改服务端项目文件，启用全环境静态资源支持
  右键服务端项目选择「编辑项目文件」，做两处修改：

  • 找到对客户端项目的ProjectReference节点，补充配置项，确保所有环境下都能正确引用客户端的静态资源输出：

    <ProjectReference Include="..\BlazorHostedDemo.Client\BlazorHostedDemo.Client.csproj">
      <ReferenceOutputAssembly>true</ReferenceOutputAssembly>
    </ProjectReference>
    

  • 在顶层<PropertyGroup>节点中添加配置，关闭静态资源仅在开发环境生效的限制：

    <StaticWebAssetsEnabled>true</StaticWebAssetsEnabled>
    

• 验证效果
  清理解决方案后重新生成，再按F5调试即可正常加载Express环境对应的页面，Blazor运行时资源、自动生成的CSS等文件都可以正常访问。

补充：该问题仅存在于本地Visual Studio F5调试场景，正式发布时SDK会自动将客户端项目的所有wwwroot资源打包到服务端发布目录，无需额外配置。

内容的提问来源于stack exchange，提问作者Luis Abreu