Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

為 Web 匯出

也參考

這個頁面描述的是如何將 Godot 專案匯出到 HTML。如果你想要找的是從源碼編譯編輯器或匯出範本二進位檔案，請閱讀 編譯至網頁平台。

HTML5 匯出功能允許將 Godot Engine 製作的遊戲發佈到瀏覽器。使用者瀏覽器必須支援 WebAssembly 和 WebGL 2.0 才能執行。

注意

目前使用 Godot 4 開發的 C# 專案尚無法匯出至網頁。更多資訊請參考 這篇部落格。

若要在網頁平台上使用 C#，請改用 Godot 3。

小訣竅

請使用瀏覽器內建的開發者主控台（通常可用 F12，或 Ctrl + Shift + I`（macOS 上為 :kbd:`Cmd + Option + I）開啟），來查看 除錯資訊，例如 JavaScript、引擎與 WebGL 錯誤。

如果快捷鍵沒有效果，通常是因為 Godot 攔截了該輸入。你仍然可以從瀏覽器選單開啟開發者主控台。

備註

因為 SharedArrayBuffer 存在安全疑慮及潛在漏洞，Web 平台上啟用多執行緒會有多項限制，包括需要特殊的伺服器標頭及完全的跨來源隔離（這代表你的遊戲網站不能有廣告或第三方整合）。

自 Godot 4.3 起，Godot 支援將遊戲匯出為單執行緒，解決此問題。雖然有無法使用執行緒、效能不如多執行緒匯出的缺點，但安裝所需的額外步驟較少。整體上也更相容於 itch.io 等商店與 Poki、CrazyGames 等網頁發佈平台。單執行緒匯出在 macOS 與 iOS 上也表現良好，以往多執行緒匯出在這些平台常有相容性問題。

因此，目前建議並預設使用單執行緒方式進行網頁匯出。

更多說明請參見 這篇關於單執行緒 Web 匯出的官方部落格。

也參考

請參考 GitHub 上與網頁匯出相關的公開議題列表，以了解目前的已知問題。

匯出檔案名稱

建議將網頁專案匯出為 index.html，因為大多數網頁伺服器會自動載入此檔案，讓網址更簡潔。

注意

Godot 4 網頁匯出會預期部分檔案名稱與初始匯出設定相同，若更改主 HTML 或其他匯出檔案名稱，可能導致專案無法正確運作。

WebGL 版本

Godot 4 can only target WebGL 2.0 (using the Compatibility rendering method). Forward+/Mobile are not supported on the web platform, as these rendering methods are designed around modern low-level graphics APIs. Godot currently does not support WebGPU, which is a prerequisite for allowing Forward+/Mobile to run on the web platform.

請參考 Can I use WebGL 2.0 以查看支援 WebGL 2.0 的瀏覽器版本列表。請注意，Safari 在 WebGL 2.0 支援上有一些其他瀏覽器沒有的問題，建議盡量使用 Chromium 核心瀏覽器或 Firefox。

行動裝置注意事項

網頁匯出也可在行動裝置上執行，但會有一些限制。原生匯出（Android、iOS）的效能會明顯較佳，但網頁匯出讓玩家能直接在瀏覽器體驗遊戲，無需經過應用商店。

請記得行動裝置的 CPU 與 GPU 效能有限，匯出為 WebAssembly 時效能會更低於原生程式。請參考 效能 章節獲得優化建議。如果專案同時支援其他平台，也能善用 功能標籤，針對網頁匯出自動啟用較低規格的設定。

為加速行動裝置載入速度，建議 自訂編譯最佳化匯出樣板，並關閉未用到的功能。根據專案內容，這可大幅減少 WebAssembly 檔案體積，下載及初始化速度更快，即使已被快取也適用。

音訊播放

自 Godot 4.3 起，網頁平台的音訊播放改用 Web Audio API。此 Sample 播放模式即使未啟用執行緒支援也有低延遲，但有幾項限制：

  • 不支援音訊效果（AudioEffects）。

  • 不支援 混響與都卜勒 效果。

  • 不支援程式化音效產生。

  • 定位音訊（Positional audio）可能依據節點屬性無法正確運作。

