Flutter Web 混合开发的真实体验

为什么选这条路

做「雷达快传」的时候，需求很明确：iOS / Android 双端都要跑，部分页面还得在 WebView 里嵌入 Web 内容。Flutter 天然适合这个场景——一套 Dart 代码，iOS、Android、Web 三端共享逻辑层。

但 Web 混合开发不是把 flutter build web 跑一下就完事了。实际项目里会遇到一堆”文档没写但你会踩”的问题。

架构分层

┌─────────────────────────────────┐
│         Flutter UI 层            │
│   (Material / 自定义组件)        │
├─────────────────────────────────┤
│      共享业务逻辑层 (Dart)        │
│   网络请求 / 状态管理 / 路由      │
├──────────────┬──────────────────┤
│  Native 桥接  │   WebView 桥接    │
│  (MethodCh)  │  (JS Bridge)     │
└──────────────┴──────────────────┘

核心思路：一套业务逻辑 + 平台差异化 UI 适配，不做”一套代码原样跑三端”的白日梦。

踩过的坑

1. WebView 里的 JS 通信

Flutter Web 端用 webview_flutter 不现实——它依赖原生 WebView，Web 平台根本不存在这个概念。解决方案：

移动端：webview_flutter + MethodChannel 走原生桥接
Web 端：直接用 dart:html 的 IFrameElement，通过 postMessage 通信

// Web 端 JS 通信封装
import 'dart:html' as html;

class WebJsBridge {
  final html.IFrameElement _iframe;
  
  void postMessage(Map<String, dynamic> data) {
    _iframe.contentWindow?.postMessage(data, '*');
  }
  
  void onMessage(void Function(Map<String, dynamic>) handler) {
    html.window.onMessage.listen((event) {
      handler(event.data);
    });
  }
}

关键点：Android/iOS 和 Web 的通信通道完全独立实现，但接口保持一致，上层业务层无感知。

2. Platform Channel 的条件编译

用了 dart.library.io 和 dart.library.html 做平台判断：

1
2
3

import 'bridge_stub.dart'
    if (dart.library.io) 'bridge_mobile.dart'
    if (dart.library.html) 'bridge_web.dart';

编译时 Dart 会自动选择对应平台的实现，零运行时开销。

3. Web 端性能优化

Flutter Web 的 CanvasKit 渲染器很重，首屏加载慢。实际方案：

开发阶段用 --web-renderer canvaskit（保证渲染一致性）
生产部署切 --web-renderer auto（移动端自动降级 HTML 渲染器）
图片全部走 CDN + WebP 格式
路由懒加载，deferred as 延迟加载非首屏模块

4. 文件下载的兼容处理

移动端用 dio + 原生存储权限，Web 端得用浏览器的下载机制：

void downloadFile(String url, String filename) {
  if (kIsWeb) {
    final anchor = html.AnchorElement(href: url)
      ..setAttribute('download', filename)
      ..click();
  } else {
    // 走原生 dio 下载 + 文件权限处理
  }
}