Godot 导出 Web 版,那些文档里没写的坑
本地双击能跑,传到服务器就白屏。记录一次 Godot 4 网页导出从白屏到跑通的排查过程。
第一次把 Godot 项目导出成网页版时,我在本地用 python -m http.server 打开是正常的,传上去就白屏。浏览器控制台一行红字,看不出所以然。
这篇记录一下最后查出来的东西,免得下次再走一遍。
一句话结论
Godot 4 的网页导出依赖正确的 MIME 类型和压缩编码。本地那个临时服务器什么都没配,反而因为“什么都没声明”而碰巧能用;nginx 一行默认配置就会毁掉它。
第一个坑:.wasm 被当成了下载文件
nginx 默认的 MIME 表里没有 .wasm,返回的是 application/octet-stream。浏览器拿到这个类型不会去实例化 WebAssembly,直接沉默。
加一行就行:
types {
application/wasm wasm;
application/javascript js mjs;
application/octet-stream pck;
}
.pck 用 octet-stream 没问题,它是当二进制读的。
第二个坑:.wasm.gz 的双重压缩
Godot 导出时会生成 .wasm 和 .wasm.gz 两份。如果你在 nginx 里开了 gzip on,而文件本身已经是 gzip 的,就会出现压缩包被当成普通文件再压一遍的情况,浏览器解出来是乱的。
有两种处理方式,选一种:
- 服务器端不压缩
.gz文件,只在响应头声明Content-Encoding: gzip - export 时选 Extensions 里的 “No compression”,让服务器自己去 gzip
我选的是第二种,配置更少:
location /games/ {
gzip on;
gzip_types application/wasm application/javascript application/octet-stream;
add_header Cross-Origin-Opener-Policy "same-origin";
add_header Cross-Origin-Embedder-Policy "require-corp";
}
关于那两个 Cross-Origin 头
如果你的项目用了多线程(Godot 4 的 Thread Support 打开),它需要 SharedArrayBuffer,而浏览器只在“跨源隔离”的环境里才给这个能力。上面那两个头就是用来声明隔离的。
但注意:一旦加上,页面里所有跨源资源都必须带 CORS 头,否则会被拦。如果你只是嵌一个游戏,可以不打开多线程导出,就完全不需要这两个头——单线程的性能损失对小游戏来说通常可以接受。
我个人的建议:先单线程跑通,真的卡了再考虑多线程。
第三个坑:首屏加载没有反馈
.pck 有几 MB 到几十 MB,网速一般的话有三到十秒纯白屏。用户会以为坏了。
Godot 的网页模板自带一个进度条,但它默认是 Godot 灰。改起来很简单,在导出设置里把 Custom HTML Shell 指向你改过的模板,找到这段 CSS:
#status {
display: flex;
align-items: center;
justify-content: center;
height: 100vh;
color: #8b5cf6;
font-family: monospace;
}
第四个坑:音频要用户先点一下
浏览器的自动播放策略决定了:没有用户交互,AudioContext 是挂起状态。游戏进去没声音,不是导出坏了。
标准做法是在启动画面前加一层“点击开始”,或者监听第一次 pointerdown 再恢复音频上下文。
第五个坑:键盘事件被父页面吃掉
如果你用 iframe 嵌入游戏,方向键和空格会先被父页面滚动抢走。给 iframe 加 allow="fullscreen" 之外,还要在获得焦点后才可靠:
<iframe
src="/games/my-game/index.html"
title="游戏"
allow="fullscreen; autoplay; gamepad"
tabindex="0"
></iframe>
并且在游戏页里监听 pointerdown 后主动 focus() 一次。
排查顺序
下次再白屏,按这个顺序看:
- F12 → Network,看
.wasm的响应类型和状态码 - Console,看是不是
CompileError或MIME type报错 - 看
Content-Encoding有没有和文件实际编码对上 - 最后才怀疑代码
大部分问题在第二步就能定位。真正的引擎 bug 概率很低,配置错才是常态。