ASP.NET Core Blazor 环境

2025-09-19

注意

这不是本文的最新版本。要查看当前版本，请参阅本文的 .NET 9 版本。

警告

不再支持此版本的 ASP.NET Core。有关详细信息，请参阅 .NET 和 .NET Core 支持策略。要查看当前版本，请参阅本文的 .NET 9 版本。

重要

此信息与在商业发布之前可能进行大幅修改的预发布产品有关。 Microsoft对此处提供的信息不作任何明示或暗示的保证。

要查看当前版本，请参阅本文的 .NET 9 版本。

本文介绍如何在应用中配置和查看 Blazor 环境。

在本地运行应用时，环境默认为 Development。发布应用时，环境默认为 Production。

我们建议采用以下约定：

始终使用“Development”环境名称进行本地开发。这是因为，ASP.NET Core 框架在为应用的本地开发运行配置应用和工具时完全需要该名称。
对于测试、过渡环境和生产环境，请始终发布和部署应用。可以使用希望用于已发布应用的任何环境命名方案，但始终使用应用设置文件名，环境段的大小写应与环境名称完全匹配。若要进行部署，请使用“Staging”（大写的“S”）作为环境名称，并将应用程序设置文件命名为“appsettings.Staging.json”以匹配。对于生产，请使用“Production”（大写“P”）作为环境名称，并将应用设置文件命名为匹配（appsettings.Production.json）。

设置环境

环境是使用以下任一方法设置的：

Blazor Web App 或 Blazor Server：对常规 ASP.NET Core 应用使用 ASP.NET Core 运行时环境中介绍的任何方法。
任何 Blazor 应用：Blazor 启动设置
独立 Blazor WebAssembly：<WasmApplicationEnvironmentName> 属性

在 Blazor Web App 的客户端上，环境是通过开发人员不与之交互的 HTML 注释从服务器确定的：

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

对于独立Blazor WebAssembly应用，请在应用的项目文件（<WasmApplicationEnvironmentName>）中使用.csproj属性设置环境。以下示例设置 Staging 环境：

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

默认环境 Development 用于生成和 Production 发布。

Blazor Web App 或 Blazor Server：对常规 ASP.NET Core 应用使用 ASP.NET Core 运行时环境中介绍的任何方法。
任何 Blazor 应用：
- Blazor 启动配置
- Azure 应用程序服务
Blazor WebAssembly：Blazor-Environment 标头

在 Blazor Web App 的客户端上，中间件从服务器确定环境，并通过名为 Blazor-Environment 的标头将环境信息传递给浏览器。该标头会在 WebAssemblyHost 于客户端侧 Program 文件 (WebAssemblyHostBuilder.CreateDefault) 中创建时设置环境。

对于在本地运行的独立 Blazor WebAssembly 应用，开发服务器会添加 Blazor-Environment 标头，其中包含从托管环境获取的环境名称。托管环境根据项目的 ASPNETCORE_ENVIRONMENT 文件建立的 Properties/launchSettings.json 环境变量设置环境。从 Blazor WebAssembly 项目模板创建的项目中环境变量的默认值 Development。有关详细信息，请参阅通过标头设置客户端环境部分。

Blazor Server：将 ASP.NET Core 运行时环境中介绍的任何方法用于常规 ASP.NET Core 应用。
Blazor Server 或 Blazor WebAssembly：
- Blazor 启动配置
- Azure 应用程序服务
Blazor WebAssembly：Blazor-Environment 标头

在托管 Blazor WebAssembly 应用的客户端上，环境通过中间件从服务器确定，该中间件通过名为的 Blazor-Environment标头将环境与浏览器通信。该标头会在 WebAssemblyHost 于客户端侧 Program 文件 (WebAssemblyHostBuilder.CreateDefault) 中创建时设置环境。

对于在开发中本地运行的应用，应用默认为 Development 环境。发布应用会将环境默认为 Production。

有关 ASP.NET Core 应用配置的一般指南，请参阅 ASP.NET Core 运行时环境。在开发和测试期间，对于除去 `Development` 环境以外具有静态文件的服务器端应用配置（例如 `Staging`），请参阅《ASP.NET Core 中的静态文件》。

通过 Blazor 启动配置设置客户端环境

如果主机名包含 Blazor，以下示例将在 Staging 环境中启动 localhost。否则，环境将设置为其默认值。

Blazor Web App：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。 有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

注意

对于在 Blazor Web App 配置中设置 webAssembly>environment 属性的 Blazor.start，明智的做法是将服务器端环境与 environment 属性上设置的环境相匹配。否则，服务器上的预渲染在不同于客户端的环境中运行，这会产生不可预测的效果。有关为环境 Blazor Web App设置的一般指南，请参阅 ASP.NET 核心运行时环境。

独立 Blazor WebAssembly：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。 有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

使用 environment 属性替代 Blazor-Environment 标头设置的环境。

上述方法在不更改 Blazor-Environment 标头值的情况下设置客户端的环境，也不会更改采用全局交互式 WebAssembly 呈现的 Blazor Web App 的服务器项目启动环境的控制台日志记录。

若要在独立Blazor WebAssembly应用或.Client的Blazor Web App项目中将环境记录到控制台，请在通过Program创建WebAssemblyHost之后，并在生成和运行项目的行WebAssemblyHostBuilder.CreateDefault之前，将以下 C# 代码放入await builder.Build().RunAsync();文件中：

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