若要使用 Godot 自己的音訊播放系統在 Web 平台上，您可以透過使用 音訊 > 一般 > 預設播放類型.web 專案設定來變更預設播放模式，或在 AudioStreamPlayer、AudioStreamPlayer2D 或 AudioStreamPlayer3D 節點上，將 播放類型 屬性變更為 串流。這會導致延遲增加 (尤其當執行緒支援被停用時)，但這樣可以讓 Godot 的所有音訊功能運作。

匯出選項

若有可執行的網頁匯出樣板，則在編輯器上 [停止場景] 與 [執行編輯的場景] 按鈕中間會多一個按鈕，可以用來在預設瀏覽器中快速開啟遊戲來測試。

若專案使用 GDExtension，必須啟用 Extension Support。

如果你計畫使用 VRAM compression，請確認目標平台已啟用 VRAM Texture Compression**（VRAM 紋理壓縮）。同時啟用 **For Desktop 和 For Mobile 將使匯出檔案更大，但可提升相容性。

如果有設定 Custom HTML shell 檔案路徑，將會使用自訂 HTML 頁面取代預設版型。請參考 自訂 HTML 頁面用於網頁匯出。

Head Include 會被加入到產生的 HTML 頁面 <head> 元素的最後。這可以用來載入 Web 字型、第三方 JavaScript API、附加 CSS 或執行自訂 JavaScript 程式碼等。

預設會自動將視窗大小配合瀏覽器視窗大小。若想不受瀏覽器視窗大小影響、改用固定大小，請將 Canvas Resize Policy 改為 None。如此即可在 HTML 外殼中以自訂 JavaScript 程式碼控制視窗尺寸。你也可以將其設定為 Project，讓表現更接近原生匯出，依據 project settings。

重要

每個專案都會產生自己的 HTML 檔案。匯出時，數個文字佔位符會根據匯出選項自動取代。如果你直接修改這個 HTML 檔案，未來重新匯出會遺失這些更動。如需客製化，請改用 Custom HTML shell 選項。

執行緒與擴充套件支援

如啟用 Thread Support**（執行緒支援），匯出的專案就能 :ref:`善用多執行緒 <doc_using_multiple_threads>` 以提升效能。同時聲音播放模式設為 **Stream 時（預設網頁匯出為 Sample），可以獲得低延遲音訊。啟用此功能需伺服器設定跨來源隔離標頭，詳見下方 提供檔案服務。

若啟用 Extensions Support （擴充套件支援），即可載入 GDExtensions 。請注意，GDExtensions 仍需針對網頁平台特別編譯才能運作。和執行緒支援一樣，啟用此功能時也需伺服器設定跨來源隔離標頭。

匯出為 Progressive Web App（PWA）

若啟用 Progressive Web App > Enable，會有以下效果：

  • 可設定高解析度圖示、顯示模式與螢幕方向。這些設定在匯出選項的 Progressive Web App 區段底部。當使用者將專案加入裝置主畫面時（多見於行動裝置），會用到這些設定。桌面平台也支援，但功能較有限。

  • 只要專案曾經被載入過一次，即使斷網也能再次啟動。這是透過 service worker 機制，在專案首次於使用者瀏覽器載入時自動安裝，未來即使沒網路也能本地備援。

    • 請注意，瀏覽器可能因用戶磁碟空間不足，或長時間未開啟專案而清除快取。若要延長快取保存期限，建議玩家將頁面加入書籤，或直接加入裝置主畫面。

    • 若離線資料已被清除，也可設定一個 Offline Page （離線頁面）作為備用顯示。該頁面必須為 HTML 檔案，且會在使用者第一次載入專案時被儲存到本機端。

  • 確保即使伺服器未主動設定跨來源隔離標頭，專案仍會自動補上相關標頭。如此一來，啟用執行緒支援的匯出專案，在任何網站都能正常運作，即便你無法控制伺服器標頭。

    • 如需停用此功能，可於 Progressive Web App 區段取消勾選 Enable Cross Origin Isolation Headers。

限制

出於安全性與隱私考量，許多在原生平台上可直接運作的功能，在網頁平台上會變得更為複雜。下方列出將 Godot 遊戲移植到網頁時需注意的限制。

重要

瀏覽器供應商正在使越來越多的功能只在 安全本文 中可用，這意味著這些功能只有在通過安全的HTTPS連接提供網頁時才可用（localhost通常不受這種要求影響）。

使用 Cookie 進行資料持久化

