Flutter Web部署GitHub Pages后页面空白问题求助

问题描述 #

我用Flutter开发了一个Web应用并部署到GitHub Pages。首次发布时页面功能正常，所有内容都能正常显示，但进行一些更新并重新部署后，网页现在显示空白，仅能看到默认标题和网站图标。

本地在Android Studio中直接通过Chrome运行时页面显示正常，只有部署到GitHub Pages时才会出现空白问题。

我的部署流程：

• 使用flutter build web命令打包，也尝试过flutter build web --release等其他组合命令
• 将Android Studio中build > web文件夹的内容上传到GitHub主分支完成部署

已尝试的解决方案 #

试过类似问题里的各种修改或移除相关代码的方案：

• 移除<base href=...>
• 设置<base href="/">
• 设置<base href="./">
• 设置<base href="/homepage/">
• 删除并重建整个GitHub仓库
• 使用flutter build web --web-renderer html命令打包
• 移除应用中所有复杂代码，仅保留一个横幅组件

我查遍了StackOverflow和GitHub上的相关问题，但所有方案都无效，求技术帮助！

我的index.html文件 #

<!DOCTYPE html>
<html>
<head>
  <!--
    If you are serving your web app in a path other than the root, change the
    href value below to reflect the base path you are serving from.
    The path provided below has to start and end with a slash "/" in order for
    it to work correctly.
    For more details:
    * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base
    This is a placeholder for base href that will be replaced by the value of
    the `--base-href` argument provided to `flutter build`.
  -->

  <!--<base href="/">-->

  <meta charset="UTF-8">
  <meta content="IE=Edge" http-equiv="X-UA-Compatible">
  <meta name="description" content="A new Flutter project.">

  <!-- iOS meta tags & icons -->
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="black">
  <meta name="apple-mobile-web-app-title" content="sports_app">
  <link rel="apple-touch-icon" href="icons/Icon-192.png">

  <!-- Favicon -->
  <link rel="icon" type="image/png" href="favicon.png"/>

  <title>sports_app</title>
  <link rel="manifest" href="manifest.json">

  <script>
    // The value below is injected by flutter build, do not touch.
    var serviceWorkerVersion = '1014210939';
  </script>
  <!-- This script adds the flutter initialization JS code -->
  <script src="flutter.js" defer></script>
</head>
<body>
  <script>
    window.addEventListener('load', function(ev) {
      // Download main.dart.js
      _flutter.loader.loadEntrypoint({
        serviceWorker: {
          serviceWorkerVersion: serviceWorkerVersion,
        }
      }).then(function(engineInitializer) {
        return engineInitializer.initializeEngine();
      }).then(function(appRunner) {
        return appRunner.runApp();
      });
    });
  </script>
</body>
</html>

Flutter Doctor输出 #

[✓] Flutter (Channel master, 3.5.0-10.0.pre.40, on macOS 11.3.1 20E241 darwin-arm64 (Rosetta), locale en-US)
    • Flutter version 3.5.0-10.0.pre.40 on channel master at /Users/mikebeazer/Developer/flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 20c4b6c53e (3 hours ago), 2022-10-23 15:22:39 -0400
    • Engine revision f62df69205
    • Dart version 2.19.0 (build 2.19.0-330.0.dev)
    • DevTools version 2.18.0

[✓] Android toolchain - develop for Android devices (Android SDK version 32.0.0)
    • Android SDK at /Users/mikebeazer/Library/Android/sdk
    • Platform android-31, build-tools 32.0.0
    • Java binary at: /Applications/Android Studio.app/Contents/jre/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment (build 11.0.10+0-b96-7281165)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 13.2.1)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 13C100
    • CocoaPods version 1.11.3

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio
    • Android Studio at /Applications/Android Studio Preview.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 11.0.10+0-b96-7281165)

[✓] Android Studio (version 2020.3)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 11.0.10+0-b96-7281165)

[✓] Connected device (2 available)
    • macOS (desktop) • macos  • darwin-arm64   • macOS 11.3.1 20E241 darwin-arm64 (Rosetta)
    • Chrome (web)    • chrome • web-javascript • Google Chrome 106.0.5249.119

[✓] HTTP Host Availability
    • All required HTTP hosts are available

• No issues found!

解决方案 #

1. 通过build参数正确注入base href
   不要手动注释或修改index.html里的<base href>占位符，打包时用--base-href参数指定GitHub Pages的实际路径。如果你的页面地址是https://<用户名>.github.io/<仓库名>/，打包命令应为：

flutter build web --release --base-href "/<仓库名>/"

打包后Flutter会自动替换index.html中的base href，无需手动修改。

2. 确认GitHub Pages部署分支
   GitHub Pages默认支持gh-pages分支，或主分支的/docs文件夹。如果直接上传到主分支根目录，需在仓库设置中把GitHub Pages的源改为“主分支”。

3. 清除缓存和Service Worker
   部署后浏览器可能缓存旧资源，按Ctrl+Shift+R强制刷新页面；或在Chrome开发者工具的Application面板中找到Service Workers，点击Unregister清除旧的服务 worker。

4. 检查资源加载状态
   打开浏览器开发者工具的Network面板，刷新页面查看main.dart.js、flutter.js等资源的请求状态。若返回404，说明路径错误，需确认base href设置正确且所有资源已完整上传到GitHub。

5. 切换到Flutter稳定版
   当前使用的是master开发分支，可能存在不稳定bug。切换到稳定版后重新打包：

flutter channel stable
flutter upgrade

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