Flutter Web部署Firebase生产环境报_flutter is undefined错误

问题表现 #

Flutter Web项目本地Debug调试模式运行无异常，部署到Firebase托管后页面白屏，浏览器控制台输出以下报错：

Uncaught SyntaxError: Unexpected token '<' (at flutter.js:1:1)
(index):50 Uncaught ReferenceError: _flutter is not defined
    at (index):50:7

当前使用的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.

    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="Trading made easy">
  <meta name="google-signin-client_id"
    content="xxx.apps.googleusercontent.com">

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

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

  <title>Torn Market</title>
  <link rel="manifest" href="manifest.json">
  <!-- <script>self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;</script> -->
  <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>

根因说明 #

两个报错是连锁反应：

1. 第一个语法错误的本质是浏览器请求flutter.js文件时，没有拿到预期的JS脚本内容，反而拿到了HTML格式的响应（通常是404错误页、首页重定向内容），HTML内容开头的<字符不符合JS语法规范，直接抛出解析错误。
2. 第二个_flutter is not defined是连带错误：flutter.js加载失败后，全局作用域下不会注入_flutter对象，后续初始化代码调用该对象时直接抛出引用错误。

排查步骤与解决方案 #

按优先级从高到低逐一排查：

• 检查构建命令的base-href参数配置
  • 若项目部署在Firebase托管的根域名下，构建时必须指定--base-href="/"，完整构建命令为flutter build web --release --base-href="/"
  • 若项目部署在子路径下（例如https://你的域名/tornmarket/），base-href参数必须和子路径完全匹配，开头结尾都要带斜杠，例如--base-href="/tornmarket/"
  • 构建完成后打开build/web/index.html文件，确认<base href>的占位符$FLUTTER_BASE_HREF已经被替换为你设置的实际路径，没有保留占位符文本。
• 检查Firebase托管配置文件firebase.json
  • 确认hosting.public字段指向Flutter构建输出的build/web目录，不要错指向项目根目录、web源码目录或其他路径。
  • 不要给.js、.css等静态资源单独配置错误的重写规则。Firebase托管默认优先匹配public目录下的静态文件，只有路径不存在时才会走重写规则返回index.html，只要public目录配置正确，不会出现静态资源返回HTML的问题。可参考以下最小可用配置：

{
  "hosting": {
    "public": "build/web",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

• 部署后验证资源响应
  • 部署完成后打开浏览器开发者工具的Network面板，强制刷新页面，找到flutter.js的请求记录：
    • 确认响应状态码为200
    • 确认响应内容是JavaScript代码，不是以<!DOCTYPE html>开头的HTML内容
  • 如果flutter.js的请求路径和预期不符、返回404或HTML内容，回到前两步重新检查base-href和public目录配置。
• 清理缓存重试
  • 强制刷新浏览器（Windows按Ctrl+Shift+R，Mac按Cmd+Shift+R）排除浏览器静态缓存影响
  • 若之前部署过错误版本，打开开发者工具的Application面板，注销旧的Service Worker、清除站点存储数据后再重试。

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