支援 WebAssembly (Wasm)
Flutter 對 WebAssembly (Wasm) 支援的最新狀態。
Flutter 與 Dart 支援將 WebAssembly 作為網頁應用程式的編譯目標。
開始使用
#若想體驗預先建置的 Flutter WebAssembly 應用程式,請參考 Wonderous demo app。
若要在自己的應用程式中嘗試 Wasm,請依照以下步驟操作。
切換到最新版本的 Flutter
#
請切換至 Flutter 3.24 或更高版本,
以便執行並編譯 Flutter 應用程式至 WebAssembly。
為確保您使用的是最新版本,請執行 flutter upgrade。
確認應用程式的相依套件相容
#您可以嘗試預設範本 sample app, 或選擇任何已遷移為 相容 Wasm 的 Flutter 應用程式。
修改 index 頁面
#
請確保您的 web/index.html 已更新為 Flutter 3.22 及之後版本的
Flutter web app initialization。
如果您想使用預設設定,請刪除 web/
目錄中的所有內容,然後執行下列指令以重新產生:
flutter create . --platforms web
執行或建置您的應用程式
#若要在開發或測試時以 Wasm 執行應用程式,請在 flutter run 指令中加入 --wasm 旗標。
flutter run -d chrome --wasm
要建置一個使用 Wasm 的網頁應用程式,請在現有的 flutter build web 指令中加入 --wasm 旗標。
flutter build web --wasm
該指令會將輸出產生在相對於套件根目錄的 build/web 目錄中,就像 flutter build web 一樣。
Wasm 正式環境除錯
#預設情況下,Wasm release 建置會移除除錯符號 (debug symbols) 並省略 source map, 以將二進位檔大小降到最低。
-
用於錯誤監控(建議):傳入
--source-maps以產生main.dart.wasm.map檔案,供錯誤追蹤服務進行符號還原 (symbolication)。 關於安全性建議與部署警告,請參考 Source maps。 -
用於 staging 或 QA 建置:傳入
--no-strip-wasm以在瀏覽器主控台的堆疊追蹤 (stack trace) 中 直接保留 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);
使用 HTTP 伺服器提供建置後的輸出
#Flutter Web WebAssembly 可以利用多執行緒來更快地渲染您的應用程式,減少卡頓現象。為了達成這一點,Flutter 會使用進階的瀏覽器功能,而這些功能需要特定的 HTTP 回應標頭(HTTP response headers)。
| 名稱 | 值 |
|---|---|
Cross-Origin-Embedder-Policy |
credentialless 或 require-corp |
Cross-Origin-Opener-Policy | same-origin |
想進一步了解這些標頭,請參考 Load cross-origin resources without CORP headers using COEP: credentialless。
進一步了解瀏覽器相容性
#
在 Flutter 3.50 及更高版本中,執行編譯為 Wasm 的 Flutter 應用程式(dart2wasm +
skwasm)需要支援三項標準化 WebAssembly 功能的瀏覽器:
- WasmGC(垃圾回收,Garbage Collection)
-
JS String Builtins(
wasm:js-string) -
Phase 4 Exception Handling(
try_table/exnref)
啟動時,flutter_bootstrap.js 會探測瀏覽器的 WebAssembly 引擎是否支援這些功能,
並在選擇 Wasm 建置前檢查 wasmAllowList 設定。
當瀏覽器不支援這些功能,或未在 wasmAllowList 中啟用時,
Flutter 會自動退回使用 flutter build web --wasm 所產生的
JavaScript(dart2js)與 CanvasKit 建置。
| 瀏覽器引擎 | Wasm 最低版本 | Flutter 3.50 的預設行為 (--wasm) |
如何啟用 Wasm |
|---|---|---|---|
| Chromium (Chrome, Edge, Opera, Brave) | 137+ (Desktop & Android) |
預設執行
dart2wasm
+
skwasm
;Chrome
< 137
會退回
dart2js
+ CanvasKit。
|
預設啟用 (wasmAllowList.blink: true)。 |
| WebKit (Safari macOS & iOS, all iOS browsers) | Safari 26.2+ (macOS & iOS 26.2+) | 預設退回 dart2js + CanvasKit (wasmAllowList.webkit: false)。 |
在
Flutter web app initialization
中設定
wasmAllowList: { webkit: true }
。Safari
<= 26.1
會透過執行時功能偵測自動退回
dart2js
+ CanvasKit。
|
| Gecko (Firefox) | Firefox 147+ | 預設退回 dart2js + CanvasKit (wasmAllowList.gecko: false)。 |
在
Flutter web app initialization
中設定
wasmAllowList: { gecko: true }
。Firefox
< 147
會自動退回
dart2js
+ CanvasKit。
|
使用相容的 JS interop 函式庫
#
為了支援編譯至 Wasm,Dart 已將其與瀏覽器及 JavaScript API 互通的方式現代化。
舊版 Dart SDK 的 web 與 JS interop 函式庫(dart:html、dart:js、
dart:js_util、dart:indexed_db、dart:svg、dart:web_audio
以及
dart:web_gl)已棄用,並計畫在未來的版本中從 Dart SDK 移除,
編譯至 Wasm 時,這些函式庫與已棄用的 package:js 套件皆不受支援。
取而代之的是,Dart 提供輕量級、以靜態 JS interop 為核心的解決方案, 可同時適用於 JavaScript 與 WebAssembly 目標:
-
package:web,可取代dart:html(以及其他舊版 web 函式庫) -
dart:js_interop,可取代package:js、dart:js與dart:js_util
關於遷移既有程式碼的詳細指南,
請參考 package:web 遷移指南。
編譯至 Wasm 時,請留意 JS interop 型別在執行時的差異
(例如 is/as 型別轉換,以及回呼中的 Zone 傳遞)。
詳情請參考 Dart 的
JS interop 型別文件
與 package:web Zones 章節。
想進一步了解 Dart 的 JS interop, 請參考 Dart 的 JS interop 文件頁面。
診斷 Wasm 編譯錯誤
#
使用 --wasm 編譯 Flutter 網頁專案時,如果您的應用程式或其套件
匯入了不支援的 web API(例如 dart:html 或 package:js),
編譯就會失敗。
1. 及早偵測並強制使用現代 JS interop
#
您可以透過 dry-run 警告及早偵測不相容之處。執行不帶 --wasm 旗標的
flutter build web 時,仍會自動執行 Wasm dry run
(傳入 --no-wasm-dry-run 可停用)。如果發現不相容之處,
您會看到類似下列的非致命警告:
Wasm dry run failed:
Found incompatibilities with WebAssembly.
package:my_app/main.dart 1:1 - dart:html unsupported (0)
在 Flutter 3.50 及更高版本中,您也可以在 JavaScript(dart2js 與 ddc)建置中
強制使用現代 JS interop。這可確保 Wasm 相容性,
並讓您的應用程式為即將從 Dart SDK 移除已棄用 web 函式庫做好準備。
請將 --no-deprecated-js-interop 傳給 flutter build web、
flutter run、flutter drive 或 flutter test --platform chrome:
flutter build web --no-deprecated-js-interop
傳入 --no-deprecated-js-interop 會使匯入已棄用 dart:* web
函式庫(以及匯入它們的套件,例如 package:js)的程式碼在
編譯時失敗。它也會讓條件式匯入中的 dart.library.html、dart.library.js 與
dart.library.js_util 求值為 false。
2. 檢查編譯器相依樹
#
如果您執行 flutter build web --wasm 時因不支援的匯入而失敗,
flutter_tools 會印出結構化的 Context 樹,
顯示是哪個套件與檔案匯入了無法使用的函式庫:
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
3. 遷移舊版匯入
#若要修正這些編譯錯誤,您必須從舊版 JS interop 套件遷移至相容 WebAssembly 的現代替代方案:
-
以
package:web取代dart:html與其他舊版 web 函式庫。 -
以
dart:js_interop取代dart:js與package:js。
完整的遷移說明,請參考
dart.dev 上的 package:web 遷移指南
以及 Dart 的 JS interop 使用指南。
如果您在遷移期間需要同時支援舊版與現代環境,
請透過檢查 dart.library.js_interop 來使用條件式匯入:
import 'fallback.dart'
if (dart.library.js) 'legacy_web_interop.dart'
if (dart.library.js_interop) 'wasm_web_interop.dart';
想進一步了解如何在編譯時選擇實作,請參考 dart.dev 上的條件式匯入文件。
Unless stated otherwise, the documentation on this site reflects Flutter 3.47. Page last updated on 2026-10-25. View source or report an issue.