Flutter-Web从0到部署上线(实践+埋坑)

随着 Flutter Web 趋于稳定，用 Flutter 实现的 App 可以低成本的被打包成 web 版了，毕竟对于用户来说使用浏览器打开个网页比下载个 App 成本低多了。这种情况下我们就可以利用 Flutter 的跨端优势，节约很多人力资源，避免去重新开发一套 web 端了。

好的既然有了使用场景，我们就好好来走一下 Flutter Web 是怎么开发部署上线的流程。

我们使用 Android Studio 作为IDE，以 Flutter 3.10.5 版本为基础创建一个 Flutter Web 工程。 创建一个 New Flutter Project，在选择 Platforms 的时候只勾选 Web，然后直接 Create。

然后我们发现在工程目录里多了个 web 的文件夹：

如果你是为现有的 Flutter 工程添加 Web 的支持，只需在项目根目录运行如下命令即可：

flutter create --platforms=web .

项目创建好了，如果想要 run 起来只需选择 chrome 浏览器，点击 run 就行了：

然后我们就可以在浏览器看到运行结果了，当然我们也可以打开开发者模式方便查看与调试：

这部分跑通后，非常恭喜你可以愉快的用 Flutter 开发网页了，接下来我们实现一个业务需求：做一个网页搜索功能。

业务功能上的开发实现我就不做赘述了，可以告诉做过 Flutter 开发的同学，没什么不同，基础配置/网络模块/数据共享/路由等该怎么封装就怎么封装，我也不过是直接拿了之前客户端 Flutter 工程相应模块的代码，稍作修改而已。UI 上的开发也是该怎么布局怎么布局，业务的开发体验上和客户端使用 Flutter 没什么不同。

在 web 端开发的时候我们通常会使用 window 对象进行一些操作。window 对象代表一个浏览器窗口或一个框架。常用的 event 监听，打开网页等操作都需要 window 对象。Flutter 自带的 dart:html 封装了 window，我们可以通过它来实现获取 window 的属性或对 window 进行操作，比如：

//打开网页
window.open("http://www.baidu.com","");

//监听event
window.addEventListener("mousedown", (event) => {
     //do something
});

另外 window 也可以帮助我们区分运行环境。

客户端通常需要区分的是 Android 和 iOS 这两个不同的运行环境，而web端是需要通过 UA 来区分不同的浏览器环境的，不同环境下的UI/逻辑等会有差别。在国内，我们最常需要区分 PC 端/移动端/ Android 端/ iOS 端/微信网页/微信小程序这几个。那么我们可以定义一个类，利用 window.navigator.userAgent 去区分这些环境：

import 'dart:html';

class DeviceUtil {
  static final DeviceUtil _instance = DeviceUtil._private();

  static DeviceUtil get() => _instance;

  factory DeviceUtil() => _instance;

  late String ua;

  DeviceUtil._private() {
    ua = window.navigator.userAgent;
  }

  //移动端
  isMobile() {
    return RegExp(
        r'phone|pad|pod|iPhone|iPod|ios|iPad|Android|Mobile|BlackBerry|IEMobile|MQQBrowser|JUC|Fennec|wOSBrowser|BrowserNG|WebOS|Symbian|Windows Phone')
        .hasMatch(ua);
  }

  //iOS端
  isIos() {
    return RegExp(r'\(i[^;]+;( U;)? CPU.+Mac OS X').hasMatch(ua);
  }

  //Android端
  isAndroid() {
    var isAndroid = ua.contains("Android") || ua.contains("Adr");
    return isAndroid;
  }

  //微信环境
  isWechat() {
    return ua.contains("MicroMessenger");
  }

  //微信小程序环境
  isMiniprogram() {
    if (ua.contains("micromessenger")) {
      //微信环境下
      if (ua.contains("miniprogram")) {
        //小程序;
        return true;
      }
    }
    return false;
  }
}

 同客户端一样，web 端也需要区分开发/测试/生产环境。同客户端的方式一样，我们还是可以通过配置不同的入口文件来实现环境的区分。如：

void main() {
  AppConfig.init(ConfigType.dev);
  root_main.main();
}

void main() {
  AppConfig.init(ConfigType.test);
  root_main.main();
}

