mcpField
F
flutter-wasm-web

flutter-wasm-web

github.com/dhruvanbhalara开发3037 次安装8 周前更新
代码仓库

关于 flutter-wasm-web

flutter-wasm-web 是一份关于使用 WebAssembly（Wasm-GC）构建和调试 Flutter Web 应用的技能指南，面向 Flutter 开发者。内容涵盖编译部署、JavaScript 互操作以及 Wasm 的限制与处理方法。

主要功能

  1. 01通过 Flutter CLI 编译 Wasm
  2. 02说明服务器 MIME 与隔离响应头
  3. 03介绍现代 JavaScript 互操作
  4. 04列出 Wasm 平台限制及处理方法
  5. 05指导使用 Chrome 调试 Wasm

适用场景

  1. 01将 Flutter Web 应用编译为 Wasm
  2. 02配置 Wasm 文件的托管响应头
  3. 03排查依赖 dart:io 的编译问题
  4. 04在 Chrome 中检查 Wasm 源码

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dhruvanbhalara/skills --skill flutter-wasm-web

安装后在 Claude Code 中输入/flutter-wasm-web确认已加载。

详细介绍

Flutter Web 与 WebAssembly（Wasm-GC）

Flutter Web 支持编译为 WebAssembly（Wasm-GC），带来接近原生的 UI 渲染性能、更流畅的动画和更快的加载速度。

目录

编译与部署

使用 Flutter CLI 将应用编译为 WebAssembly：

flutter build web --wasm
服务端配置

Wasm-GC 要求通过正确的 HTTP 标头提供特定文件。请确保 Web 主机（Firebase Hosting、Cloudflare、Vercel、Nginx）包含：

  • 为生成的 .wasm 文件设置 Content-Type: application/wasm。
  • COOP 和 COEP 标头（建议启用，以提升性能并确保多线程安全）：
    • Cross-Origin-Opener-Policy: same-origin
    • Cross-Origin-Embedder-Policy: require-corp

现代 JS 互操作（dart:js_interop 和 package:web）

Wasm-GC 编译严格禁止使用旧版 dart:html、dart:js 或 package:js 库。必须使用标准的 dart:js_interop 和 package:web 包。

JS 互操作核心原则
  • 不要导入 dart:html。导入 package:web/web.dart 以访问 DOM。
  • 使用 @JS() 注解声明外部 JavaScript 函数。
  • 始终使用 Dart JS 类型（例如 JSString、JSNumber、JSBool、JSAny、JSObject）。
示例：调用 JS API
import 'dart:js_interop';
import 'package:web/web.dart';

// Declare external JS API
@JS('console.log')
external void jsConsoleLog(JSAny message);

@JS('localStorage.setItem')
external void jsSetLocalStorage(JSString key, JSString value);

void main() {
  // Convert Dart types to JS types
  jsConsoleLog('Hello from Wasm-GC!'.toJS);
  jsSetLocalStorage('app_mode'.toJS, 'dark'.toJS);
  
  // Accessing the DOM via package:web
  final windowEl = window;
  jsConsoleLog(windowEl.location.href.toJS);
}

Wasm 特有限制与解决方案

1. 不支持 dart:io
  • 影响：文件系统、Socket 和标准 HTTP 客户端无法编译。
  • 解决方案：使用 package:http（会解析为浏览器原生 Fetch API），并使用 IndexedDB 或本地存储进行缓存。
2. Isolate/线程限制
  • 影响：标准 Dart VM isolate 无法在 WebAssembly 中运行。在 Web 上调用 Isolate.spawn 或 compute() 会引发运行时错误。
  • 解决方案：如需进行繁重处理，可通过 JS 互操作使用 Web Worker 线程；或者将计算拆分成小块，在主线程上执行。
3. 字体和资源加载
  • 影响：Wasm 编译使用 CanvasKit 渲染 Widget。必须在 pubspec.yaml 中显式声明自定义字体，以防回退到其他字体进行渲染。

调试 WebAssembly

  • Chrome 开发者工具：Chrome 支持调试 Wasm-GC 源映射。你可以直接在 Chrome 的 Sources 面板中检查 Dart 源代码。
  • 检查兼容性：使用 flutter run -d chrome --wasm，在本地以 Wasm 模式运行和调试。

评论

支持 Markdown