当前位置：首页 > news >正文

Flutter WebAssembly (Wasm) 支持 - 实用指南Flutter WebAssembly (Wasm) 支持 - 实用指南

news 2025/9/3 11:05:16

Flutter WebAssembly (Wasm) 支持 - 实用指南

概述

WebAssembly (Wasm) 是一种低级的二进制格式，旨在成为高级语言（如 Dart）在 Web 平台上的编译目标。它能提供接近原生的执行性能。

Flutter 和 Dart 在构建 Web 应用时，支持将应用编译为 WebAssembly 格式。这标志着 Flutter Web 应用在性能上的一次重大飞跃。

核心优势:

性能提升: Wasm 代码执行效率远高于 JavaScript，尤其适用于计算密集型操作。
启动优化: 可以带来更快的应用启动速度。
多线程渲染: 利用高级浏览器特性，实现多线程渲染，减少卡顿 (Jank)。

开始使用

1. 切换到最新版本的 Flutter

要编译和运行 Wasm 应用，你需要 Flutter 3.24 或更高版本。

flutter upgrade

2. 确保你的应用依赖项兼容

尝试使用默认的模板示例应用 (flutter create my_wasm_app)。
或者，确保你现有的 Flutter 应用已迁移至支持 Wasm 的依赖项。一些旧的、依赖于 dart:html 或 package:js 的包可能需要更新。

3. 更新 Index 页面

确保你应用的 web/index.html 文件已更新为 Flutter 3.22+ 的最新初始化方式。

简单方法: 删除 web/ 目录下的所有内容，然后重新生成：

flutter create . --platforms=web

4. 运行或构建你的应用

开发运行 (使用 Chrome 浏览器):
```
flutter run -d chrome --wasm
```
生产构建:
```
flutter build web --wasm
```
输出文件位于 build/web/ 目录，与标准 JavaScript 构建输出位置相同。

5. 在兼容的浏览器中打开应用

即使使用了 --wasm 标志，Flutter 也会同时生成 JavaScript 和 Wasm 代码。运行时如果浏览器不支持 WasmGC，则会自动回退到 JavaScript 版本，保证应用在所有主流浏览器中都能工作。

如何检测应用是否正在以 Wasm 模式运行？

推荐方法: 检查编译时设置的环境变量。

const bool isRunningWithWasm = bool.fromEnvironment('dart.tool.dart2wasm');
if (isRunningWithWasm) {print('Running on WebAssembly! 🚀');
} else {print('Running on JavaScript (fallback mode).');
}

备用方法: 利用数字表示的差异进行检测。

final bool isRunningWithWasm = identical(double.nan, double.nan);

重要配置：部署与 HTTP 头

为了启用 多线程渲染 以获得最佳性能，你的 HTTP 服务器必须配置特定的响应头。

头部名称 (Name)	值 (Value)
`Cross-Origin-Embedder-Policy`	`credentialless` 或 `require-corp`
`Cross-Origin-Opener-Policy`	`same-origin`

如果不设置这些头部，应用将无法使用多线程渲染功能。

了解更多: 使用 COEP: credentialless 加载跨域资源

浏览器兼容性

要运行编译为 Wasm 的 Flutter 应用，你需要一个支持 WasmGC (垃圾回收) 的浏览器。

浏览器	支持情况	说明
Chrome	✅ 119+ (桌面版 & Android)	基于 V8 引擎，支持良好。
Edge	✅ 119+	基于 Chromium，支持同 Chrome。
Firefox	⚠️ 120+ 宣布支持，但目前因 Bug 不可用	存在一个已知 Bug 阻止与 Flutter Wasm 渲染器兼容。需要关注此问题进展。
Safari	⚠️ 技术预览版支持，但目前因 Bug 不可用	存在一个类似 Bug 阻止兼容。需要关注此问题进展。
iOS 所有浏览器	❌ 不支持	所有 iOS 浏览器都必须使用 WebKit 内核，而 WebKit 对 WasmGC 的支持尚未就绪，无法运行 Flutter Wasm 应用。