对 WebAssembly (Wasm) 的支持

Flutter 与 Dart 支持将 WebAssembly 作为 Web 构建应用时的编译目标。

要试用使用 Wasm 构建的 Flutter Web 应用，可查看 Wonderous 演示应用。

若要在自己的应用中试验 Wasm，请按以下步骤操作。

请切换到 Flutter 3.24 或更高版本，以运行并将 Flutter 应用编译为 WebAssembly。要确保使用最新版本，请运行 flutter upgrade。

请尝试默认模板 示例应用，或选择已迁移为 与 Wasm 兼容的任意 Flutter 应用。

请确保应用的 web/index.html 已更新为适用于 Flutter 3.22 及更高版本的最新 Flutter Web 应用初始化。

若要使用默认配置，请删除 web/ 目录内容并运行以下命令重新生成：

$ flutter create . --platforms web

要在开发或测试时使用 Wasm 运行应用，请在 flutter run 命令中使用 --wasm 标志。

$ flutter run -d chrome --wasm

要使用 Wasm 构建 Web 应用，请在现有的 flutter build web 命令中添加 --wasm 标志。

$ flutter build web --wasm

该命令会在相对于 package 根的 build/web 目录中生成输出，与 flutter build web 相同。

默认情况下，Wasm 发布构建会移除调试符号并省略源映射文件，以尽可能减小二进制文件的大小。

• 错误监控（推荐）：传递 --source-maps 参数来生成 main.dart.wasm.map 文件，供错误跟踪服务进行符号映射。相关安全建议和部署警告，请参考 源映射。

• staging 或 QA 构建：传递 --no-strip-wasm 参数，可在浏览器控制台的堆栈跟踪中直接保留 Wasm 函数名词，但会导致 Wasm 二进制文件大小增加约 47%。

# Generate source maps for production error tracking:
$ flutter build web --wasm --source-maps

# Preserve Wasm function names for staging/QA debugging:
$ flutter build web --wasm --no-strip-wasm

即使使用 --wasm 标志，Flutter 仍会将应用编译为 JavaScript。若运行时未检测到 WasmGC 支持，将使用 JavaScript 输出，因此应用仍可在所有主流浏览器中运行。

你可以通过检查编译时设置的 dart2wasm 环境变量来验证应用是否实际以 Wasm 运行（推荐）。

const isRunningWithWasm = bool.fromEnvironment('dart.tool.dart2wasm');

或者，你可以利用数字表示方式的差异来测试是否使用了原生 (Wasm) 数字表示。

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

Flutter Web WebAssembly 可使用多线程更快渲染应用并减少卡顿。为此，Flutter 使用需要特定 HTTP 响应标头的高级浏览器功能。

要了解这些标头的更多信息，请参阅 使用 COEP: credentialless 加载无需 CORP 标头的跨域资源。

要运行已编译为 Wasm 的 Flutter 应用，你需要支持 WasmGC 的浏览器。

Chromium 与 V8 自 119 版起支持 WasmGC。 iOS 上的 Chrome 使用 WebKit，目前尚不 支持 WasmGC。 Firefox 在 120 版宣布稳定支持 WasmGC，但由于已知限制目前无法工作（详见下文）。

• 为何不用 Firefox？ Firefox 120 及更高版本此前可以运行 Flutter/Wasm，但目前存在一个阻碍与 Flutter Wasm 渲染器兼容的 bug。详情请关注 此 bug。

• 为何不用 Safari？ Safari 现已支持 WasmGC，但存在类似 bug，阻碍与 Flutter Wasm 渲染器的兼容。详情请关注 此 bug。

为支持编译到 Wasm，Dart 改变了与浏览器和 JavaScript API 互操作的方式。这会导致使用 dart:html 或 package:js 的 Dart 代码无法编译为 Wasm。

取而代之的是，Dart 现在提供基于静态 JS 互操作的新轻量方案：

• package:web，用于替代 dart:html（及其他 Web 库）

• dart:js_interop，用于替代 package:js 和 dart:js

相关迁移现有代码的详细指南，请参考 package:web 迁移指南

在编译为 Wasm 时，请注意 JS 交互操作类型在运行时存在的差异（例如 is/as 类型转换以及回调中的 Zone 传播）。详情请查看 Dart 的 JS 互操作类型文档 以及 package:web 中的 Zones.

要了解 Dart 中的 JS 互操作，请参阅 Dart 的 JS interop 文档页面。

When compiling a Flutter web project with --wasm, if your application or its packages import unsupported web APIs (such as dart:html or package:js), the compilation will fail.

By default, the Dart Wasm compiler emits a clean, structured dependency chain tree, but this output can be buried in a long terminal exception stack trace.

You can detect incompatibilities early with dry-run warnings. When you run flutter build web without the --wasm flag, a Wasm dry run is still performed automatically. If incompatibilities are found, you will see a non-fatal warning like this:

Wasm dry run failed:
Found incompatibilities with WebAssembly.

package:my_app/main.dart 1:1 - dart:html unsupported (0)

If you run flutter build web --wasm and it fails, flutter_tools outputs a large exception stack trace (for example, Target dart2wasm failed...).

Ignore the long stack trace and command string. Instead, scroll up to the top of the error output to find the structured Context tree. This clean tree tells you exactly which package and file imported the unsupported library:

Context: The unavailable library 'dart:html' is imported through these packages:

    main.dart => package:my_app => dart:html

Detailed import paths for (some of) these imports:

    main.dart => package:my_app/main.dart => dart:html

To fix these compilation errors, you must migrate from legacy JS interop packages to modern WebAssembly-compatible alternatives:

• Replace dart:html and other legacy web libraries with package:web.
• Replace dart:js and package:js with dart:js_interop.

For comprehensive migration instructions, check out the package:web migration guide on dart.dev and Dart's JS interop usage guide.

If you need to support both legacy and modern environments during your migration, use conditional imports by checking for dart.library.js_interop:

import 'fallback.dart'
  if (dart.library.js) 'legacy_web_interop.dart'
  if (dart.library.js_interop) 'wasm_web_interop.dart';

To learn more about selecting implementations at compile time, see the conditional imports documentation on dart.dev.