Flutter Web打包上传至GitHub Pages后页面白屏报错该如何解决？

Flutter Web构建产物上传到GitHub Pages后页面全白，控制台报错如下：

Uncaught (in promise) TypeError: Failed to register a ServiceWorker for scope ('https://adamtechnologynl.github.io/') with script ('https://adamtechnologynl.github.io/flutter_service_worker.js?v=2470069411'): A bad HTTP response code (404) was received when fetching the script.
manifest.json:1 Failed to load resource: the server responded with a status of 404 ()
manifest.json:1 Manifest: Line: 1, column: 1, Syntax error.
manifest.json:1 Failed to load resource: the server responded with a status of 404 ()
(index):88 Failed to load app from service worker. Falling back to plain <script> tag.
(anonymous) @ (index):88
(index):47 GET https://adamtechnologynl.github.io/main.dart.js net::ERR_ABORTED 404
loadMainDartJs @ (index):47
(anonymous) @ (index):91

所有报错均指向静态资源404，核心原因是Flutter Web默认构建配置的资源根路径为/，和GitHub Pages的实际部署路径不匹配：

• 如果是部署到GitHub Pages项目站点（即访问路径为https://<用户名>.github.io/<仓库名>/），Flutter默认会从根域名请求资源，找不到对应文件
• 如果是部署到根站点（即https://<用户名>.github.io/），则是上传的文件目录层级错误，没有把build/web下的所有文件直接放到仓库根目录

• 部署项目站点时，构建时添加--base-href参数指定子路径，假设仓库名为flutter_demo，构建命令为：
  flutter build web --release --base-href "/flutter_demo/"
  注意路径前后必须加斜杠
• 部署根站点时，确认上传的是build/web目录下的所有文件直接到仓库根目录，不要嵌套web文件夹
• 不需要PWA能力的场景下，构建时添加参数--pwa-strategy=none可取消ServiceWorker相关逻辑，避免对应报错
• 修复后重新上传构建产物，用浏览器隐私模式访问验证，避免旧缓存干扰

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