Flutter Web部署GitHub Pages后报错：_flutter is not defined

部署Flutter Web项目到GitHub Pages后出现以下错误：

(index):46 Uncaught ReferenceError: _flutter is not defined

执行flutter clean未解决问题，用户提供的Web构建入口文件代码如下：

<!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="$FLUTTER_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="code_snippets">
  <link rel="apple-touch-icon" href="icons/Icon-192.png">

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

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

  <script>
    // The value below is injected by flutter build, do not touch.
    var serviceWorkerVersion = null;
  </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.js加载状态
  打开浏览器开发者工具（F12）→ 网络标签，刷新页面查看flutter.js的请求状态。如果返回404，说明文件路径错误，需确认构建产物中存在该文件，且<base href>设置正确。

• 正确设置构建的--base-href参数
  GitHub Pages部署时，若仓库名非用户名.github.io，项目会部署在https://用户名.github.io/仓库名/路径下，构建时必须指定base href：

  flutter build web --base-href "/你的仓库名/"
  

  构建完成后检查index.html，确保<base href>已被替换为实际路径，而非保留$FLUTTER_BASE_HREF占位符。

• 调整脚本执行时机
  flutter.js的defer属性可能导致其在页面load事件触发后才加载完成，可修改为加载完成后再执行初始化代码：

  <script src="flutter.js" onload="initFlutter()"></script>
  <script>
    function initFlutter() {
      _flutter.loader.loadEntrypoint({
        serviceWorker: {
          serviceWorkerVersion: serviceWorkerVersion,
        }
      }).then(function (engineInitializer) {
        return engineInitializer.initializeEngine();
      }).then(function (appRunner) {
        return appRunner.runApp();
      });
    }
  </script>
  

  或直接移除defer属性，确保flutter.js在body脚本前加载完成。

• 确认部署文件完整性
  检查GitHub Pages部署的文件是否包含build/web目录下所有产物，包括flutter.js、main.dart.js、图标文件等。若使用GitHub Actions部署，需确认配置文件正确复制了全部构建文件。

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