Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

為 Web 匯出

也參考

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

匯出 HTML5 可以將 Godot Engine 做的遊戲發行在瀏覽器上。該功能需要使用者瀏覽器有支援 WebAssemblyWebGL

注意

使用 Godot 4 以 C# 編寫的專案目前無法匯出到 Web。若要在 Web 平台上使用 C#,請改用 Godot 3。

小訣竅

Use the browser-integrated developer console, usually opened with F12 (Cmd + Option + I on macOS), to view debug information like JavaScript, engine, and WebGL errors.

注意

由於 SharedArrayBuffer 和 WebGL 2.0 的上游錯誤,Godot 4 的 HTML5 匯出目前無法在 macOS 和 iOS 上運作。我們建議改用 macOS <doc_exporting_for_macos>` 和 iOS <doc_exporting_for_ios>` 本機匯出功能,因為它也會帶來更好的效能。

一般來說,Godot 3 的 HTML5 匯出與各種瀏覽器更相容,特別是在使用 GLES2 渲染後端(只需要 WebGL 1.0)時。

Godot 版本

Godot 4.0 及更高版本只能針對 WebGL 2.0(使用相容性渲染方法)。目前還沒有穩定的方法在網路上運作 Vulkan 應用程式。

有關支援 WebGL 2.0 的瀏覽器版本列表,請參閱「我可以使用 WebGL 2.0 <https://caniuse.com/webgl2>」。請注意,Safari 在 WebGL 2.0 支援方面存在一些其他瀏覽器不具備的問題,因此我們建議盡可能使用基於 Chromium 的瀏覽器或 Firefox 。

匯出選項

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

如果你打算使用 VRAM compression ,請確保為目標平臺啟用 Vram Texture Compression (同時啟用 For DesktopFor Mobile 將導致更大,但更相容的匯出)。

若有設定 預設 HTML Shell 檔案,則會用這個檔案而非預設 HTML 頁面。請參考 :ref:doc_customizing_html5_shell` 。

Head Include 會被加到產生的 HTML 頁面中 <head> 元素的尾端。這樣便可以達成如載入 Webfont 或第三方 JavaScript API、加上 CSS 或執行 JavaScript 等功能。

重要

每個專案都會產生自己的 HTML 檔案。匯出時,產生的 HTML 檔案 中的各個預留位置都會依據給定的匯出選項取代。若直接修改 產生的 HTML 檔案 ,則未來匯出的時候都會遺失這些修改。若要自定產生的檔案,請參考 匯出自訂 HTML 頁面

限制

由於安全性與隱私權問題,要將許多在原生平台上能輕鬆運作的功能放到 Web 平台上會很複雜。以下列出了一些在將 Godot 遊戲移植到網頁時應注意的限制。

重要

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

使用 Cookie 來保留資料

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

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

背景

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

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

全螢幕與滑鼠截取

瀏覽器不允許任意 進入全螢幕 模式。同樣地,也不允許隨時 截取滑鼠遊標 。這些操作必須要改為用 JavaScript 輸入事件來處理。這代表,在 Godot 中必須要在按鍵輸入事件回呼 (如 _input_unhandled_input) 中才能進入全螢幕。用 :ref:``class_Input``單例來查詢還不夠,必須要啟用相關的輸入事件。

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

音訊

Some browsers restrict autoplay for audio on websites. The easiest way around this limitation is to request the player to click, tap or press a key/button to enable audio, for instance when displaying a splash screen at the start of your game.

也參考

Google 有提供關於 網頁音訊自動播放政策 (英文) 的額外資訊。

Apple's Safari team also posted additional information about their Auto-Play Policy Changes for macOS.

警告

存取麥克風需要:ref:安全本文 <doc_javascript_secure_contexts>

網路

由於缺乏瀏覽器的支援,低級別的網路沒有實作。

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

在 HTML5 平台上,HTTP 類別有一些限制:

  • 無法存取或更改 StreamPeer

  • 無法使用 Threaded/Blocking 模式

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

  • 無法區塊回覆

  • 無法禁用主機驗證

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

剪貼簿

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

警告

需要:ref:安全本文 <doc_javascript_secure_contexts>

遊戲手柄

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

警告

需要:ref:安全本文 <doc_javascript_secure_contexts>

不會顯示啟動畫面

預設 HTML 頁面不會在載入時顯示啟動畫面。但,圖片是匯出為 PNG 檔案,所以 自定 HTML 頁面 可以顯示圖片。

提供檔案

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

警告

To ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports always use SharedArrayBuffer. This requires a secure context, while also requiring the following CORS headers to be set when serving the files:

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

If you don't control the web server or are unable to add response headers, use coi-serviceworker as a workaround.

If the client doesn't receive the required response headers, the project will not run.

The generated .html file can be used as DirectoryIndex in Apache servers and can be renamed to e.g. index.html at any time. Its name is never depended on by default.

The HTML page draws the game at maximum size within the browser window. This way, it can be inserted into an <iframe> with the game's size, as is common on most web game hosting sites.

除了 .html 外其他的檔案都是以原本的樣子來提供,名稱不變。 .wasm 檔案為實作引擎的二進位 WebAssembly 模組。 .pck 檔案則是包含遊戲的 Godot 主要套件。 .js 檔案包含了由 .html 檔案用來存取引擎的啟動程式碼。 .png 檔案包含了啟動畫面,預設的 HTML 頁面不會使用到,但可以用 自定 HTML 頁面 來顯示。

.pck 檔案為二進位形式,通常會以 MIME 型別 application/octet-strem 來傳送。 .wasm 則是 application/wasm

警告

使用 application/wasm 之外的 MIME 型別來傳遞 WebAssembly 模組 (``.wasm`) 可以防止一些啟動最佳化。

