托管和部署 ASP.NET Core Blazor WebAssembly

作者：Luke Latham、Rainer Stropek 和 Daniel Roth

使用 Blazor WebAssembly 托管模型：

• 将 Blazor 应用、其依赖项以及 .NET 运行时下载到浏览器。
• 应用将在浏览器线程中直接执行。

支持以下部署策略：

• Blazor 应用由 ASP.NET Core 应用提供服务。 使用 ASP.NET Core 进行托管部署部分中介绍了此策略。
• Blazor 应用位于静态托管 Web 服务器或服务中，其中未使用 .NET 对 Blazor 应用提供服务。 独立部署部分介绍了此策略，包括有关将 Blazor WebAssembly 应用作为 IIS 子应用托管的信息。

重写 URL，以实现正确路由

在 Blazor WebAssembly 应用中路由对页组件的请求不如在 Blazor Server 对托管应用中路由请求直接。 假设有一个 Blazor WebAssembly 应用包含以下两个组件：

• Main.razor – 在应用的根目录处加载并包含指向 About 组件 (href="About") 的链接。
• About.razor – About 组件。

使用浏览器的地址栏（例如，https://www.contoso.com/）请求应用的默认文档：

1. 浏览器发出请求。
2. 返回默认页，通常为 index.html 。
3. index.html 启动应用 。
4. Blazor 的路由器进行加载，然后呈现 Razor Main 组件。

在 Main 页中，选择指向 About 组件的链接适用于客户端，因为 Blazor 路由器阻止浏览器在 Internet 上发出请求，针对 About 转到 www.contoso.com，并为呈现的 About 组件本身提供服务。 针对 Blazor WebAssembly 应用中的 内部终结点的所有请求，工作原理都相同：这些请求不会触发对 Internet 上的服务器托管资源的基于浏览器的请求。 路由器将在内部处理请求。

如果针对 www.contoso.com/About 使用浏览器的地址栏发出请求，则请求会失败。 应用的 Internet 主机上不存在此类资源，所以返回的是“404 - 找不到” 响应。

由于浏览器针对客户端页面请求基于 Internet 的主机，因此 Web 服务器和托管服务必须将对服务器上非物理方式资源的所有请求重写为 index.html 页 。 如果返回 index.html，应用的 Blazor 路由器将接管工作并使用正确的资源响应 。

部署到 IIS 服务器时，可以将 URL 重写模块与应用的已发布 web.config 文件一起使用。 有关详细信息，请参阅 IIS 部分。

使用 ASP.NET Core 进行托管部署

托管部署 通过在 Web 服务器上运行的 ASP.NET Core 应用为浏览器提供 Blazor WebAssembly 应用。

Blazor 应用随附于已发布输出中的 ASP.NET Core 应用，因此这两个应用一起进行部署。 需要能够托管 ASP.NET Core 应用的 Web 服务器。 对于托管部署，Visual Studio 将 Blazor WebAssembly App 项目模板（使用 dotnet new命令时为 blazorwasm 模板）包括在“托管” 选项中。

有关托管和部署 ASP.NET Core 应用的详细信息，请参阅 托管和部署 ASP.NET Core。

若要了解如何部署到 Azure 应用服务，请参阅 使用 Visual Studio 将 ASP.NET Core 应用发布到 Azure。

独立部署

独立部署将 Blazor WebAssembly 应用作为客户端直接请求的一组静态文件提供 。 任何静态文件服务器均可提供 Blazor 应用。

独立部署资产发布到 bin/Release/{TARGET FRAMEWORK}/publish/{ASSEMBLY NAME}/dist 文件夹中 。

IIS

IIS 是适用于 Blazor 应用的强大静态文件服务器。 要配置 IIS 以托管 Blazor，请参阅在 IIS 上生成静态网站。

已发布的资产是在 /bin/Release/{TARGET FRAMEWORK}/publish 文件夹中创建。 在 Web 服务器或托管服务上托管“publish”文件夹内容 。

web.config

发布 Blazor 项目时，将使用以下 IIS 配置创建 web.config 文件：

• 对以下文件扩展名设置 MIME 类型：
  • .dll – application/octet-stream
  • .json – application/json
  • .wasm – application/wasm
  • .woff – application/font-woff
  • .woff2 – application/font-woff
• 对以下 MIME 类型启用 HTTP 压缩：
  • application/octet-stream
  • application/wasm
• 建立 URL 重写模块规则：
  • 提供应用的静态资产驻留所在的子目录 ({ASSEMBLY NAME}/dist/{PATH REQUESTED} )。
  • 创建 SPA 回退路由，以便非文件资产请求能够重定向到应用的静态资产文件夹中的默认文档 ({ASSEMBLY NAME}/dist/index.html )。