有关 Blazor 启动的详细信息，请参阅 ASP.NET Core Blazor 启动。

通过标头设置客户端环境

Blazor WebAssembly 应用可以使用 Blazor-Environment 标头设置环境。具体而言，必须在 _framework/blazor.boot.json 文件上设置响应标头，但对于其他 Blazor 文件请求或整个 Blazor 部署，在文件服务器响应上设置标头不会造成任何损害。

尽管 Blazor 框架以混合字母大小写 (Blazor-Environment) 的 kebab 大小写形式发出标头名称，但欢迎使用全小写或全大写的 kebabe 大小写（blazor-environment、BLAZOR-ENVIRONMENT）。

对于使用 Blazor的内置开发服务器运行的本地开发，可以通过在项目的 Blazor-Environment 文件中设置 ASPNETCORE_ENVIRONMENT 环境变量的值来控制 Properties/launchSettings.json 标头的值。使用开发服务器在本地运行时，确定应用的环境的优先顺序是 Blazor.start 配置（environment 键）>Blazor-Environment 响应标头（blazor.boot.json 文件）>ASPNETCORE_ENVIRONMENT 环境变量（launchSettings.json）。不能对已部署 ASPNETCORE_ENVIRONMENT 应用使用 launchSettings.json 环境变量（Blazor WebAssembly）方法。此方法仅适用于本地运行应用的开发服务器。

IIS

在 IIS 的以下示例中，自定义标头（Blazor-Environment）将添加到已发布的 web.config 文件中。 web.config 文件位于 bin/Release/{TARGET FRAMEWORK}/publish 文件夹中，其中 {TARGET FRAMEWORK} 占位符是目标框架：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    ...
    <httpProtocol>
      <customHeaders>
        <add name="Blazor-Environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

注意

若要为 IIS 使用一个自定义 web.config 文件，并且它在应用发布到 publish 文件夹时不会被覆盖，请参阅“通过 IIS 托管和部署 ASP.NET CoreBlazor WebAssembly”。

Nginx

对于 Nginx 服务器，请使用 add_header中的 ngx_http_headers_module 指令：

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

有关详细信息，请参阅以下资源：

Apache

对于 Apache 服务器，请使用 Header 模块中的 mod_headers 指令：

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

有关详细信息，请参阅以下资源：

设置 Azure 应用服务的环境

对于 Blazor WebAssembly 独立应用，可以通过启动配置或 Blazor-Environment 标头来手动设置环境。

对于服务器端应用，请通过 Azure 中的 ASPNETCORE_ENVIRONMENT 应用设置设置环境：

确认应用设置文件名中环境段的大小写与其环境名称大小写完全匹配。例如，Staging 环境的匹配应用设置文件名是 appsettings.Staging.json。如果文件名 appsettings.staging.json（小写“s”），则该文件未找到，并且该文件中的设置不会在 Staging 环境中使用。
对于 Visual Studio 部署，请确认应用已部署到正确的部署槽位。对于名为 BlazorAzureAppSample的应用，应用将部署到 Staging 部署槽位。
在 Azure 门户的环境部署槽位中，通过 ASPNETCORE_ENVIRONMENT 应用设置来设置环境。对于名为 BlazorAzureAppSample 的应用，暂存应用服务槽命名为 BlazorAzureAppSample/Staging。对于 Staging 槽的配置，请通过值 ASPNETCORE_ENVIRONMENT 为 Staging 创建应用设置。已为该设置启用了部署槽位设置。

在浏览器中请求时，BlazorAzureAppSample/Staging 应用会在 Staging 的 https://blazorazureappsample-staging.azurewebsites.net 环境中加载。

在浏览器中加载应用时，blazor.boot.json 的响应头集合指示 Blazor-Environment 标头值为 Staging。

appsettings.{ENVIRONMENT}.json 文件中的应用设置由应用加载，其中 {ENVIRONMENT} 占位符是应用的环境。在前面的示例中，将加载 appsettings.Staging.json 文件中的设置。

在 Blazor WebAssembly 应用中读取环境

通过注入 IWebAssemblyHostEnvironment 并读取 Environment 属性来获取组件中的应用环境。

ReadEnvironment.razor：

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

在 Blazor Web App 中读取环境客户端信息

假设组件或应用未禁用预呈现，则服务器上预呈现 .Client 项目中的组件。由于服务器没有注册 IWebAssemblyHostEnvironment 服务，因此无法在服务器预呈现期间注入服务并使用服务实现的主机环境扩展方法和属性。将服务注入交互式 WebAssembly 或交互式自动组件会导致以下运行时错误：

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

若要解决此问题，请为服务器上的 IWebAssemblyHostEnvironment 创建自定义服务实现。有关详细信息和示例实现，请参阅预呈现文章的服务器部分中的“自定义服务实现”，稍后将在Blazor文档中显示。

在启动时读取客户端环境

在启动过程中，WebAssemblyHostBuilder 会通过 IWebAssemblyHostEnvironment 属性公开 HostEnvironment，这会在主机生成器代码中启用环境特定的逻辑。

在文件Program中：

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

使用通过 WebAssemblyHostEnvironmentExtensions 提供的下列便捷扩展方法，可在当前环境中检查 Development、Production、Staging 和自定义环境名称：

在文件Program中：

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

IWebAssemblyHostEnvironment.BaseAddress 服务不可用时，可以在启动期间使用 NavigationManager 属性。

其他资源

反馈

此页面是否有帮助？