Delivering the files with server-side compression is recommended especially for the .pck and .wasm files, which are usually large in size. The WebAssembly module compresses particularly well, down to around a quarter of its original size with gzip compression. Consider using Brotli precompression if supported on your web server for further file size savings.

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

不提供即時壓縮的主機: itch.io, GitLab 頁面 ( 支援手動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 單例。該單例只提供了一個名為 eval 的方法,類似 JavaScript 中相同名稱的函式。該方法接受單一字串參數,會將該字串作為 JavaScript 程式碼來執行。這樣便可用 Godot 整合腳本中無法實作的方法來與瀏覽器互動。

func my_func():
    JavaScriptBridge.eval("alert('Calling JavaScript per GDScript!');")

特定情況下,最後一個 JavaScript 陳述式的回傳值會轉換為 GDScript 值,並由 eval() 回傳:

  • JavaScript number 型會以 GDScript float 回傳

  • JavaScript bool 型會以 GDScript bool 回傳

  • JavaScript string 型會以 GDScript String 回傳

  • JavaScript ArrayBuffer, TypedArrayDataView 型會以 GDScript class_PoolByteArray 回傳

func my_func2():
    var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

其他的 JavaScript 值則會回傳為 null

建置的 HTML5 匯出樣板也有可能為了提升安全性而被 建置 為不支援該單例的版本。當使用這種樣板或是在非 HTML5 的平台上時,呼叫 JavaScript.eval 也會回傳 null 。可以通過 JavaScript 功能標籤 來檢查是否可使用該單例:

func my_func3():
    if OS.has_feature('web'):
        JavaScriptBridge.eval("""
            console.log('The JavaScriptBridge singleton is available')
        """)
    else:
        print("The JavaScriptBridge singleton is NOT available")

小訣竅

GDScript 的多行字串是由三個引號 """ 來包圍,如同上方 my_func3() 中的範例,適用於讓 JavaScript 更容易閱讀。

eval 方法也接受第二個可選的布林參數,可以用來指定是否要在全域執行本文中執行程式碼。預設值為 false ,以防止汙染全域命名空間:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.eval("var SomeGlobal = {};", true)

環境變數

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

環境變數

匯出選項

環境變數

加密/加密金鑰

GODOT_SCRIPT_ENCRYPTION_KEY