为 Web 导出

参见

本页面描述的是如何将 Godot 项目导出到 HTML5。如果你想要从源码编译编辑器或导出模板二进制文件，请移步《为 Web 平台编译》。

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.

注意

Projects written in C# using Godot 4 currently cannot be exported to the web. See this blog post for more information.

To use C# on web platforms, use Godot 3 instead.

小技巧

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

If the shortcut doesn't work, it's because Godot actually captures the input. You can still open the developer console by accessing the browser's menu.

备注

Due to security concerns with SharedArrayBuffer due to various exploits, the use of multiple threads for the Web platform has multiple drawbacks, including requiring specific server-side headers and complete cross-origin isolation (meaning no ads, nor third-party integrations on the website hosting your game).

Since Godot 4.3, Godot supports exporting your game on a single thread, which solves this issue. While it has some drawbacks on its own (it cannot use threads, and is not as performant as the multi-threaded export), it doesn't require as much overhead to install. It is also more compatible overall with stores like itch.io <https://itch.io/> or Web publishers like Poki or CrazyGames. The single-threaded export works very well on macOS and iOS too, where it always had compatibility issues with multiple threads exports.

For these reasons, it is the preferred and now default way to export your games on the Web.

For more information, see this blog post about single-threaded Web export.

参见

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.

WebGL 版本

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 的浏览器版本列表见 Can I use WebGL 2.0。请注意，Safari 对 WebGL 2.0 的支持存在很多问题，这些问题在其他浏览器中并不存在，因此我们推荐尽量使用基于 Chromium 的浏览器或 Firefox。

Mobile considerations

The Web export can run on mobile platforms with some caveats. While native Android and iOS exports will always perform better by a significant margin, the Web export allows people to run your project without going through app stores.

