已发布的Blazor WASM应用未使用appsettings.Development.json问题排查

核心原因分析 #

Blazor WASM 运行在浏览器客户端，和 ASP.NET Core Server 端的环境变量处理逻辑完全不同，这是问题的核心：

• 服务器端环境变量不生效：你在 IIS 中设置的 ASPNETCORE_ENVIRONMENT 是给服务器端程序用的，Blazor WASM 无法读取这个服务器端环境变量。
• 配置文件可能未被打包：如果项目文件没有配置将 appsettings.Development.json 复制到发布输出目录，即使是 Debug 配置发布，这个文件也不会被包含进去，自然无法加载。
• 客户端环境标识未设置：Blazor WASM 依赖客户端的环境标识加载对应配置，默认没有显式设置时会使用 Production 环境，只加载 appsettings.json。

修复建议 #

1. 确保配置文件被包含在发布输出中 #

编辑 Blazor WASM 项目文件（.csproj），添加以下配置，保证 appsettings.Development.json 会被复制到发布目录：

<ItemGroup>
  <Content Include="appsettings.Development.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </Content>
</ItemGroup>

如果只想在 Debug 配置下包含该文件，可添加条件限制：

<ItemGroup>
  <Content Include="appsettings.Development.json" Condition="'$(Configuration)' == 'Debug'">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </Content>
</ItemGroup>

2. 显式设置客户端环境标识 #

有两种方式让 Blazor WASM 识别到 Development 环境：

方式一：修改 index.html

在 index.html 的 <head> 标签中，在加载 Blazor 脚本之前添加以下代码，直接指定客户端环境：

<script>
  window.BlazorEnvironment = "Development";
</script>

方式二：构建时指定环境参数

使用 .NET CLI 发布时，通过参数直接指定 Blazor 环境：

dotnet publish -c Debug /p:BlazorEnvironment=Development

构建后的发布包会自动使用 Development 环境，加载对应配置文件。

3. 验证配置加载逻辑 #

在 Program.cs 中添加日志输出，确认当前环境是否正确：

var builder = WebAssemblyHostBuilder.CreateDefault(args);
// 输出当前环境，验证是否为 Development
Console.WriteLine($"Current environment: {builder.HostEnvironment.Environment}");

builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

await builder.Build().RunAsync();

默认情况下，WebAssemblyHostBuilder.CreateDefault(args) 会根据客户端环境自动加载 appsettings.{Environment}.json，只要环境标识正确，配置就会被加载。

部署时的配置规范 #

• 不同环境部署时，建议通过构建参数指定 BlazorEnvironment，避免手动修改 index.html，减少出错概率。
• 生产环境部署时，确保不包含 appsettings.Development.json，只保留生产环境配置文件，避免敏感信息泄露。

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