Blazor WASM部署至GitHub Pages后资源加载404问题求助

核心问题分析 #

你的工作流能成功部署，但资源加载404，本质是静态资源的路径与GitHub Pages的实际访问路径不匹配。虽然你修改了index.html的<base href>，但可能存在以下问题：

• 手动修改的base href在发布时被覆盖
• 发布时未正确传递GitHub Pages的子路径参数
• 部署action版本过旧导致路径处理异常

具体解决步骤 #

1. 修正发布命令，自动设置BasePath #

Blazor发布时可以通过BasePath参数自动修改index.html的<base href>，无需手动修改文件，避免本地开发与部署的冲突。把你的发布步骤命令替换为：

cd App.Client; dotnet publish -c:Release -p:GHPages=true -p:BasePath=/你的仓库名称/ -o ../dist/Web --nologo

注意：你的仓库名称要和GitHub仓库的实际名称完全一致（区分大小写，建议小写），比如仓库名为BlazorWasmApp，则写/blazorwasmapp/。

2. 升级部署Action版本 #

你使用的JamesIves/github-pages-deploy-action@3.7.1版本过旧，部分参数和路径处理逻辑已更新。替换为最新稳定版（当前为v4.6.0），并修正参数名：

- name: Commit wwwroot to GitHub Pages
  uses: JamesIves/github-pages-deploy-action@v4.6.0
  with:
    token: ${{ secrets.MY_TOKEN }}
    branch: gh-pages
    folder: dist/Web/wwwroot
    clean: true # 可选：清理gh-pages分支的旧文件，避免残留

3. （可选）在项目csproj中配置条件BasePath #

如果不想每次发布都手动写BasePath参数，可以在App.Client.csproj中添加条件配置，当GHPages=true时自动应用路径：

<PropertyGroup Condition="'$(GHPages)' == 'true'">
  <BasePath>/你的仓库名称/</BasePath>
</PropertyGroup>

这样发布命令只需保留-p:GHPages=true即可。

4. 验证GitHub Pages设置 #

进入仓库的「Settings」→「Pages」：

• 确认「Source」选择的是gh-pages分支，「Folder」为/(root)
• 查看生成的访问域名，确保路径是https://用户名.github.io/仓库名称/，与你设置的BasePath一致

5. 检查gh-pages分支文件结构 #

部署完成后，查看gh-pages分支的根目录，应包含以下内容：

• _framework文件夹（Blazor核心文件）
• 各种css/js文件（如MudBlazor.min.css、blazor.webassembly.js）
• index.html

如果这些文件嵌套在某个子文件夹里，说明部署的folder参数有误，确认dist/Web/wwwroot是正确的发布输出目录。

验证 #

重新触发工作流（可以用「Workflow dispatch」手动触发），部署完成后访问GitHub Pages域名，检查控制台是否还有404错误。

内容的提问来源于stack exchange，提问作者I NN_