安装 URL 重写模块

重写 URL 必须使用 URL 重写模块。 此模块默认不安装，且不适用于安装为 Web 服务器 (IIS) 角色服务功能。 必须从 IIS 网站下载该模块。 使用 Web 平台安装程序安装模块：

1. 以本地方式导航到 URL 重写模块下载页。 对于英语版本，请选择“WebPI”以下载 WebPI 安装程序 。 对于其他语言，请选择适当的服务器体系结构 (x86/x64) 下载安装程序。
2. 将安装程序复制到服务器。 运行安装程序。 选择“安装”按钮，并接受许可条款 。 安装完成后无需重启服务器。

配置网站

将网站的物理路径设置为应用的文件夹 。 该文件夹包含：

• web.config 文件，IIS 使用该文件配置网站，包括所需的重定向规则和文件内容类型 。
• 应用的静态资产文件夹。

作为 IIS 子应用托管

如果独立应用作为 IIS 子应用托管，请执行下列任一操作：

• 禁用继承的 ASP.NET Core 模块处理程序。

  通过向文件添加 <handlers> 部分，删除 Blazor 应用已发布 web.config 文件中的处理程序：

  <handlers>
    <remove name="aspNetCore" />
  </handlers>
  

• 通过使用 <location> 元素并且将 inheritInChildApplications 设置为 false，禁止继承根（父级）应用的 <system.webServer> 部分：

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <handlers>
          <add name="aspNetCore" ... />
        </handlers>
        <aspNetCore ... />
      </system.webServer>
    </location>
  </configuration>
  

除配置应用的基路径外，还需删除处理程序或禁用继承。 在 IIS 中配置子应用时，在应用的 index.html 文件中将应用基路径设置为 IIS 别名 。

疑难解答

如果你看到“500 - 内部服务器错误” ，且 IIS 管理器在尝试访问网站配置时抛出错误，请确认是否已安装 URL 重写模块。 如果未安装该模块，则 IIS 无法分析 web.config 文件 。 这可以防止 IIS 管理器加载网站配置，并防止网站对 Blazor 的静态文件提供服务。

有关排查部署到 IIS 的问题的详细信息，请参阅 Azure App Service 和 IIS 上的 ASP.NET Core 疑难解答。

Azure 存储

Azure 存储静态文件承载允许无服务器的 Blazor 应用承载。 支持自定义域名、Azure 内容分发网络 (CDN) 以及 HTTPS。

为存储帐户上的静态网站承载启用 blob 服务时：

• 设置“索引文档名称” 到 index.html。
• 设置“错误文档路径” 到 index.html。 Razor 组件和其他非文件终结点不会驻留在由 blob 服务存储的静态内容中的物理路径。 当收到 Blazor 路由器应处理的对这些资源之一的请求时，由 blob 服务生成的“404 - 未找到” 错误会将此请求路由到“错误文档路径” 。 返回 Index.html blob，Blazor 路由器会加载并处理此路径。

有关更多信息，请参阅 Azure 存储中的静态网站承载。

Nginx

以下 nginx.conf 文件已简化，以展示如何将 Nginx 配置为，每当在磁盘上找不到相应文件时，发送 index.html 文件。

events { }
http {
    server {
        listen 80;

        location / {
            root /usr/share/nginx/html;
            try_files $uri $uri/ /index.html =404;
        }
    }
}

有关生产 Nginx Web 服务器配置的详细信息，请参阅 Creating NGINX Plus and NGINX Configuration Files（创建 NGINX 增强版和 NGINX 配置文件）。

Docker 中的 Nginx

要使用 Nginx 在 Docker 中托管 Blazor，请设置 Dockerfile，以使用基于 Alpine 的 Nginx 映像。 更新 Dockerfile，以将 nginx.config 文件复制到容器 。

向 Dockerfile 添加一行，如下面的示例中所示：

FROM nginx:alpine
COPY ./bin/Release/netstandard2.0/publish /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/nginx.conf

Apache

若要将 Blazor WebAssembly 应用部署到 CentOS 7 或更高版本：

