ASP.NET Core Blazor 静态文件

项目
04/11/2024

注意

此版本不是本文的最新版本。对于当前版本，请参阅此文的 .NET 8 版本。

重要

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

对于当前版本，请参阅此文的 .NET 8 版本。

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

Blazor 框架静态文件

在 .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 项目中删除该属性。

静态文件中间件

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

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

非 `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）。

本部分适用于独立 Blazor WebAssembly 应用和托管的 Blazor WebAssembly 解决方案。

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

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

如果不设置 <StaticWebAssetBasePath> 属性，托管解决方案的客户端应用或独立应用将按照以下路径发布：

托管的 Blazor WebAssembly 解决方案的 Server 项目中：/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
独立 Blazor WebAssembly 应用中：/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

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

在 Client 应用的项目文件 (.csproj) 或独立 Blazor WebAssembly 应用的项目文件 (.csproj) 中：

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

在已发布的输出中：

托管的 Blazor WebAssembly 解决方案的 Server 项目中客户端应用的路径：/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
独立 Blazor WebAssembly 应用的路径：/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

<StaticWebAssetBasePath> 属性最常用于控制单个托管部署中多个 Blazor WebAssembly 应用的已发布静态资产的路径。有关详细信息，请参阅多个托管的 ASP.NET Core Blazor WebAssembly 应用。该属性在独立 Blazor WebAssembly 应用中也有效。

在前面的示例中，{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 });

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

使用 StaticFileOptions 通过 Program 中的依赖项注入 (DI) 来配置选项：
```
using Microsoft.AspNetCore.StaticFiles;

...

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

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});
```
此方法配置用于提供 Blazor 脚本的同一文件提供程序。确保自定义配置不会干扰提供 Blazor 脚本。例如，不要通过使用 provider.Mappings.Remove(".js") 配置提供程序来删除 JavaScript 文件的映射。

在 Program 文件中使用两次对 UseStaticFiles 的调用：

使用 StaticFileOptions 在第一次调用中配置自定义文件提供程序。
第二个中间件提供 Blazor 脚本，其使用 Blazor 框架提供的默认静态文件配置。

using Microsoft.AspNetCore.StaticFiles;

...

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

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

可以使用 MapWhen 执行自定义静态文件中间件来避免在提供 _framework/blazor.server.js 时受到干扰：

app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

其他资源

应用基路径

ASP.NET Core Blazor 静态文件

Blazor 框架静态文件

静态 Web 资产项目模式

静态文件中间件

非 Development 环境中的静态文件

Blazor WebAssembly 资产的前缀

静态 Web 资产基路径

文件映射和静态文件选项

其他资源

反馈

其他资源

非 `Development` 环境中的静态文件