void main() {
  AppConfig.init(ConfigType.online);
  root_main.main();
}

在 AppConfig.init() 就可以根据不同的环境做不同的配置了。 

关于数据共享/网络/UI/动画等库就不做介绍了，因为这些库和平台不相关，用各自熟悉的就好，下面是来介绍一下为了实现一些浏览器相关功能需要用到的插件。

好了，到此为止，我觉着使用 Flutter 开发一个常规的 web 业务已经不成问题了。接下来我们探讨一下如何调试呢？

跑通后应该如何调试呢？我们先来说明一下 PC 端的调试方式。

如果熟悉浏览器开发者模式，可直接使用浏览器进行调试，打 log 或 debug 都是没问题的，也可以看到源码，可以抓包：

当然客户端同学可能不熟悉浏览器开发者模式，也没关系，利用 Android Studio，之前在客户端写 Flutter 怎么调试，现在写 web 端依旧可以怎么调试。 介绍完 PC 端的调试，那么在移动端应该如何调试呢？

我们依旧可以用 PC 上的浏览器，红色箭头指向的位置可以切换至移动端模拟器设备，可以选择机型。但更多的时候，我们希望可以真机调试。熟悉 vue 框架的同学都知道，在本地调试的时候，会给出两个地址，如下图所示：

我们可以在手机浏览器上输入 Network 显示的 ip 地址进行调试。在 Flutter 环境上并没有提供相应的 ip 地址，我们可以通过 flutter 的本地打包命令指定一个地址，如下所示：

flutter run -d chrome --web-hostname 10.2.136.130 -t lib/main_test.dart --web-port 8080

指定本机的 ip 地址和端口号，然后在手机浏览器上输入：

10.2.136.130:8080

之后我们如何看到调试信息呢？由于使用 Chrome 浏览器需要科学上网，在此我们以 iPhone 的 Safari 浏览器+ PC 端的 Safari 浏览器为例：

如何进行调试我们已经清楚了，假设我们已经开发完成了，如何打包部署上线呢？

flutter build web

即可。但这样显然是不够的，因为我们需要区分环境来打不通的包。 在上一章节我们配置了不同的入口文件，我们以 dev 环境为例，其入口文件是 main_dev，那么我们的打包命令就变成了：

flutter build web -t lib/main_dev.dart

这行命令执行完成后，报错了，报错信息如下：

这是个图标数据加载问题，我们加上--no-tree-shake-icons即可。执行命令如下：

flutter build web -t lib/main_dev.dart --no-tree-shake-icons

然后我们就会在项目根目录的 build 文件夹下找到 web 这个文件夹，对应的就是 web 前端打出来的 dist 文件夹。包含了以下文件：

编译产物有了，那么如何部署呢？ 

官方给了如下的部署方式： 

https://flutter.cn/docs/deployment/web#deploying-to-the-web 

看了官方文档后我发现，这三种部署方式并不适用于我们的项目。由于 CDN 具有提高网站性能和用户体验，减轻原始服务器的负载等优势，目前我们团队已经搭建了 CDN 部署平台。既然如此，我们的部署方案也需要往这方面靠。CDN 部署配置主要要解决的问题就是各种资源的路径问题。

（1）修改index.html的CDN资源路径

我先来简单说明一下 FlutterWeb 编译产物，如下图所示：

assets 包含了我们所有的静态资源文件：包括图片，字体文件等。 最重要是 flutter.js 和 main.dart.js 这两个文件。其中 flutter.js 为入口的 js 文件，我们可以打开 web 目录下 index.html：

<!DOCTYPE html>
<html>
<head>
  
  <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.">

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

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

  <title>flutter_web</title>
  <link rel="manifest" href="manifest.json">
  <script>
    // The value below is injected by flutter build, do not touch.
    var serviceWorkerVersion = null;
  </script>
  </script>-->
  <script src="flutter.js" defer></script>
</head>
<body>
  <script>
    window.addEventListener('load', function(ev) {
      // Download main.dart.js
      _flutter.loader.loadEntrypoint({
        serviceWorker: {
          serviceWorkerVersion: serviceWorkerVersion,
        },
        onEntrypointLoaded: function(engineInitializer) {
          engineInitializer.initializeEngine({
        }).then(function(appRunner) {
            appRunner.runApp();
          });
        }
      });
    });
  </script>
