godot-export

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot Export & Builds (4.x)

Godot 导出与构建（4.x）

Turn a project into runnable platform builds via export presets and the command line, and handle the web/dedicated-server gotchas. Targets Godot 4.3+.

通过导出预设和命令行将项目转换为可运行的平台构建包，并解决Web/专用服务器相关的疑难问题。适用于**Godot 4.3+**版本。

When to use

适用场景

Use when producing a shippable build: installing export templates, creating/editing export presets, exporting from the editor or headless CLI (CI), or troubleshooting web (HTML5) and dedicated-server exports.

When not to use: storefront publishing flows →

steam-publish

itch-publish

; the networking code of a server →

godot-multiplayer

(this skill covers building it headless).

适用于生成可分发的构建包时：安装导出模板、创建/编辑导出预设、从编辑器或无头CLI（CI）导出，或排查Web（HTML5）和专用服务器导出问题。

不适用场景：商店发布流程 → 请使用

steam-publish

itch-publish

；服务器的网络代码 → 请使用

godot-multiplayer

（本技能仅涵盖无头构建的相关内容）。

Core workflow

核心工作流程

Install export templates matching your engine version: Editor menu > Manage Export Templates (download), or install the
```
.tpz
```
offline. Versions must match the editor exactly.
Add export presets in Project > Export: pick a platform (Windows Desktop, macOS, Linux, Web, Android, iOS), set the export path, icons, features, and resource include/exclude filters. Presets are saved to
```
export_presets.cfg
```
.
Export from the editor with Export Project (release) or Export PCK/ZIP.
Or export headless from the CLI for automation/CI using
```
--export-release "<preset name>" <output path>
```
.
Per platform: Web needs cross-origin isolation (COOP/COEP) for threads; Android needs the SDK/keystore; macOS/iOS need signing for distribution.
Smoke-test the build on the target before shipping — exported builds use
```
res://
```
read-only; write to
```
user://
```
.

安装与引擎版本匹配的导出模板：通过编辑器菜单 > Manage Export Templates（下载），或离线安装
```
.tpz
```
文件。模板版本必须与编辑器版本完全一致。
添加导出预设：在Project > Export中操作：选择平台（Windows Desktop、macOS、Linux、Web、Android、iOS），设置导出路径、图标、功能以及资源包含/排除过滤器。预设将保存至
```
export_presets.cfg
```
。
从编辑器导出：使用Export Project（发布版）或Export PCK/ZIP功能。
或通过无头CLI导出：用于自动化/CI场景，命令为
```
--export-release "<preset name>" <output path>
```
。
各平台注意事项：Web平台需要跨源隔离（COOP/COEP）以支持线程；Android平台需要配置SDK/密钥库；macOS/iOS平台需要签名才能分发。
发布前在目标平台进行冒烟测试：导出的构建包中
```
res://
```
为只读；请写入
```
user://
```
路径。

Patterns

实践模式

1. Headless CLI export (CI-friendly)

1. 无头CLI导出（适配CI）

bash

undefined

bash

undefined

Preset name must match exactly what's in Project > Export (quote it).

Run from the project directory (where project.godot lives).

godot --headless --export-release "Windows Desktop" build/windows/game.exe godot --headless --export-release "Linux/X11" build/linux/game.x86_64 godot --headless --export-release "Web" build/web/index.html

Debug build (includes debug symbols / remote debug):

godot --headless --export-debug "Windows Desktop" build/windows/game_debug.exe

Export only the data pack (no executable):

godot --headless --export-pack "Linux/X11" build/game.pck

undefined

godot --headless --export-pack "Linux/X11" build/game.pck

undefined

2. Run a project headless (dedicated server / tests)

2. 无头运行项目（专用服务器/测试）

bash

undefined

bash

undefined

No window/GPU — for a server build or automated runs.

godot --headless --path . res://server_main.tscn

Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:

godot --headless --path . --quit-after 600

undefined

godot --headless --path . --quit-after 600

undefined

3. Detect the build context at runtime

3. 在运行时检测构建环境

gdscript

func _ready() -> void:
    if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
        _start_server_only()          # skip rendering/UI on a headless server
    if OS.has_feature("web"):
        _apply_web_tweaks()
    # Custom feature tags (added per preset) are also queryable:
    # if OS.has_feature("demo"): limit_content()

gdscript

func _ready() -> void:
    if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
        _start_server_only()          # skip rendering/UI on a headless server
    if OS.has_feature("web"):
        _apply_web_tweaks()
    # Custom feature tags (added per preset) are also queryable:
    # if OS.has_feature("demo"): limit_content()

4. Choose write paths that survive export

4. 选择可在导出后正常使用的写入路径

gdscript

undefined

gdscript

undefined

res:// is READ-ONLY in exported games. Always write to user://.

func save_path() -> String: return "user://savegame.tres" # resolves to the OS app-data dir

