Sunqy 文档库

主题

25 · Flutter Web 与桌面端 ​

目标：把同一套 Flutter 代码跑到浏览器和桌面（Windows/macOS/Linux），搞清能力边界、坑点、以及你的前端经验哪些能用、哪些会误导你。

💡 本篇对前端转 Flutter尤其重要：Web 端是你经验最可迁移的地方，但也最容易因为"以为跟写网页一样"而踩坑。

开篇：前端概念对照 ​

前端Flutter Web差异与注意
DOM 元素树无 DOM（Canvas 绘制或编译成 HTML/CSS）浏览器 DevTools 的元素面板基本没用
CSS 选择器/样式无 CSS，全靠 Widget 样式不能用外部样式表
div/span/p 语义标签默认无语义标签需要 SEO/无障碍时手动加 Semantics
响应式（媒体查询）LayoutBuilder / MediaQuery逻辑一致，写法不同
路由（History API）GoRouter（path 或 hash 模式）服务器需配置 fallback
fetchdio / http一样受 CORS 限制
localStorageshared_preferences（底层即 localStorage）见 18 篇
SEO默认极弱（Canvas 渲染无文本）需要额外方案
打包产物index.html + main.dart.js + 资源首屏加载是大问题

一句话心智模型：Flutter Web 不是"另一种前端框架"，它是把 App 的渲染引擎搬进浏览器。所以 App 的能力基本都在，但 Web 的生态（SEO、DOM 操作、CSS 生态）基本都不在。

一、先判断：要不要上 Web / 桌面端 ​

场景适合度说明
内部管理后台 / B 端工具✅ 非常适合不需要 SEO，交互复杂，正好发挥 Flutter 优势
已有 App，想复用代码做个 Web 版✅ 适合复用率高，但需处理响应式布局
营销页 / 内容站 / 博客❌ 不适合SEO 与首屏是硬伤，用传统 Web 技术
需要嵌入现有网页的局部组件⚠️ 谨慎可用 flutter.js 嵌入，但体积与加载是问题
桌面工具（内部工具、配置器）✅ 适合Flutter 桌面端成熟度不错
重原生能力的桌面应用⚠️ 谨慎需写插件，生态不如 Electron 成熟

决策要点：Flutter 的多平台价值在"一套代码覆盖多端"，而不是"在某个端做得比原生 Web/桌面更好"。如果你只需要 Web 端，用 Web 技术栈更合适。

二、Flutter Web：两种渲染器 ​

bash
flutter build web --web-renderer html        # HTML 渲染器
flutter build web --web-renderer canvaskit   # CanvasKit 渲染器
flutter build web --web-renderer auto        # 默认：桌面用 canvaskit，移动浏览器用 html
维度HTML 渲染器CanvasKit 渲染器
原理编译成真实 DOM + CSSSkia 编译成 WASM，画在 Canvas 上
包体小（~几百 KB）大（+1.5~2MB WASM）
渲染一致性与各端有差异与各端高度一致
性能（复杂绘制）一般更好
文本可选中/复制✅ 原生支持需要额外处理
适用场景内容型、对体积敏感图形密集、要求多端一致

选型：默认 auto 即可。追求多端视觉一致或复杂动画 → canvaskit；追求加载速度 → html。

三、Web 端必踩的六个坑 ​

3.1 CORS（最容易卡住的地方） ​

与前端完全一样：浏览器同源策略不会因为你是 Flutter 就放过你。

  • 现象：本地 flutter run -d chrome 正常，部署后接口全挂；或只有预检 OPTIONS 失败
  • 解法：服务端配置 CORS 响应头（Access-Control-Allow-Origin 等），前端无解
  • 开发期应急：用 flutter run -d chrome --web-browser-flag "--disable-web-security"（仅本地）

3.2 路由模式与刷新 404 ​

模式URL 形态服务器要求
Hash（默认）example.com/#/order/123无要求（不会 404）
Pathexample.com/order/123必须配置 fallback：所有未匹配路径返回 index.html
dart
// GoRouter 切换（见 13 篇）
GoRouter(routerConfig: ..., );
// 用 path 模式需设置 UrlPathStrategy（新版 GoRouter 默认 path）

Nginx 配置：

nginx
location / {
    try_files $uri $uri/ /index.html;
}

忘了配 fallback 的表现：首页正常，刷新子页面或直接访问深链接就 404——与前端 SPA 部署一模一样。

3.3 首屏加载慢（体积问题） ​

Flutter Web 的 main.dart.js 动辄 1~3MB，首屏白屏明显。优化手段（按性价比）：

手段做法收益
加 loading 占位在 web/index.html 里写加载动画，Flutter 就绪后替换体感提升最大，成本最低
延迟加载库deferred as 分包（Dart 的延迟导入）首屏 JS 变小
--web-renderer html换渲染器省 1.5MB+
资源压缩图片用 webp、字体子集化中等
开启 gzip/brotli服务器配置明显（文本压缩率高）
html
<!-- web/index.html：Flutter 加载前的占位 -->
<div id="loading">
  <style>#loading{display:flex;height:100vh;align-items:center;justify-content:center}</style>
  <div class="spinner">加载中…</div>
</div>
<script>
  window.addEventListener('load', function () {
    document.getElementById('loading')?.remove();
  });
</script>

3.4 SEO 基本没有 ​

CanvasKit 渲染时页面里没有可选中的文本，搜索引擎抓不到内容。

  • 需要 SEO → 用 html 渲染器 + 手动添加 Semantics；或干脆别用 Flutter 做
  • 折中方案：为关键页面单独提供服务端渲染的静态页（landing page 用 Web 技术，应用主体用 Flutter）

3.5 dart:io 不可用 ​

Web 平台没有文件系统和 socket：

