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.

編譯至網頁平台

也參考

本頁說明如何從原始碼編譯 HTML5 編輯器與匯出範本的二進位檔。如果你想將專案匯出到 HTML5,請參閱 為 Web 匯出。

系統需求

要編譯網頁平台的匯出樣板,需準備以下項目:

  • Emscripten 6.0.12+。

  • Python 3.10+。

    • 如果使用 Python 3.10 至 3.13,還須執行 pip install --user zstandard,安裝 Python 的 Zstandard 支援。Python 3.14 及更新版本已預設包含 Zstandard 支援,因此不需要此步驟。

  • SCons 4.4+ 建置系統。

也參考

如需取得 Godot 編譯所需的原始碼,請參閱 取得原始碼。

關於 Godot 使用 SCons 的基本說明,請參閱 建置系統介紹。

建構匯出樣板

在開始之前,請確認 emcc 已經加入你的 PATH。這通常會由 Emscripten SDK 設定,例如執行 emsdk activate 以及 source ./emsdk_env.sh 或 emsdk_env.bat 時。

開啟終端機, 切換到引擎原始碼的根目錄。接著透過 SCons 建構網頁平台, 目標 target 可以指定為 template_release (發行版) 或 template_debug (除錯版):

scons platform=web target=template_release
scons platform=web target=template_debug

預設情況下, JavaScriptBridge 單例 會被編譯進引擎中。官方的匯出樣板也會啟用此 JavaScript 單例。由於 eval() 呼叫可能有安全疑慮,你可以使用 javascript_eval 選項來編譯不包含該單例的版本:

scons platform=web target=template_release javascript_eval=no
scons platform=web target=template_debug javascript_eval=no

預設會啟用 WebWorker 執行緒支援。若只想使用單執行緒,可用 threads 選項停用執行緒支援:

scons platform=web target=template_release threads=no
scons platform=web target=template_debug threads=no

引擎將會透過 Emscripten 編譯為 WebAssembly。完成後,產生的檔案會放在 bin 子資料夾中。正式版檔名為 godot.web.template_release.wasm32.zip ,除錯版為 godot.web.template_debug.wasm32.zip 。

最後,將發行版樣板的 ZIP 檔重新命名為 web_release.zip:

mv bin/godot.web.template_release.wasm32.zip bin/web_release.zip

除錯版樣板則重新命名為 web_debug.zip:

mv bin/godot.web.template_debug.wasm32.zip bin/web_debug.zip

GDExtension

出於效能與相容性考量,預設匯出範本不包含 GDExtension 支援。詳情請參閱 網頁匯出選項。

你可以加上 dlink_enabled=yes 選項,建構支援 GDExtension 的匯出樣板:

scons platform=web dlink_enabled=yes target=template_release
scons platform=web dlink_enabled=yes target=template_debug

完成後,產生的檔案會放在 bin 子目錄中,檔名會加入 .dlink。

最後, 請將壓縮檔重新命名為 web_dlink_release.zip (發行版) 與 web_dlink_debug.zip (除錯版)。

mv bin/godot.web.template_release.wasm32.dlink.zip bin/web_dlink_release.zip
mv bin/godot.web.template_debug.wasm32.dlink.zip bin/web_dlink_debug.zip

建構編輯器

也可以編譯一個可於瀏覽器執行的 Godot 編輯器版本。一般不建議以此取代原生版本。你可以這樣建構瀏覽器版編輯器:

scons platform=web target=editor

完成後,產生的檔案會放在 bin 子資料夾,檔名為 godot.web.editor.wasm32.zip。你可以將解壓後的內容上傳到你的 Web 伺服器,然後用瀏覽器開啟以使用編輯器。

關於網頁伺服器需求,請參閱 網頁匯出選項。

小訣竅

Godot 原始碼庫內附有一個 Python 本地網頁伺服器腳本,可用來在本機測試網頁版編輯器。

編譯完編輯器後,先解壓縮 bin/ 資料夾中的 ZIP 檔,再於 Godot 原始碼根目錄執行以下指令:

# You may need to replace `python` with `python3` on some platforms.
python platform/web/serve.py

這會提供 bin/ 資料夾的內容並自動開啟預設瀏覽器。在開啟的頁面中存取 godot.editor.html,即可這樣測試網頁編輯器。

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