Git Action未创建gh-pages分支，Flutter Web部署GitHub Pages遇阻

问题描述 #

尝试将Flutter应用部署到GitHub Pages，本地运行正常，但部署时出现异常：

• 按方法操作后未生成gh-pages分支；
• 被迫将部署分支设为main后，访问出现404错误：

404

File not found

The site configured at this address does not contain the requested file.

If this is your site, make sure that the filename case matches the URL.
For root URLs (like http://example.com/) you must provide an index.html file.

Flutter Web产物在main分支根目录下的路径为：subdirectory_1/subdirectory_2/root_of_flutter_app/build/web/，当前使用的GitHub Actions配置文件如下：

name: Gh-Pages

on:
  push:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2 # Only works with v2
      - uses: subosito/flutter-action@v1
      - uses: bluefireteam/flutter-gh-pages@v7
        with:
          workingDir: subdirectory_1/subdirectory_2/root_of_flutter_app/
          baseHref: /repo_name/

问题排查与修复 #

1. 未生成gh-pages分支的原因及修复 #

• 权限不足：GitHub Actions默认可能只有读权限，无法推送新分支。进入仓库「Settings」→「Actions」→「General」，将「Workflow permissions」设置为「Read and write permissions」。
• 触发分支不匹配：若仓库默认分支是main，但配置中触发分支是master，推送main分支不会触发Action。需将on.push.branches改为你实际使用的分支（比如main）。
• 依赖版本过旧：actions/checkout@v2和subosito/flutter-action@v1版本较老，可能存在兼容性问题，建议升级到最新稳定版。

2. 404错误的核心原因及修复 #

将部署分支设为main时，GitHub Pages会读取分支根目录的index.html，但你的产物嵌套在子目录中，自然无法找到。正确流程是：生成gh-pages分支，然后在GitHub Pages设置中，将部署源指定为gh-pages分支的根目录。

3. 优化后的Actions配置 #

更新配置文件，确保权限、分支、依赖版本正确，同时显式添加依赖获取和构建步骤：

name: Deploy Flutter Web to GitHub Pages

on:
  push:
    branches: [ main ]  # 改为你实际的触发分支

jobs:
  build-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.x'  # 指定你项目使用的Flutter版本

      - name: Install dependencies
        working-directory: subdirectory_1/subdirectory_2/root_of_flutter_app/
        run: flutter pub get

      - name: Build web app
        working-directory: subdirectory_1/subdirectory_2/root_of_flutter_app/
        run: flutter build web --release --base-href "/repo_name/"

      - name: Deploy to gh-pages
        uses: bluefireteam/flutter-gh-pages@v7
        with:
          workingDir: subdirectory_1/subdirectory_2/root_of_flutter_app/
          baseHref: /repo_name/

最后步骤 #

1. 提交更新后的配置文件到触发分支；
2. 等待Action执行完成，确认gh-pages分支生成；
3. 进入仓库「Settings」→「Pages」，将「Source」设置为「Deploy from a branch」，选择gh-pages分支和「/ (root)」目录，保存设置。

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