GitHub Actions工作流在主分支Dart文件变更后未更新GitHub Pages

一、检查GitHub Actions工作流配置 #

常见配置错误点 #

• 构建路径未正确指定：Flutter Web默认构建输出目录为build/web，若工作流中推送的目录错误（比如写成build或其他路径），会导致gh-pages分支无有效更新内容。使用peaceiris/actions-gh-pages时，需确保配置publish_dir: build/web；若手动编写脚本，要明确将build/web下的所有文件复制到gh-pages分支的根目录。
• 代码检出不完整：使用actions/checkout时，需添加fetch-depth: 0参数拉取完整仓库历史，避免因仅拉取最新提交导致构建基于旧代码。
• 依赖与构建步骤缺失：构建前必须执行flutter pub get安装最新依赖，且使用flutter build web --release命令构建生产版本，跳过依赖安装或使用debug模式都可能导致输出旧内容。
• 推送权限不足：确认工作流使用的GITHUB_TOKEN拥有推送gh-pages分支的权限，私有仓库可能需要使用个人访问令牌（PAT）替代默认token。

针对“nothing to commit”的修复 #

若推送时提示工作树干净，大概率是构建文件未被正确同步到gh-pages分支：

1. 工作流中需先清空gh-pages分支的现有内容（可通过git rm -rf .实现，注意保留必要文件如.gitignore）；
2. 将build/web下的所有文件复制到当前目录；
3. 执行git add .、git commit -m "Deploy latest build"再推送。使用第三方action时，需确保其内部逻辑包含上述同步步骤。

二、GitHub Pages缓存强制刷新 #

若gh-pages分支已更新但站点未生效，可通过以下方式强制刷新CDN缓存：

• 手动触发重新部署：进入仓库「Settings」→「Pages」页面，在「Build and deployment」区域点击「Deploy」按钮（若可见），触发GitHub Pages重新拉取gh-pages分支内容。
• 添加静态资源版本标识：构建时通过--dart-define参数给资源加哈希或版本号，例如：

  flutter build web --release --dart-define=BUILD_VERSION=$(date +%s)
  

  或手动修改index.html中资源路径，如将main.dart.js改为main.dart.js?v=20240520，强制浏览器重新加载资源。
• 自定义域名缓存清理：若使用自定义域名且配置了第三方CDN（如Cloudflare），需在CDN控制台手动清除缓存。

三、验证关键更新步骤是否遗漏 #

• Flutter版本一致性：确保本地与GitHub Actions中使用的Flutter版本一致，可通过subosito/flutter-action指定固定版本：

  - uses: subosito/flutter-action@v2
    with:
      flutter-version: '3.13.0'
  

• gh-pages分支内容校验：本地拉取gh-pages分支，对比index.html、main.dart.js与本地构建产物的哈希值，若不一致则说明推送步骤存在问题；若一致则聚焦缓存或Pages配置。
• Pages部署源确认：在仓库「Settings」→「Pages」中，确认部署源为gh-pages分支的根目录，而非其他分支或子目录。

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