Flutter Web项目无法部署到GitHub Pages求助

1. 正确配置Flutter Web构建参数 #

因为你期望访问路径为https://packruble.github.io/weather_animation/weathunits_configurator/，构建时必须指定匹配的--base-href参数，否则资源加载会出现404错误导致空白页。

进入项目目录example/weathunits_configurator，执行构建命令：

flutter clean
flutter build web --base-href "/weather_animation/weathunits_configurator/"

flutter clean用于清除旧构建缓存，确保base-href配置生效。构建完成后，检查build/web/index.html中的<base>标签，确认内容为<base href="/weather_animation/weathunits_configurator/">。

2. 调整GitHub Actions工作流配置 #

使用稳定性较高的peaceiris/actions-gh-pages Action，将构建产物部署到gh-pages分支的weathunits_configurator目录下。完整工作流示例如下：

name: Deploy Flutter Web to GitHub Pages

on:
  push:
    branches: [ main ] # 替换成你的主分支名称

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: 'stable'
          
      - name: Install dependencies
        working-directory: example/weathunits_configurator
        run: flutter pub get
        
      - name: Build web app
        working-directory: example/weathunits_configurator
        run: flutter build web --base-href "/weather_animation/weathunits_configurator/"
        
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: example/weathunits_configurator/build/web
          publish_branch: gh-pages
          destination_dir: weathunits_configurator # 将构建产物放到gh-pages分支的该目录下

3. 配置GitHub Pages仓库设置 #

1. 打开weather_animation仓库，进入Settings > Pages
2. 在Build and deployment区域：
   • 选择Deploy from a branch
   • 分支选择gh-pages，目录选择**/(root)**
3. 点击Save保存设置

4. 验证部署结果 #

1. 推送代码触发工作流，等待部署完成
2. 访问https://packruble.github.io/weather_animation/weathunits_configurator/，强制刷新浏览器（Ctrl+F5）清除缓存
3. 打开浏览器控制台排查问题：
   • 若仍有404错误，确认gh-pages分支下是否存在weathunits_configurator目录，且目录内包含所有构建产物（index.html、main.dart.js、assets文件夹等）
   • 检查base-href是否与实际访问路径完全匹配

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