func _ready() -> void: print(OS.get_user_data_dir()) # where user:// actually lives

undefined

func save_path() -> String: return "user://savegame.tres" # resolves to the OS app-data dir

func _ready() -> void: print(OS.get_user_data_dir()) # where user:// actually lives

undefined

Pitfalls

常见陷阱

"No export template found". Templates must match the exact editor version (incl. beta/rc). Re-download via Manage Export Templates after upgrading Godot.
Preset name mismatch in CLI.
```
--export-release "Windows"
```
fails if the preset is named
```
"Windows Desktop"
```
. Names are case- and space-sensitive; quote them.
Web build shows a blank page / threads error. HTML5 builds that use threads require the server to send
```
Cross-Origin-Opener-Policy: same-origin
```
and
```
Cross-Origin-Embedder-Policy: require-corp
```
(cross-origin isolation for
```
SharedArrayBuffer
```
). Must be served over HTTP(S), not opened as a
```
file://
```
. itch.io has a "SharedArrayBuffer support" toggle for this.
Writing to
res://
at runtime fails in exports (read-only, packed). Use
```
user://
```
.
Missing resources in the build. Non-resource files (e.g. external
```
.json
```
,
```
.txt
```
) are not auto-included — add them via the preset's Resources > Filters to export non-resource files (e.g.
```
*.json
```
).
Android export needs setup: Android SDK/JDK paths in Editor Settings, a debug or release keystore, and the
```
INTERNET
```
permission for networked games.
macOS/iOS distribution requires signing/notarization; unsigned macOS apps are blocked by Gatekeeper.
Debug vs release.
```
--export-debug
```
enables remote debugging and debug checks; ship
```
--export-release
```
.

"未找到导出模板"：模板版本必须与编辑器版本完全一致（包括beta/rc版本）。升级Godot后，请重新通过Manage Export Templates下载模板。
CLI中的预设名称不匹配：如果预设名称为
```
"Windows Desktop"
```
，则
```
--export-release "Windows"
```
会执行失败。预设名称区分大小写和空格，请用引号包裹。
Web构建显示空白页面/线程错误：使用线程的HTML5构建要求服务器发送
```
Cross-Origin-Opener-Policy: same-origin
```
和
```
Cross-Origin-Embedder-Policy: require-corp
```
（为
```
SharedArrayBuffer
```
提供跨源隔离）。必须通过HTTP(S)服务访问，不能直接打开
```
file://
```
链接。itch.io平台有“SharedArrayBuffer支持”开关可配置此项。
运行时写入
res://
失败：导出的构建包中
```
res://
```
为只读（已打包），请使用
```
user://
```
路径。
构建包中缺少资源：非资源文件（如外部
```
.json
```
、
```
.txt
```
）不会自动包含，请通过预设的Resources > Filters to export non-resource files添加（例如
```
*.json
```
）。
Android导出需要配置：在编辑器设置中指定Android SDK/JDK路径，准备调试或发布用的密钥库，联网游戏还需添加
```
INTERNET
```
权限。
macOS/iOS分发需要签名/公证：未签名的macOS应用会被Gatekeeper阻止。
调试版与发布版的区别：
```
--export-debug
```
启用远程调试和调试检查；发布时请使用
```
--export-release
```
。

References

参考资料

For the
```
export_presets.cfg
```
structure, all useful CLI flags, custom feature tags, PCK/expansion patching, encryption, and per-platform setup (Android keystore, macOS signing, web headers), read
```
references/presets-and-cli.md
```
.

关于
```
export_presets.cfg
```
的结构、所有实用CLI标志、自定义功能标签、PCK/扩展补丁、加密以及各平台配置（Android密钥库、macOS签名、Web头），请阅读
```
references/presets-and-cli.md
```
。

godot-export

Original

Translation

Godot Export & Builds (4.x)

Godot 导出与构建（4.x）

When to use

适用场景

Core workflow

核心工作流程

Patterns

实践模式

1. Headless CLI export (CI-friendly)

1. 无头CLI导出（适配CI）

Preset name must match exactly what's in Project > Export (quote it).

Preset name must match exactly what's in Project > Export (quote it).

Run from the project directory (where project.godot lives).

Run from the project directory (where project.godot lives).

Debug build (includes debug symbols / remote debug):

Debug build (includes debug symbols / remote debug):

Export only the data pack (no executable):

Export only the data pack (no executable):

2. Run a project headless (dedicated server / tests)

2. 无头运行项目（专用服务器/测试）

No window/GPU — for a server build or automated runs.

No window/GPU — for a server build or automated runs.

Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:

Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:

3. Detect the build context at runtime

3. 在运行时检测构建环境

4. Choose write paths that survive export

4. 选择可在导出后正常使用的写入路径

res:// is READ-ONLY in exported games. Always write to user://.

res:// is READ-ONLY in exported games. Always write to user://.

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能