如何将 Godot 游戏导出到网页端（HTML5 指南，2026年）

Godot 以 HTML5 和 WebAssembly 格式导出到网页端，这意味着你的游戏可以直接在浏览器标签页中运行，无需下载，无需插件。这是把可玩构建分享给别人最快的方式：发一个链接，对方点开就能玩。

问题在于，「导出到网页端」其实是两件事，不是一件。生成文件很简单，大约一分钟就能搞定。但让这些文件真正在浏览器中运行，才是大多数人遇到黑屏的地方，因为现代浏览器要求提供两个特定的 HTTP 请求头，而多线程 WebAssembly 构建依赖这两个请求头才能工作。本指南涵盖这两个环节、具体的设置方法，以及导致大多数导出失败的三种错误。

本指南适用于 Godot 4 以及 Summer Engine。Summer Engine 与 Godot 4 兼容，使用相同的导出流程。如果你的游戏是用自然语言描述构建的，导出步骤与手写代码的 Godot 项目完全相同。

{/* IMAGE: The Godot Export dialog open with a Web preset selected, the Export Project button highlighted. 1200x675 editor screenshot. */}

网页导出实际生成什么文件

导出时，Godot 不会生成单个文件，而是写出一个包含静态资源的小文件夹：

• index.html 是加载一切的页面，也是浏览器打开的入口。
• .wasm 文件 是编译为 WebAssembly 的 Godot 引擎本体，是体积最大的部分。
• .pck 文件 是你的游戏数据：场景、脚本和资源打包在一起。
• .js 文件 是将引擎连接到页面的加载器胶水代码。
• 通常还有 .worker.js 和 .audio.worklet.js，用于多线程和音频处理。

这些文件必须放在同一目录下，并通过 HTTP 服务访问。不能双击 index.html 就期望它能运行，这是很多人踩到的第一个坑。后面我们会详细说明。

第一步：安装导出模板

Godot 的编辑器和导出模板是分开发布的。导出模板是各平台的预编译引擎二进制文件，包括用于浏览器的 WebAssembly 构建。全新安装时不包含这些模板。

进入 编辑器 然后选择 管理导出模板，点击 下载并安装，即可拉取与你当前引擎版本完全对应的模板。

这是整个流程中最重要的一条规则：模板版本必须与引擎版本完全匹配。 4.3 的模板无法运行从 4.4 导出的项目。版本不匹配是网页构建失败的第二大常见原因，仅次于请求头问题。升级引擎后，必须重新安装模板。

第二步：添加 Web 导出预设

打开 项目 然后选择 导出。点击 添加 并选择 Web。

此时会出现一个选项面板。默认值基本合理，但有两个设置对网页端尤为重要：

• 导出类型。 「Regular」选项给你多线程构建，速度更快，也是默认选项。过去曾有非多线程的回退方案，供无法设置特殊请求头的服务器使用。在 Godot 4 中，几乎永远应该选择多线程构建，然后在服务器端修复请求头问题，具体方法见下文。
• VRAM 贴图压缩。 勾选你关心的目标平台。浏览器在大多数机器上走「桌面端」压缩路径，所以保持开启。移动端浏览器可能还需要勾选移动端压缩选项。

除非有特殊需求，否则 Head Include 和自定义 HTML 外壳保持空白即可。默认外壳会自动处理加载和进度条。

第三步：导出项目

选择一个目标文件夹。新建一个空文件夹，命名为 web-build 之类的名字，让输出文件与其他内容分开。

主文件命名为 index.html，而不是你的游戏名称。包括 itch.io 在内的大多数托管平台会把 index.html 作为入口文件。如果你命名为 mygame.html，服务器找不到它，你看到的将是一个空白目录列表，而不是游戏。

点击 导出项目。几秒钟后，文件夹就会填满前面列出的那些文件。简单的那一半完成了。

{/* IMAGE: A file explorer showing the exported web-build folder contents: index.html, .wasm, .pck, .js files. 1000x500. */}

第四步：请求头问题，直白地说清楚

这是大多数快速教程不会提到的部分，也是大多数初次网页导出出现黑屏的原因。

Godot 4 的多线程构建使用了 SharedArrayBuffer，这是一个让 WebAssembly 引擎在多线程上运行的浏览器特性。出于安全考虑，浏览器只在页面通过两个特定 HTTP 响应头提供服务时才启用 SharedArrayBuffer：

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

这两个请求头会让页面进入浏览器所谓的「跨域隔离」状态。没有它们，SharedArrayBuffer 就是 undefined，引擎无法启动线程，你会看到黑色画布，控制台会出现提到 SharedArrayBuffer is not defined 或 crossOriginIsolated is false 的报错。

这两个请求头不在 Godot 里设置，而是在提供文件的服务器端设置。这就是关键所在。由此引出三个结论：

1. 从硬盘直接打开 index.html 永远不会生效，因为没有服务器来发送请求头。
2. 无法设置自定义请求头的服务器（比如普通的 GitHub Pages）无法直接运行多线程构建。
3. 自动发送这两个请求头的服务器（比如开启了相应选项的 itch.io）直接就能用。

第五步：上传前先在本地测试

不要通过上传再刷新的方式调试网页导出。先在自己的机器上用一个设置了正确请求头的本地服务器测试。

如果你安装了 Python，最快的方式是写一个小脚本，用两个请求头提供文件夹服务。把下面这个脚本保存为 web-build 文件夹里的 serve.py：

