Flutter Web应用经GitHub Actions部署后项目页显示异常

问题 #

我把一个Flutter应用部署成了用户GitHub Pages（地址：sensn.github.io），之后用GitHub Actions工作流尝试部署另一个Flutter Web应用作为项目GitHub Pages（地址：sensn.github.io/particle_field）。现在两个页面都加载用户Pages上的Flutter应用，项目页没显示对应的particle_field应用，推测是缓存或配置问题，但不知道怎么修。

原因 #

• Flutter Web默认按根路径构建资源，部署到项目子路径时会错误请求根目录的用户Pages资源
• GitHub Pages缓存机制可能导致旧资源未更新
• Action构建时未配置正确的base href，导致资源加载路径错误

修复步骤 #

1. 构建时指定Base Href #

执行flutter build web命令必须加上--base-href "/particle_field/"参数，让所有资源从子路径加载，避免和根路径的用户Pages冲突。

修改Action中的构建命令：

flutter build web --release --base-href "/particle_field/"

2. 检查项目GitHub Pages设置 #

• 进入项目仓库的Settings -> Pages
• 确认部署源选择gh-pages分支，发布目录为根目录（/）
• 保存设置后等待部署完成

3. 清除缓存 #

• 访问项目页时按Ctrl + Shift + R（Windows/Linux）或Cmd + Shift + R（Mac）强制刷新，清空浏览器缓存
• 若仍有问题，可在GitHub Pages设置中重新触发部署，或删除旧的gh-pages分支后重新推送

4. 修正后的GitHub Actions配置 #

把原main.yml修改为以下内容，重点添加了base-href参数：

name: particle_field
on:
  push:
    branches:
      - main
jobs:
  build:
    name: Build Web
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          channel: 'master'
      - run: |
             cd example    
             flutter config --enable-web
             flutter pub get
             # 指定子路径的base href
             flutter build web --release --base-href "/particle_field/"
      - run: |
          cd example/build/web
          git init
          git config --global user.email "你的邮箱地址"
          git config --global user.name "你的GitHub用户名"
          git remote add origin https://${{secrets.Commit_secret}}@github.com/sensn/particle_field.git
          git checkout -b gh-pages
          git add --all
          git commit -m "update"
          git push origin gh-pages -f   

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