dart
import 'dart:io';        // ❌ Web 上编译失败
if (Platform.isAndroid)  // ❌ 同样不行

// ✅ 正确做法
import 'package:flutter/foundation.dart' show kIsWeb;
if (kIsWeb) { /* Web 分支 */ } else { /* 原生分支 */ }

需要跨平台的 IO 能力，用 universal_io 等抽象包，或按平台条件导入：

dart
// 条件导入：Web 与原生用不同实现
export 'src/io_stub.dart' if (dart.library.io) 'src/io_native.dart';

3.6 字体与文本 ​

  • 中文字体文件很大（数 MB），Web 上会拖慢加载 → 字体子集化（只保留用到的字）
  • CanvasKit 模式下自定义字体需要额外声明，否则回退到默认字体
  • 文本选中/复制：CanvasKit 模式需要 SelectableText 才可选

四、桌面端（Windows / macOS / Linux） ​

4.1 启用与运行 ​

bash
flutter config --enable-windows-desktop      # 各平台分别启用
flutter config --enable-macos-desktop
flutter config --enable-linux-desktop

flutter devices                               # 确认设备已识别
flutter run -d windows
flutter build windows --release               # 产物在 build/windows/runner/Release

4.2 桌面端特有要点 ​

关注点说明常用方案
窗口管理尺寸、位置、最小化、无边框window_manager
菜单栏 / 托盘顶部菜单、系统托盘图标tray_manager + menu_base
键盘鼠标右键菜单、快捷键、悬停Focus/Shortcuts/MouseRegion
文件系统读写、文件选择框file_picker + dart:io
多窗口打开子窗口desktop_multi_window
打包分发安装包制作Windows: msix/Inno Setup；macOS: 需签名公证；Linux: deb/rpm/AppImage

4.3 桌面端与移动端的布局差异 ​

桌面端必须处理：

dart
// 响应式布局（同 Web）
LayoutBuilder(builder: (context, c) {
  if (c.maxWidth >= 1100) return const WideLayout();    // 三栏
  if (c.maxWidth >= 650)  return const MediumLayout();  // 两栏
  return const NarrowLayout();                          // 单栏
})

// 桌面端交互差异
- 鼠标悬停态（移动端没有）
- 右键上下文菜单
- 键盘导航（Tab 焦点、Enter 确认）
- 窗口缩放时的重新布局（不是屏幕旋转）

五、多平台代码组织 ​

5.1 平台分支的三种写法 ​

dart
// ① kIsWeb 判断（最常用）
import 'package:flutter/foundation.dart';
if (kIsWeb) return WebView(); else return NativeView();

// ② ThemeData.platform / defaultTargetPlatform
import 'package:flutter/foundation.dart' show defaultTargetPlatform, TargetPlatform;
switch (defaultTargetPlatform) {
  case TargetPlatform.android: ...
  case TargetPlatform.iOS: ...
  case TargetPlatform.windows: ...
  case TargetPlatform.macOS: ...
  case TargetPlatform.linux: ...
}

// ③ 条件导入（平台 API 差异大时用，见 3.5）

5.2 实践建议 ​

  • 平台分支集中在适配层，不要让 if (kIsWeb) 散落各处
  • 用抽象接口 + 多实现（同 09 篇数据层 的 Repository 思路）
  • 条件导入的文件命名清晰：xxx_web.dart / xxx_native.dart

六、常见陷阱速查 ​

陷阱症状解法
部署后刷新 404深链接/刷新报 404服务器配 fallback 到 index.html
接口跨域失败本地正常线上挂服务端配 CORS
dart:io 编译失败Web 构建报找不到 dart:io改 kIsWeb + 条件导入
首屏白屏很久加载 2~5 秒空白加 loading 占位 + 压缩 + 换渲染器
字体不生效/太大字体回退或加载慢声明字体 + 子集化
中文输入法异常输入法候选框位置错乱特定版本问题，升级 Flutter 版本
桌面端窗口尺寸异常启动尺寸不对window_manager 设置初始尺寸
鼠标滚轮滚动过快/过慢滚动体验异常桌面端需调整滚动物理参数
构建产物路径找不到不知产物在哪build/web（Web）、build/windows/runner/Release（Win）

七、动手练习 ​

练习 25.1（Web 跑通）：把现有项目跑起来 flutter run -d chrome，记录：首屏耗时、包体大小、哪些页面布局正常、哪些错乱。

练习 25.2（渲染器对比）：分别用 html 与 canvaskit 构建，对比包体大小与复杂动画页面的流畅度，把数据记下来。

练习 25.3（刷新 404）：用 path 路由模式，本地起个静态服务器访问子页面并刷新，复现 404，再配置 fallback 解决。

练习 25.4（响应式改造）：挑一个移动端页面，用 LayoutBuilder 改造成"窄屏单栏 / 宽屏两栏"，在浏览器里拖窗口验证。

练习 25.5（桌面端，有环境）：flutter run -d windows 跑通，加一个"窗口最小尺寸限制"和"关闭时最小化到托盘"的功能。

八、自检清单 ​

  • [ ] 能说出 Flutter Web 两种渲染器的差异与选型
  • [ ] 知道 CORS、路由 fallback、首屏体积三个 Web 端核心问题及解法
  • [ ] 知道 dart:io 在 Web 不可用，以及条件导入的写法
  • [ ] 能解释为什么"需要 SEO 的站点不适合用 Flutter Web"
  • [ ] 知道桌面端需要额外处理的窗口管理、键鼠交互、打包分发
  • [ ] 能把平台差异收敛到适配层，而不是散落 if (kIsWeb)

相关文档 ​

导航：上一章 24 · 推送通知与深链接 ｜ 下一章 26 · 混合开发与 Add-to-App