若要保留 user:// 檔案系統中的資料，則使用者必須要 允許 Cookie (尤其是 IndexedDB)。若在 iframe 內玩遊戲的話，則必須同時啟用 第三方 Cookie。隱私模式也會防止保留資料。

OS.is_userfs_persistent() 方法可以用來檢查 user:// 檔案系統是否會被保留，但有時候檢查結果不會是正確的。

背景處理

這個標籤頁不再是使用者瀏覽器的活動標籤頁時，專案就會被瀏覽器暫停。也就是說不會運作 _process()、_physics_process() 等函式，除非使用者重新啟動了這個標籤頁（切換到這個標籤頁）。如果使用者在標籤頁外停留了過長的時間，就可能造成網路遊戲的掉線。

這一限制不適用於丟失焦點的瀏覽器*視窗*。因此，對於使用者而言，變通方法是讓專案運作在一個單獨的*視窗*中，而不是標籤頁。

全螢幕與滑鼠捕捉

瀏覽器不允許任意 進入全螢幕 。對於 捕捉游標 也是如此。相反地，這些操作必須作為對 JavaScript 輸入事件的回應而發生。在 Godot 中，這表示必須在已按下的輸入事件回呼函式 (例如 _input 或 _unhandled_input) 內進入全螢幕。查詢 Input 單例是不夠的，相關的輸入事件目前必須處於活躍狀態。

出於相同原因，除非引擎是從有效的輸入事件處理常式中開始的，否則無法使用全螢幕專案設定。要設定則需要 自定 HTML 頁面 。

音訊

部分瀏覽器會限制網站的音訊自動播放。最簡單的解法是要求玩家點擊、觸控或按下任意鍵／按鈕來啟用音訊，例如在遊戲啟動畫面時提示操作。

也參考

Google 針對其 Web Audio 自動播放政策 提供了更多資訊。

Apple 的 Safari 團隊也有發布 macOS 自動播放政策變更說明。

警告

存取麥克風需要 secure context 。

警告

自 Godot 4.3 起，Web 匯出預設以 Sample 模式播放音訊，而非 Stream。

這是因為瀏覽器對音訊播放的偏好，以及未啟用 Use Threads 匯出選項時，Web 遊戲處理能力有限。

請注意，目前樣本（Sample）播放尚未支援音訊效果。

網路

因瀏覽器未支援，低階網路功能尚未實作。

目前，只有 HTTP client, HTTP requests, WebSocket (client) 和 WebRTC 被支援。

在 HTML5 平台上，HTTP 類別有一些限制：

  • 無法存取或更改 StreamPeer

  • 無法使用 Threaded/Blocking 模式

  • 每影格無法處理多次，因此在迴圈內輪詢會導致程式凍結

  • 無法區塊回覆

  • 無法禁用主機驗證

  • 必須遵守 同源政策 (Same-origin policy)

剪貼簿

在引擎和作業系統之間同步剪貼板需要瀏覽器 剪貼板 API ，此外，由於該 API 的非同步性，從 GDScript 存取時可能不可靠。

警告

需要 secure context。

遊戲手柄

按下遊戲手柄上面的任一按鈕之後，這個遊戲手柄才能被偵測到。根據瀏覽器、作業系統、遊戲手柄三者的組合不同，遊戲手柄的對應可能有誤，可惜由於隱私方面的考慮， 遊戲手柄 API 並沒有提供可靠的方法來偵測遊戲手柄的資訊，因而無法根據模型、供應商、作業系統來進行重新對應。

警告

需要 secure context。

提供檔案服務

匯出網頁會產生多個用來在網頁伺服器上提供的檔案，其中包含一個用來顯示的預設 HTML 頁面。可以使用自定 HTML 檔案，請參考 自訂 HTML 頁面用於網頁匯出 。

警告

僅限啟用 Use Threads 匯出時，為確保低延遲音訊與支援 Thread，Godot 4 Web 匯出會使用 SharedArrayBuffer。這需要伺服器有 安全環境，並加上下列 CORS 標頭：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

如無法控制伺服器或無法加上回應標頭，請在匯出選項啟用 Progressive Web App > Enable。此選項會以 service worker 模擬標頭，讓專案可正常執行，但仍需安全環境（HTTPS）。

若客戶端收不到必要標頭，且未啟用 service worker 模擬，專案將無法執行。

