ASP.NET Core Blazor 静态文件

本文介绍用于提供静态文件的 Blazor 应用配置。

静态资产中间件

本部分适用于服务器端 Blazor 应用。

在应用的请求处理管道中调用 UseStaticFiles，将静态文件中间件配置为向客户端提供静态资产。 有关详细信息，请参阅 ASP.NET Core 中的静态文件。

在 .NET 8 之前的版本中，Blazor 框架静态文件（如 Blazor 脚本）通过静态文件中间件提供。 在 .NET 8 及更高版本中，Blazor 框架静态文件通过终结点路由进行映射，而不再使用静态文件中间件。

静态 Web 资产项目模式

本部分适用于 Blazor Web 应用的 .Client 项目。

Blazor Web 应用的 .Client 项目中所需的 <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> 设置会将 Blazor WebAssembly 静态资产行为恢复为默认值，使该项目作为托管项目的一部分运行。 Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) 以特定方式配置静态 Web 资产，以便在“独立”模式下工作，服务器只需使用库的输出。 这不适用于 Blazor Web 应用，其中，应用的 WebAssembly 部分是主机的逻辑部分，必须表现得更像库。 例如，项目不公开样式捆绑包（例如 BlazorSample.Client.styles.css），而是仅向主机提供项目捆绑包，以便主机可以将其包括在自己的样式捆绑包中。

不支持更改 <StaticWebAssetProjectMode> 的值 (Default) 或从 .Client 项目中删除该属性。

非 Development 环境中的静态文件

本部分适用于服务器端静态文件。

在本地运行应用时，静态 Web 资产仅在 Development 环境中默认启用。 若要在本地开发和测试期间为 Development 以外的环境启用静态文件（例如 Staging），请在 Program 文件中的 WebApplicationBuilder 上调用 UseStaticWebAssets。

警告

为确切环境调用 UseStaticWebAssets 以防止在生产环境中激活该功能，因为如果在生产环境中调用，该功能会从磁盘上的不同位置提供文件（而不是从项目提供）。 本部分中的示例通过调用 IsStaging 来检查 Staging 环境。

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Blazor WebAssembly 资产的前缀

本部分适用于 BlazorWeb 应用。

使用 WebAssemblyComponentsEndpointOptions.PathPrefix 终结点选项设置指示 Blazor WebAssembly 资产的前缀的路径字符串。 该路径必须对应于引用的 Blazor WebAssembly 应用程序项目。

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

在上一示例中，{PATH PREFIX} 占位符是路径前缀，必须以正斜杠 (/) 开头。

在以下示例中，路径前缀设置为 /path-prefix：

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

静态 Web 资产基路径

本部分适用于独立的 Blazor WebAssembly 应用。

默认情况下，发布应用会将应用的静态资产（包括 Blazor 框架文件 (_framework)）放置在已发布输出的根路径 (/) 中。 项目文件 (.csproj) 中指定的 <StaticWebAssetBasePath> 属性将基路径设置到非根路径：

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

在前面的示例中，{PATH} 占位符是路径。

如果未设置 <StaticWebAssetBasePath> 属性，则独立应用发布在 /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/。

在前面的示例中，{TFM} 占位符是目标框架名字对象 (TFM)（例如 net6.0）。

如果独立 Blazor WebAssembly 应用中的 <StaticWebAssetBasePath> 属性将发布的静态资产路径设置为 app1，则发布的输出中应用的根路径为 /app1。

在独立 Blazor WebAssembly 应用的项目文件（.csproj）中：

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

在发布的输出中，独立 Blazor WebAssembly 应用的路径为 /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/。

在前面的示例中，{TFM} 占位符是目标框架名字对象 (TFM)（例如 net6.0）。

文件映射和静态文件选项

本部分适用于服务器端静态文件。

若要使用 FileExtensionContentTypeProvider 创建其他文件映射，或者要配置其他 StaticFileOptions，请使用以下方法之一。 在以下示例中，{EXTENSION} 占位符为文件扩展名，{CONTENT TYPE} 占位符为内容类型。 以下 API 的命名空间是 Microsoft.AspNetCore.StaticFiles。

• 使用 StaticFileOptions 通过 Program 中的依赖项注入 (DI) 来配置选项：

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  builder.Services.Configure<StaticFileOptions>(options =>
  {
      options.ContentTypeProvider = provider;
  });
  
  app.UseStaticFiles();
  

• 将 StaticFileOptions 直接传递到 Program 文件中的 UseStaticFiles：

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
  

其他资源

应用基路径