如何在GitHub Pages托管无index.html的ASP.NET Core 8 Blazor Web应用

1. 确保项目发布时生成index.html #

如果你的Blazor Web App是单项目模式（无独立客户端项目），需在项目文件（.csproj）中添加配置，让发布流程自动生成index.html：

<PropertyGroup>
  <!-- 启用自动生成静态页面，包含index.html -->
  <BlazorEnableAutoGeneratedPages>true</BlazorEnableAutoGeneratedPages>
  <!-- 适配GitHub Pages的仓库路径，替换为你的实际仓库名称 -->
  <StaticWebAssetBasePath>/你的仓库名称/</StaticWebAssetBasePath>
</PropertyGroup>

如果是托管式Blazor Web App（含Server和Client子项目），直接发布Client项目即可，Client项目会自动在发布目录的wwwroot下生成index.html。

2. 调整GitHub Actions部署脚本 #

修改.github/workflows/deploy.yml文件，确保指向正确的发布输出目录：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 8.0.x

      - name: Publish Blazor App
        run: dotnet publish --configuration Release --output publish

      # 单项目用publish/wwwroot；托管项目替换为Client/bin/Release/net8.0/publish/wwwroot
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: publish/wwwroot
          branch: gh-pages
          clean: true

3. 处理GitHub Pages的路由回退问题 #

GitHub Pages是静态托管服务，无法直接识别Blazor客户端路由，访问/page1这类非根路径会返回404。解决方法：

• 在项目的wwwroot目录下创建404.html，内容与自动生成的index.html完全一致（发布后会同步到输出目录）。
• 当GitHub Pages返回404时，会加载404.html，此时Blazor路由系统会接管并渲染对应页面。

4. 验证发布配置 #

发布完成后，进入GitHub仓库的「Settings」→「Pages」页面，确认部署来源为gh-pages分支的/root目录。

内容的提问来源于stack exchange，提问作者Patrick Szalapski