import http.server, socketserver

class Handler(http.server.SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header("Cross-Origin-Opener-Policy", "same-origin")
        self.send_header("Cross-Origin-Embedder-Policy", "require-corp")
        super().end_headers()

with socketserver.TCPServer(("", 8000), Handler) as httpd:
    print("Serving on http://localhost:8000")
    httpd.serve_forever()

运行 python serve.py，然后打开 http://localhost:8000。如果游戏在这里能正常加载，说明导出是正确的，剩下的问题都是服务器配置问题，与 Godot 无关。

如果不想写脚本，Godot 编辑器里的 远程调试 运行选项（播放按钮旁的下拉菜单中的「在浏览器中运行」）会自动启动一个配置正确的本地服务器并打开构建。这是开发过程中最快的完整性检查方式。

第六步：托管上线

itch.io（最简单，免费）

这是分享游戏和参加 game jam 的推荐方案。

1. 将整个 web-build 文件夹打包成 zip。注意是打包文件夹的内容，而不是文件夹本身，确保 index.html 位于 zip 的顶层。
2. 在 itch.io 上新建一个项目，将 项目类型 设置为 HTML。
3. 上传 zip 文件，并勾选 此文件将在浏览器中运行。
4. 在嵌入选项中，设置与游戏分辨率匹配的视口尺寸，如果 itch 提供了 SharedArrayBuffer 支持 选项，勾选它（itch 会帮你设置那两个请求头）。

itch.io 会自动处理请求头，这就是它阻力最小的原因。如果游戏在上面的本地脚本测试中能运行，但在 itch 上不行，那几乎可以肯定是 SharedArrayBuffer 开关没勾选。

Netlify、Vercel 或自有服务器

这些服务器支持设置自定义请求头，配置完成后多线程构建就能正常运行。

在 Netlify 上，将 _headers 文件添加到部署根目录：

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

在 Vercel 上，在 vercel.json 的 headers 规则下设置同样的两个请求头。在自己的 nginx 或 Apache 服务器上，将它们添加到对应的 location 块中。原理到处都一样：为页面和资源发送这两个请求头。

GitHub Pages

普通的 GitHub Pages 无法设置自定义请求头，因此多线程构建无法直接在上面运行。有人通过一个小型 service worker 在客户端注入请求头来绕过这个问题（「coi-serviceworker」是常见的解法），但这是一种变通手段，不是每个浏览器都能识别。如果必须用 GitHub Pages，做好添加这个变通方案的准备。否则，用 itch.io 或 Netlify，省去麻烦。

修复黑屏：三问清单

如果你看到黑色画布，打开浏览器开发者控制台（按 F12，然后切到控制台标签），读第一条红色报错。它会对应以下三种原因之一。

1. 你是直接打开文件的吗？ 如果 URL 以 file:// 开头，那就是问题所在。用上面的本地脚本通过 HTTP 提供服务。
2. 报错中提到了 SharedArrayBuffer 或 crossOriginIsolated 吗？ 请求头缺失。在服务器端添加它们，或者勾选 itch.io 的 SharedArrayBuffer 开关。
3. 报错中提到了版本或模板加载失败吗？ 导出模板与引擎版本不匹配。通过「管理导出模板」重新安装。

九成的网页导出失败都是这三种情况之一。按顺序逐一排查，再假设游戏有更深层的 bug。

哪些功能在浏览器中不可用

网页导出是真实可用的，但它不是加了个 URL 的桌面版。有些东西表现会有所不同：

• 文件系统访问 是沙盒化的。存档数据写入浏览器的 IndexedDB，而不是磁盘上的文件夹。如果网页端是你的主要目标，存档系统要围绕这一点设计。
• 原生插件（为桌面端编译的 GDExtension 库）通常在浏览器中无法工作。任何链接了原生 .dll 或 .so 的内容都需要兼容网页的替代方案，或者在网页构建中去掉。
• 加载体积比任何地方都更重要。 在网页端，玩家在游戏启动前需要下载引擎、数据包和所有资源。压缩贴图，删除未用资源，如果网页端是你的主要渠道，要对 3D 项目的规模保持现实预期。一款体量较大的 3D 游戏首次加载可能达到 30 到 100 MB，在移动网络下体验很差。
• 音频延迟 在浏览器中略高于桌面端。通常没有影响，偶尔在节奏要求严格的游戏中会有感知。

如果你的游戏是用 Summer Engine 构建的

上面的导出步骤完全相同，因为 Summer Engine 与 Godot 4 兼容，使用同一套 HTML5 和 WebAssembly 流程。区别在于上游，也就是游戏的构建方式。你不需要手写玩家控制器、场景配置和游戏逻辑，只需用自然语言描述你想要的效果，AI 来构建。准备分享时，按照本文描述的步骤导出到网页端即可。

网页端导出属于免费功能。构建和导出都是免费的，付费计划只涉及更高的 AI 用量和团队协作功能，所以从想法到一个可点击的链接，整个流程尝试起来零成本。

如果你还没有开始项目，到达网页可玩构建的最快路径是：从一个已经配置好移动和摄像机的模板开始，用自然语言描述你想要的游戏机制，然后按照上面六个步骤放到浏览器里。从空白项目到一个可玩的 itch.io 链接，整个过程一个下午就能完成。