</body>
</html>

看到 <script src="flutter.js" defer></script> 这行。而 main.dart.js 是我们的 dart 业务代码被编译成的 js 文件。flutter.js 会加载 main.dart.js 和其它文件。默认情况下，flutter.js 会加载各个文件，包括资源文件( assets )都使用的是相对路径。首先就是通过 loadEntrypoint () 方法加载 main.dart.js 这个文件：

//flutter.js
async loadEntrypoint(options) {
      const { entrypointUrl = `${baseUri}main.dart.js`, onEntrypointLoaded } =
        options || {};

      return this._loadEntrypoint(entrypointUrl, onEntrypointLoaded);
    }

但我们发现貌似 entrypointUrl 是可以自己传递的，于是我们从官网文档里找到了 自定义web应用初始化 的链接： https://flutter.cn/docs/platform-integration/web/initialization 有如下的参数可传：

其中 loadEntrypoint() 方法可以传递 entrypointUrl 参数来指定 main.dart.js 的路径。而 initializeEngine() 方法可以通过传递 assetBase 参数来指定 CDN 资源路径。这么看来我们完全可以通过将这两个参数设置为绝对路径来解决 main.dart.js 的加载与 CDN 资源路径的问题。需要注意的是 initializeEngine() 方法是 Flutter3.7.0 开始才支持的。 我们改一下 index.html：

    window.addEventListener('load', function(ev) {
      // Download main.dart.js
      _flutter.loader.loadEntrypoint({
        serviceWorker: {
          serviceWorkerVersion: serviceWorkerVersion,
        },
        entrypointUrl: "YOUR_CDN_ABSOLUTE_PATH/main.dart.js",
        onEntrypointLoaded: function(engineInitializer) {
          engineInitializer.initializeEngine({
          assetBase: "YOUR_CDN_ABSOLUTE_PATH"
        }).then(function(appRunner) {
            appRunner.runApp();
          });
        }
      });
    });

我们再打个包，还是会报错，找不到 flutter.js，还是因为路径问题。处理方式更简单了，直接在 index.html 里配置成绝对路径即可。另外我们发现 Icon-192.png，favicon.png，manifest.json 这几个文件也是相对路径，那么我们一次性都改成绝对路径：

<head>
  
  <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.">

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

  
  <link rel="icon" type="image/png" href="YOUR_CDN_ABSOLUTE_PATH/favicon.png"/>

  <title>flutter_web</title>
  <link rel="manifest" href="YOUR_CDN_ABSOLUTE_PATH/manifest.json">
  <script>
    // The value below is injected by flutter build, do not touch.
    var serviceWorkerVersion = null;
  </script>
  
  <script src="YOUR_CDN_ABSOLUTE_PATH/flutter.js" defer></script>
</head>

再打个包上传到 CDN，嗯一切都正常了～ 到这里看上去都完美了，但突然想起来不对啊，我们是区分开发/测试/生产环境的，相应的 CDN 路径也是不同的。修改 index.html 的方式指定的都是绝对路径，不符合我们的需求啊。既然如此我们再改改。

• 1.首先根据当前域名 document.location.origin 的不同，区分不同环境下的 CDN 地址：YOUR_CDN_HOST。默认是是空，即本地调试情况，不需要配置 CDN 地址。

• 2.为 flutter.js，icons/Icon-192.png，favicon.png，manifest.json 指定 id，并通过 document.getElementById() 方法找到相应元素，为他们配置 CDN 的绝对路径。

• 3.如上一章节所示，配置 entrypointUrl 与 assetBase。

• 1.Dart 中 int 和 JS 中 Number 的转换问题。

• 2.导入特定平台依赖项。

• 3.路由问题。

• 4. iPhone 手机 Safari 浏览器的侧滑返回问题。

• 5. lottie 问题。

• 6.跨域问题。

• 1.前往 flutter\bin\cache 文件夹，删除 flutter_tools.stamp 文件。

• 2.前往 flutter\packages\flutter_tools\lib\src\web，打开 chrome.dart 文件。

• 3.找到 '--disable-extensions' 这部分，在最下面添加 '--disable-web-security'，重新 build 即可。