建置與發佈 Web 應用程式
如何準備並發佈 Web 應用程式。
在一般的開發週期中,
你會在命令列介面 (Command Line Interface) 上使用 flutter run -d chrome
(例如)來測試應用程式。
這會建置出你的應用程式的 debug(除錯)版本。
本頁將協助你準備應用程式的 release(發佈)版本, 並涵蓋以下主題:
- 建置發佈版本的應用程式
- Web 內容雜湊與 HTTP 快取
- 部署至 Web
- 部署至 Firebase Hosting
- 在 Web 上處理圖片
- 選擇加入 WebAssembly
- 程式碼壓縮(Minification)
- 行動瀏覽器 viewport 與 SafeArea
建置發佈版本的應用程式
#請使用 flutter build web 指令來建置應用程式以進行部署。
flutter build web
若要使用 WebAssembly (Wasm) 建置你的應用程式,請加上 --wasm 旗標:
flutter build web --wasm
這個動作會產生應用程式(包含資源),並將檔案放置在專案的 /build/web 目錄中。
若要驗證應用程式的發行版本(release build),請啟動一個網頁伺服器(例如 python -m http.server 8000,或使用 dhttpd
套件),然後開啟 /build/web 目錄。在瀏覽器中前往 localhost:8000(以 Python SimpleHTTPServer 為例),即可檢視應用程式的發行版本。
其他建置旗標
#
你可能需要部署 profile 或 debug 版本以進行測試。
要這麼做,請在 flutter build web 指令中加入 --profile 或 --debug
旗標。
Profile 版本專為使用 Chrome DevTools 進行效能分析而設計,
Debug 版本則可用來設定 dart2js 以支援 assertion 並調整最佳化等級(可使用 -O 旗標)。
Source maps
#
若要產生 source map,以便在當機回報服務中進行符號還原(symbolication),
請加上 --source-maps 旗標:
flutter build web --source-maps
產生 source map 時,會在 build/web 目錄中建立獨立的 .js.map 或 .wasm.map 檔案
(或兩者皆有,視你的建置目標而定),
且不會為編譯後的輸出增加二進位檔的負擔。
Web 內容雜湊 (--web-content-hash)
#
若要在多次部署之間啟用以內容為基礎的自動快取更新(cache busting),
請在 flutter build web 中加上 --web-content-hash:
flutter build web --wasm --web-content-hash
啟用 --web-content-hash 後,Flutter 會將截短為 8 個字元的 SHA-256 內容雜湊,
嵌入編譯後的進入點以及 build/web/assets/** 下的所有檔案,
並將雜湊後的路徑記錄在 flutter_bootstrap.js(_flutter.buildConfig)中:
-
已雜湊的不可變檔案(
Cache-Control: public, max-age=31536000, immutable):- 編譯後的進入點:
main.dart.<hash>.js、main.dart.<hash>.wasm以及main.dart.<hash>.mjs(若啟用--source-maps,另有main.dart.<hash>.js.map與main.dart.<hash>.mjs.map)。 assets/**下的所有檔案:包含AssetManifest.<hash>.bin、AssetManifest.bin.<hash>.json、FontManifest.<hash>.json、NOTICES.<hash>、字型、圖片以及shaders/**。
- 編譯後的進入點:
-
未雜湊的啟動與根目錄檔案(
Cache-Control: max-age=0, must-revalidate或no-cache):index.html、flutter_bootstrap.js、flutter.js、manifest.json、version.json、404.html以及icons/**。- 使用
--no-web-resources-cdn建置時所內含的canvaskit/**檔案。 - 使用
--source-maps建置時的main.dart.wasm.map(.wasm二進位檔的sourceMappingURL自訂區段所參照的是未雜湊的.wasm.map檔名)。
如需完整的 firebase.json 範例,請參閱 Web FAQ。
針對作用中瀏覽器分頁的疊加部署
#
當你部署新版本(N)時,已開啟瀏覽器分頁且仍執行前一版本(N-1)的使用者,
可能會延遲載入(lazily fetch)檔名帶有 N-1 版本內容雜湊的資源、字型或圖片。
為避免在版本推出期間於工作階段中途出現 404 錯誤,
請採用**疊加部署(overlay deployment)**策略:
-
在你的 CDN 或儲存空間 bucket 中,除了
N版本已雜湊的檔案之外, 至少也保留前一版本(N-1)已雜湊的main.dart.*與assets/**檔案(或在 24–72 小時的寬限期後清除舊的雜湊檔案)。 - 最後再以原子(atomic)方式更新
index.html與flutter_bootstrap.js。 -
將
/assets/**、/canvaskit/**、/icons/**與/main.dart.*排除在 單頁應用程式(SPA)的/index.html全域改寫(catch-all rewrite)規則之外, 這樣找不到的資源就會回傳真正的404,而不是200 text/html。
自訂 service worker(precache_manifest.json)
#
啟用 --web-content-hash 後,flutter build web 會將物料清單(bill of materials)
寫入 build/web/precache_manifest.json:
{
"version": 1,
"entries": [
{
"url": "flutter_bootstrap.js",
"hash": "a1b2c3d4",
"size": 10432,
"urlHashed": false
},
{
"url": "main.dart.f215ce97.wasm",
"hash": "f215ce97",
"size": 1842104,
"urlHashed": true
}
]
}
自訂的 PWA service worker 或 Workbox 管線可以直接使用
precache_manifest.json(傳入 revision: entry.urlHashed ? null : entry.hash,
以避免 URL 已雜湊的檔案因查詢參數而被重複快取)。
選擇加入 WebAssembly
#
若要針對 WebAssembly 編譯並最佳化你的應用程式,
請在執行或建置時使用 --wasm 旗標。
如需更多資訊,請參閱 Support for WebAssembly (Wasm)。
部署至 Web
#當你準備好部署應用程式時,請將發行套件(release bundle)上傳至 Firebase、雲端或其他類似服務。以下是幾種常見選擇,當然還有其他方式:
部署至 Firebase Hosting
#你可以使用 Firebase CLI 來建置並釋出 Flutter 應用程式至 Firebase Hosting。
開始之前
#首先,請安裝或更新 Firebase CLI:
npm install -g firebase-tools
初始化 Firebase
#-
在 Firebase framework-aware CLI 啟用 Web 框架預覽功能:
firebase experiments:enable webframeworks -
在一個空的目錄或現有的 Flutter 專案中,執行初始化指令:
firebase init hosting 當系統詢問是否要使用 web framework(網頁框架)時,請選擇
yes。如果你目前位於一個空的目錄中,系統會要求你選擇你的 web framework,請選擇
Flutter Web。選擇你的 Hosting 原始目錄(hosting source directory);這可以是一個現有的 Flutter 應用程式。
選擇一個區域來託管你的檔案。
選擇是否要與 GitHub 設定自動建置與部署。
-
將應用程式部署到 Firebase Hosting:
firebase deploy執行此指令會自動執行
flutter build web --release, 因此你不需要另外進行應用程式的建置步驟。
如需進一步了解,請參閱官方 Firebase Hosting Flutter Web 文件。
在 Web 上處理圖片
#
Web 支援標準的 Image 元件(Widget)來顯示圖片。
基於設計,網頁瀏覽器會執行不受信任的程式碼,同時不會危害主機電腦。
這使得在圖片處理方面,Web 相較於行動裝置和桌面平台有更多限制。
如需更多資訊,請參閱 Displaying images on the web。
程式碼壓縮(Minification)
#
為了提升應用程式啟動速度,編譯器會透過移除未使用的程式碼(稱為 tree shaking 樹狀搖晃),以及將程式碼符號重新命名為更短的字串(例如將 AlignmentGeometryTween
重新命名為像是 ab)來減少編譯後程式碼的大小。這兩種最佳化方式的應用,取決於建置模式:
| Web 應用程式建置類型 | 程式碼壓縮? | 是否執行 tree shaking? |
|---|---|---|
| debug | 否 | 否 |
| profile | 否 | 是 |
| release | 是 | 是 |
行動瀏覽器 viewport 與 SafeArea
#
在具有螢幕切口、瀏海或 Home 指示條的行動瀏覽器(例如 iOS Safari 與 Android Chrome)上,
Flutter Web 預設會在瀏覽器的安全區域內進行渲染(viewport-fit=contain)。
若要橫跨整個螢幕進行邊到邊(edge-to-edge)渲染,
並以瀏覽器的 CSS env(safe-area-inset-*) 內縮值填入 Flutter 的
SafeArea
與 MediaQuery.paddingOf,
請在 web/index.html 檔案的 <head> 中加入帶有
viewport-fit=cover 的 <meta name="viewport"> 標籤
(新建立的 web/index.html 範本中已將其以註解形式附上作為選項):
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
瀏覽器歷史紀錄中的 URL 百分比編碼
#
在 Flutter 3.50 與更新版本中,傳給
SystemNavigator.routeInformationUpdated 的路由字串,
在寫入瀏覽器網址列與歷史紀錄時,會保留百分比編碼序列
(例如 %2F、%26、%23 與 %20),
而不是使用 Uri.decodeComponent 將其解碼。
將 Flutter 應用程式嵌入 HTML 頁面
#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.