1. 创建 Apache 配置文件。 下面的示例展示了一个简化的配置文件 (blazorapp.config)：

   <VirtualHost *:80>
       ServerName www.example.com
       ServerAlias *.example.com
   
       DocumentRoot "/var/www/blazorapp"
       ErrorDocument 404 /index.html
   
       AddType aplication/wasm .wasm
       AddType application/octet-stream .dll
   
       <Directory "/var/www/blazorapp">
           Options -Indexes
           AllowOverride None
       </Directory>
   
       <IfModule mod_deflate.c>
           AddOutputFilterByType DEFLATE text/css
           AddOutputFilterByType DEFLATE application/javascript
           AddOutputFilterByType DEFLATE text/html
           AddOutputFilterByType DEFLATE application/octet-stream
           AddOutputFilterByType DEFLATE application/wasm
           <IfModule mod_setenvif.c>
           BrowserMatch ^Mozilla/4 gzip-only-text/html
           BrowserMatch ^Mozilla/4.0[678] no-gzip
           BrowserMatch bMSIE !no-gzip !gzip-only-text/html
       </IfModule>
       </IfModule>
   
       ErrorLog /var/log/httpd/blazorapp-error.log
       CustomLog /var/log/httpd/blazorapp-access.log common
   </VirtualHost>
   

2. 将 Apache 配置文件放入 /etc/httpd/conf.d/ 目录（这是 CentOS 7 中的默认 Apache 配置目录）。

3. 将应用的文件放入 /var/www/blazorapp 目录（配置文件中特定于 DocumentRoot 的位置）。

4. 重启 Apache 服务。

有关详细信息，请参阅 mod_mime 和 mod_deflate。

GitHub 页

要处理 URL 重写，请使用脚本添加 404.html 文件，该脚本可处理到 index.html 页的重定向请求 。 关于社区提供的示例实现，请参阅用于 GitHub 页的单页应用（GitHub 上的 rafrex/spa-github-pages）。 可在 GitHub 上的 blazor-demo/blazor-demo.github.io（实时站点）查看使用社区方法的示例。

如果使用项目站点而非组织站点，请在 index.html 中添加或更新 <base> 标记 。 将 href 属性值设置为，包含尾部斜杠的 GitHub 存储库名称（例如，my-repository/）。

主机配置值

在开发环境中，Blazor WebAssembly 应用可以在运行时接受以下主机配置值作为命令行参数。

内容根

--contentroot 参数设置包含应用内容文件的目录的绝对路径（内容根目录）。 在下面的示例中，/content-root-path 是应用的内容根路径。

• 以本地方式在命令提示符下运行应用时传递该参数。 在应用的目录中，执行以下操作：

  dotnet run --contentroot=/content-root-path
  

• 在 IIS Express 配置文件中，向应用的 launchSettings.json 文件添加条目 。 如果使用 Visual Studio 调试器并在命令提示符中运行 dotnet run 来运行应用，使用的是此设置。

  "commandLineArgs": "--contentroot=/content-root-path"
  

• 在 Visual Studio 中，在“属性” > “调试” > “应用程序参数”中指定参数 。 在 Visual Studio 属性页中设置参数可将参数添加到 launchSettings.json 文件 。

  --contentroot=/content-root-path
  

基路径

--pathbase 参数可设置使用非根相对 URL 路径本地运行的应用的应用基路径（将 <base> 标记 href 针对暂存和生产设置为 / 之外的路径）。 在下面的示例中，/relative-URL-path 是应用的基路径。 有关详细信息，请参阅应用基路径。

• 以本地方式在命令提示符下运行应用时传递该参数。 在应用的目录中，执行以下操作：

  dotnet run --pathbase=/relative-URL-path
  

• 在 IIS Express 配置文件中，向应用的 launchSettings.json 文件添加条目 。 如果使用 Visual Studio 调试器并在命令提示符中运行 dotnet run 来运行应用，使用的是此设置。

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• 在 Visual Studio 中，在“属性” > “调试” > “应用程序参数”中指定参数 。 在 Visual Studio 属性页中设置参数可将参数添加到 launchSettings.json 文件 。

  --pathbase=/relative-URL-path
  

URL

--urls 参数设置 IP 地址或主机地址，其中包含侦听请求的端口和协议。

• 以本地方式在命令提示符下运行应用时传递该参数。 在应用的目录中，执行以下操作：

  dotnet run --urls=http://127.0.0.1:0
  

• 在 IIS Express 配置文件中，向应用的 launchSettings.json 文件添加条目 。 如果使用 Visual Studio 调试器并在命令提示符中运行 dotnet run 来运行应用，使用的是此设置。

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• 在 Visual Studio 中，在“属性” > “调试” > “应用程序参数”中指定参数 。 在 Visual Studio 属性页中设置参数可将参数添加到 launchSettings.json 文件 。

  --urls=http://127.0.0.1:0
  

配置链接器

Blazor 对每个生成执行中间语言 (IL) 链接，以从输出程序集中删除不必要的 IL。 可以在生成时控制程序集链接。 有关详细信息，请参阅 配置 ASP.NET Core Blazor 链接器。