Remember that CPU and GPU performance is at a premium when running on mobile devices. This is even more the case when running a project exported to Web (as it's WebAssembly instead of native code). See 性能 section of the documentation for advice on optimizing your project. If your project runs on platforms other than Web, you can use 功能标签 to apply low-end-oriented settings when running the project exported to Web.

To speed up loading times on mobile devices, you should also compile an optimized export template with unused features disabled. Depending on the features used by your project, this can reduce the size of the WebAssembly payload significantly, making it faster to download and initialize (even when cached).

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.

导出选项

如果可以使用可运行的Web导出模板, 则编辑器中的 停止场景 和 播放编辑的场景 按钮之间会出现一个按钮, 可以在默认浏览器中快速打开游戏进行测试.

如果你的项目使用 GDExtension，则需要启用 Extension Support。

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页面. 请参阅 导出自定义 HTML 页面.

Head Include 被附加到生成的HTML页面的 <head> 元素中. 例如, 这允许加载webfonts和第三方JavaScript APIs, 包括CSS或运行JavaScript代码.

重要

每个项目必须生成他们自己的HTML文件。在导出时，几个文本占位符会在生成的HTML文件中被替换，专门用于给定的导出选项。任何对该HTML文件的直接修改都会在以后的导出中丢失。要自定义生成的文件，请使用** 自定义HTML shell**选 项。

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游戏移植到Web时应注意的限制.

重要

浏览器供应商正在使越来越多的功能只在 安全上下文 中可用，这意味着这些功能只有在通过安全的HTTPS连接提供网页时才可用（localhost通常不受这种要求影响）。

使用 cookie 进行数据持久化

如果需要持久化 user:// 文件系统, 用户必须 允许cookie (特别是IndexedDB). 当玩 iframe 中呈现的游戏时, 还必须启用 第三方 cookie. 隐身/隐私浏览模式也会防止持久性.

方法 OS.is_userfs_persistent() 可用于检查 user:// 文件系统是否持久, 但在某些情况下会误报.

后台处理

这个标签页不再是用户浏览器的活动标签页时，项目就会被浏览器暂停。也就是说不会运行 _process()、_physics_process() 等函数，除非用户重新激活了这个标签页（切换到这个标签页）。如果用户在标签页外停留了过长的时间，就可能造成网络游戏的掉线。

这一限制不适用于丢失焦点的浏览器窗口。因此，对于用户而言，变通方法是让项目运行在一个单独的窗口中，而不是标签页。

全屏和鼠标捕获

浏览器不允许任意进入全屏，捕获光标也是如此。这些操作只能在响应 JavaScript 输入事件时进行。在 Godot 中，这意味着需要在 _input、_unhandled_input 等输入事件回调中进入全屏。查询 Input 单例并不满足这一条件，相关的输入事件必须处于活动状态。

出于同样的原因, 除非从有效的输入事件处理程序中启动引擎, 否则全屏项目设置将不起作用. 这需要 定制HTML 页面.

音频

一些浏览器限制网站上的音频自动播放。绕过这一限制的最简单方法是请求玩家点击、点击或按下一个键/按钮以启用音频，例如在游戏开始时显示启动屏幕时。

参见

Google offers additional information about their Web Audio autoplay policies.

苹果的 Safari 团队也针对他们 对 macOS 自动播放策略的调整发布了额外说明。

警告

访问麦克风需要安全上下文。

警告

Since Godot 4.3, by default Web exports will use samples instead of streams to play audio.

This is due to the way browsers prefer to play audio and the lack of processing power available when exporting Web games with the Use Threads export option off.

Please note that audio effects aren't yet implemented for samples.

网络

Low-level networking is not implemented due to lacking support in browsers.

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

HTTP类在HTML5平台上也有若干限制:

  • 无法访问或更改 StreamPeer

  • Threaded/Blocking 模式不可用

  • 每帧不能进行多次, 因此循环中的轮询将冻结

  • 没有分块响应

  • 无法禁用主机验证

  • 遵循 同源政策

剪贴板

在引擎和操作系统之间同步剪贴板需要浏览器 剪贴板 API ，此外，由于该 API 的异步性，从 GDScript 访问时可能不可靠。

警告

需要安全上下文。

游戏手柄

按下游戏手柄上面的任一按钮之后，这个游戏手柄才能被检测到。根据浏览器、操作系统、游戏手柄三者的组合不同，游戏手柄的映射可能有误，可惜由于隐私方面的考虑， 游戏手柄 API 并没有提供可靠的方法来检测游戏手柄的信息，因而无法根据模型、供应商、操作系统来进行重新映射。

警告

需要安全上下文。

提供文件

导出为Web生成多个要从Web服务器提供的文件, 包括用于演示的默认HTML页面. 可以使用自定义HTML文件, 请参阅 导出自定义 HTML 页面 .

警告

Only when exporting with Use Threads, to ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports 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, 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.

生成的 .html 文件可以在 Apache 服务器中用作 DirectoryIndex，文件名可以随便修改，比如可以改成 index.html。默认情况下不会用到这个名称。

HTML页面在浏览器窗口内以最大尺寸绘制游戏. 这样, 就可以将其插入游戏大小的 <iframe> 中, 这在大多数网络游戏托管站点中很常见.

The other exported files are served as they are, next to the .html file, names unchanged. The .wasm file is a binary WebAssembly module implementing the engine. The .pck file is the Godot main pack containing your game. The .js file contains start-up code and is used by the .html file to access the engine. The .png file contains the boot splash image.

.pck 文件是二进制文件, 通常与MIME类型 application/octet-stream 一起分发. .wasm 文件以 application/wasm 分发.

警告

分发WebAssembly模块(.wasm)时, 使用一个 application/wasm 以外的MIME类型, 可能会阻止某些启动优化.

建议使用服务器端压缩来分发文件，特别是 .pck 和 .wasm 文件，因为这种文件通常很大。WebAssembly 模块的压缩做得特别好，使用 gzip 压缩最多能够缩小到原始大小的四分之一左右。如果 Web 服务器支持的话，请考虑使用 Brotli 预压缩，能够进一步节省文件大小。

提供即时压缩的主机: GitHub Pages (gzip)

Hosts that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

小技巧

Godot 的仓库中包含了一个用来运行本地 Web 服务器的 Python 脚本。这个脚本原本是用于测试 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 交互并访问一些独特的 Web 浏览器功能。

环境变量

你可以使用以下环境变量在编辑器外部设置导出选项。在导出过程中，这些值会覆盖你在导出菜单中设置的值。

HTML5 导出环境变量

导出选项

环境变量

加密 / 密钥

GODOT_SCRIPT_ENCRYPTION_KEY