產生的 .html 檔案可以用作 Apache 伺服器中的 DirectoryIndex ，並可以隨時重新命名，例如為 index.html 。它的名稱在預設情況下從不被依賴。

HTML 頁面會將遊戲顯示為瀏覽器視窗最大範圍，方便嵌入指定大小的 <iframe>，這是大多數網頁遊戲平台的慣例。

其他匯出檔案會與 .html 檔案同目錄、名稱不變。.wasm 是引擎的 WebAssembly 二進位模組，.pck 是遊戲主資源包，.js 則是啟動程式碼，供 .html 呼叫引擎，.png 是啟動畫面圖片。

.pck 檔案為二進位格式，通常以 application/octet-stream MIME 類型傳送。.wasm 則為 application/wasm。

警告

使用除了 application/wasm 以外的 MIME 類型傳送 WebAssembly 模組 (.wasm)，可能會阻礙一些啟動最佳化。

建議伺服器端啟用檔案壓縮，尤其是 .pck 和 .wasm 這兩個通常較大的檔案。WebAssembly 模組用 gzip 壓縮後通常可縮至原本的四分之一。若伺服器支援 Brotli，則更建議預壓縮以進一步減少檔案大小。

提供即時壓縮的主機: GitHub Pages (gzip)

不提供即時壓縮的主機： itch.io、GitLab Pages（支援手動 gzip 預壓縮）

小訣竅

Godot 儲存庫包含一個「託管本機 Web 伺服器的 Python 腳本 <https://raw.githubusercontent.com/godotengine/godot/master/platform/web/serve.py>」。該腳本旨在測試 Web 編輯器，但也可用於測試匯出的專案。

將連結的腳本儲存到名為「serve.py」的檔案中，將此檔案移至包含匯出專案的「index.html」的資料夾，然後在同一資料夾中的命令提示字元中執行以下命令：

# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .

在 Windows 上，您可以按住 Shift 並右鍵單擊 Windows 資源管理器中的空白區域，然後選擇 在此處開啟 PowerShell 視窗，在目前資料夾中開啟命令提示字元。

這將提供目前資料夾的內容並自動開啟預設的 Web 瀏覽器。

請注意，這個基於 Python 的 Web 伺服器僅適合開發測試用途。在正式部署時，請改用成熟的 Web 伺服器，例如 Apache 或 nginx。

與瀏覽器及 JavaScript 互動

如何與 JavaScript 互動並存取瀏覽器獨有功能，請參考 專門頁面。

環境變數

您可以使用下列環境變數在編輯器外部設定匯出選項。在匯出過程中，這些值會覆寫您在匯出選單中設定的值。

HTML5 匯出環境變數

匯出選項

環境變數

加密／加密金鑰

GODOT_SCRIPT_ENCRYPTION_KEY

疑難排解

在本機執行匯出時顯示成其他專案

若你在多個專案中使用一鍵部署，可能會發現顯示的是先前某個已部署的專案，而不是目前正在開發的專案。這是因為 service worker 快取目前缺乏自動的快取失效機制所致。

作為替代方案, 你可以手動取消註冊目前的 service worker, 以重設快取, 並允許註冊新的 service worker。在 Chromium 系瀏覽器中, 按 F12 或 Ctrl + Shift + I (macOS 為 Cmd + Option + I ) 開啟開發者工具, 然後在 DevTools 中點選 Application 分頁 (若面板過窄可能藏在山形圖示後)。你可以勾選 Update on reload 後重新載入頁面, 或點選目前已註冊的 service worker 旁的 Unregister , 再重新載入頁面。

在 Chromium 系瀏覽器的 DevTools 中取消註冊 service worker

在 Chromium 系瀏覽器的 DevTools 中取消註冊 service worker

在 Firefox 中流程相似。按 F12 或 Ctrl + Shift + I (macOS 為 Cmd + Option + I ) 開啟開發者工具, 在 DevTools 中點選 Application 分頁 (若面板過窄可能藏在山形圖示後)。點選目前已註冊的 service worker 旁的 Unregister , 然後重新載入頁面。

在 Firefox 的 DevTools 中取消註冊 service worker

在 Firefox 的 DevTools 中取消註冊 service worker

匯出選項

完整的可用匯出選項列表請見 EditorExportPlatformWeb 類別參考。