Up to date

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

為 Web 匯出

也參考

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

HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for WebAssembly and WebGL 2.0 in the user's browser.

注意

使用 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.

也參考

See the list of open issues on GitHub related to the web export for a list of known bugs.

Export file name

We suggest users to export their Web projects with index.html as the file name. index.html is usually the default file loaded by web servers when accessing the parent directory, usually hiding the name of that file.

注意

The Godot 4 Web export expects some files to be named the same name as the one set in the initial export. Some issues could occur if some exported files are renamed, including the main HTML file.

Godot 版本

Godot 4.0 and later 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.

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

Audio playback

Since Godot 4.3, audio playback is done using the Web Audio API on the web platform. This Sample playback mode allows for low latency even when the project is exported without thread support, but it has several limitations:

  • AudioEffects are not supported.

  • Reverberation and doppler effects are not supported.

  • Procedural audio generation is not supported.

  • Positional audio may not always work correctly depending on the node's properties.

To use Godot's own audio playback system on the web platform, you can change the default playback mode using the Audio > General > Default Playback Type.web project setting, or change the Playback Type property to Stream on an AudioStreamPlayer, AudioStreamPlayer2D or AudioStreamPlayer3D node. This leads to increased latency (especially when thread support is disabled), but it allows the full suite of Godot's audio features to work.

匯出選項

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

If your project uses GDExtension Extension Support needs to be enabled.

If you plan to use VRAM compression make sure that VRAM Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible export).

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

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

重要

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

Thread and extension support

If Thread Support is enabled, the exported project will be able to make use of multithreading to improve performance. This also allows for low-latency audio playback when the playback type is set to Stream (instead of the default Sample that is used in web exports). Enabling this feature requires the use of cross-origin isolation headers, which are described in the 提供檔案 section below.

If Extensions Support is enabled, GDExtensions will be able to be loaded. Note that GDExtensions still need to be specifically compiled for the web platform to work. Like thread support, enabling this feature requires the use of cross-origin isolation headers.

Exporting as a Progressive Web App (PWA)

If Progressive Web App > Enable is enabled, it will have several effects:

  • Configure high-resolution icons, a display mode and screen orientation. These are configured at the end of the Progressive Web App section in the export options. These options are used if the user adds the project to their device's homescreen, which is common on mobile platforms. This is also supported on desktop platforms, albeit in a more limited capacity.

  • Allow the project to be loaded without an Internet connection if it has been loaded at least once beforehand. This works thanks to the service worker that is installed when the project is first loaded in the user's browser. This service worker provides a local fallback when no Internet connection is available.

    • Note that web browsers can choose to evict the cached data if the user runs low on disk space, or if the user hasn't opened the project for a while. To ensure data is cached for a longer duration, the user can bookmark the page, or ideally add it to their device's home screen.

    • If the offline data is not available because it was evicted from the cache, you can configure an Offline Page that will be displayed in this case. The page must be in HTML format and will be saved on the client's machine the first time the project is loaded.

  • Ensure cross-origin isolation headers are always present, even if the web server hasn't been configured to send them. This allows exports with threads enabled to work when hosted on any website, even if there is no way for you to control the headers it sends.

    • This behavior can be disabled by unchecking Enable Cross Origin Isolation Headers in the Progressive Web App section.

限制

由於安全性與隱私權問題，要將許多在原生平台上能輕鬆運作的功能放到 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 頁面 。

警告

If either thread support or extension support are enabled, the exported project will require 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, check Progressive Web App > Enable in the export options. This applies a service worker-based workaround that allows the project to run by simulating the presence of these response headers. A secure context is still required in this case.

If the client doesn't receive the required response headers or the service worker-based workaround is not applied, 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。

Interacting with the browser and JavaScript

See the dedicated page on how to interact with JavaScript and access some unique Web browser features.

環境變數

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

環境變數

匯出選項

環境變數

加密/加密金鑰

GODOT_SCRIPT_ENCRYPTION_KEY