通过

使用 GitHub Pages 托管和部署 ASP.NET Core 独立 Blazor WebAssembly 版

注释

此版本不是本文的最新版本。 有关当前版本的信息，请参阅.NET 9 版本的本文。

警告

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

重要

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

有关当前版本的信息，请参阅.NET 9 版本的本文。

本文介绍如何使用 Blazor WebAssembly 托管和部署独立。

下面的 Blazor WebAssembly 应用 GitHub Pages 部署指南，通过一个部署到 GitHub Pages 的实时工具，展示了相关概念。 该工具由 ASP.NET Core 文档作者用于创建指向 API 文档的交叉引用 (XREF) 链接，以便用于文章的 markdown。

GitHub Pages 设置

  • Actions>常规
    • 操作权限
      • 允许企业操作，并选择非企业操作和可重用工作流> 启用（已选择）
      • 允许 GitHub 创建的操作> 已启用（已选中）
      • 允许操作和可重用工作流>stevesandersonms/ghaction-rewrite-base-href@{SHA HASH},†
    • 工作流权限>读取存储库内容和包权限
  • 页面>生成和部署
    • 源>GitHub Actions
    • 所选工作流：静态 HTML，并将静态部署操作脚本基于 Xref 生成器工具的 Xref 生成器 static.yml 文件。 下一部分中介绍了文件中的配置。
    • 自定义域：如果打算使用本指南未涵盖的自定义域，请进行设置。 有关详细信息，请参阅为 GitHub Pages 站点配置自定义域。
    • 实施 HTTPS> 已启用（已选中）

† SHA 哈希（{SHA HASH} 占位符）表示最新 stevesandersonms/ghaction-rewrite-base-href GitHub Action 发布版本的 SHA 哈希。 通过固定到特定版本，使用版本标识符（例如 v1）的被损害的最新版本可能会危及部署的风险较小。 定期将 SHA 更新到最新版本，以获取最新功能和 bug 修复。

若要获取 SHA 哈希，请执行以下命令：

  1. 导航到 SteveSandersonMS/ghaction-rewrite-base-href Action GitHub 存储库。
  2. 在页面右侧的发布下选择发布。
  3. 找到并选择短 SHA 哈希（例如 5b54862）。
  4. 以下两个因素中的任一个：
    • 从浏览器地址栏中的 URL 获取完整的 SHA。
    • 选择页面“ 复制”按钮右侧的“复制”按钮 ，将 SHA 放在剪贴板上。

有关详细信息，请参阅在工作流中使用预编写的构建基块：使用 SHA（GitHub 文档）。

静态部署脚本配置

Xref 生成器 static.yml 文件

在脚本中为部署配置以下条目：

  • 发布目录 (PUBLISH_DIR)：使用发布 Blazor WebAssembly 应用的存储库文件夹的路径。 针对特定的 .NET 版本编译该应用，版本的路径段必须匹配。 示例：BlazorWebAssemblyXrefGenerator/bin/Release/net9.0/publish/wwwroot是采用 .NET 9 SDK net9.0的应用的路径。
  • 推送路径 (on:push:paths)：设置推送路径以将应用的存储库文件夹与 ** 通配符匹配。 示例：BlazorWebAssemblyXrefGenerator/**。
  • .NET SDK 版本（dotnet-version 通过 actions/setup-dotnet Action）：目前，无法将版本设置为“latest”（请参阅允许将“latest”指定为 dotnet 版本 (actions/setup-dotnet #497)，为此功能请求投赞同票）。 将 SDK 版本设置为至少与应用的框架版本一样高。
  • 发布路径（dotnet publish 命令）：将发布文件夹路径设置为应用的存储库文件夹。 示例：dotnet publish BlazorWebAssemblyXrefGenerator -c Release。
  • Base HREF（适用于 base_href的 SteveSandersonMS/ghaction-rewrite-base-href）：设置最新版本操作的 SHA 哈希（请参阅 GitHub Pages 设置部分中的指南以获取说明）。 将应用的基本 href 设置为存储库的名称。 示例：Blazor 示例的存储库所有者为 dotnet。 Blazor 示例的存储库名称为 blazor-samples。 将 Xref 生成器工具部署到 GitHub Pages 时，其 Web 地址基于存储库的名称 (https://dotnet.github.io/blazor-samples/)。 应用的 base href 为 /blazor-samples/，它会被设置为 base_href，以便 ghaction-rewrite-base-href Action 在部署应用时写入到应用的 wwwroot/index.html<base> 标签。 有关详细信息，请参阅 ASP.NET Core Blazor 应用基路径。

GitHub 托管的 Ubuntu（最新）服务器预安装了 .NET SDK 版本。 如果预安装的 .NET SDK 足以编译应用，则可以从 actions/setup-dotnet 脚本中删除 步骤。 若要确定为 ubuntu-latest 安装的 .NET SDK，请执行以下操作：

  1. 转到GitHub 存储库actions/runner-images的 可用映像部分。
  2. 找到 ubuntu-latest 映像，这是表的第一行。
  3. 选择 Included Software 列中的链接。
  4. 向下滚动到 .NET 工具部分，查看通过映像安装的 .NET Core SDK。

部署注意事项

默认的 GitHub Action（用于部署网页）会跳过部署以下划线开头的文件夹，例如 _framework 文件夹。 若要部署以下划线开头的文件夹，请将一个空的 .nojekyll 文件添加到应用程序存储库的根目录中。 示例：Xref 生成器 .nojekyll 文件

在第一个应用部署之前执行此步骤： Git 将 JavaScript (JS) 文件（如 blazor.webassembly.js）视为文本，并在部署管道中将行尾结束符号从 CRLF（回车换行符）转换为 LF（换行符）。 这些对 JS 文件的更改产生的文件哈希值与发送给客户端的 Blazor 不同。 这种不匹配会导致客户端完整性检查失败。 解决此问题的一种方法是在将应用的资产添加到 Git 分支之前，先添加一个包含 .gitattributes 行的 *.js binary 文件。 该 *.js binary 行将 Git 配置为将文件视为 JS 二进制文件，从而避免在部署管道中处理文件并导致客户端完整性检查通过。 有关详细信息，请参阅 ASP.NET Core Blazor WebAssembly .NET 捆绑包缓存和完整性检查失败。 示例：Xref 生成器 .gitattributes 文件

若要根据用于 GitHub 页的单页应用（rafrex/spa-github-pages GitHub 存储库）处理 URL 重写，请执行以下步骤：

GitHub Pages 本身不支持使用 Brotli 压缩的资源。 使用 Brotli：