godot-export

Godot 导出与构建（4.x）

通过导出预设和命令行将项目打包为可运行的平台版本，并处理 Web／专用服务器相关注意事项。目标版本为 Godot 4.7。

适用场景

• 用于制作可发布的构建：安装导出模板、创建／编辑导出预设、从编辑器或无头 CLI（CI）导出，或排查 Web（HTML5）和专用服务器导出问题。

不适用场景： 商店发布流程 → steam-publish／itch-publish；服务器的网络代码 → godot-multiplayer（本技能涵盖无头构建）。

核心工作流

1. 安装与引擎版本匹配的导出模板： 从编辑器菜单 > Manage Export Templates 下载，或离线安装 .tpz。版本必须与编辑器完全匹配。
2. 添加导出预设： 在 Project > Export 中选择平台（Windows Desktop、macOS、Linux、Web、Android、iOS），设置导出路径、图标、功能以及资源包含／排除过滤器。预设会保存到 export_presets.cfg。
3. 从编辑器导出： 使用 Export Project（发布版）或 Export PCK/ZIP。
4. 或者从 CLI 无头导出： 使用 --export-release "<preset name>" <output path> 进行自动化／CI 导出。
5. 按平台处理： Web 的多线程需要跨源隔离（COOP/COEP）；Android 需要 SDK／密钥库；macOS／iOS 分发需要签名。
6. 发布前在目标平台上对构建进行冒烟测试——导出的构建中 res:// 为只读；请写入 user://。

常用模式

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

# 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

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

# 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

3. 在运行时检测构建上下文

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. 选择可在导出后继续使用的写入路径

# 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

注意事项

• “No export template found”。 模板必须与编辑器版本完全匹配（包括 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 support”开关。
• 在运行时写入 res:// 会在导出版本中失败（只读、已打包）。请使用 user://。
• 构建中缺少资源。 非资源文件（例如外部 .json、.txt）不会自动包含——请通过预设中的 Resources > Filters to export non-resource files 添加（例如 *.json）。
• Android 导出需要进行设置：在 Editor Settings 中设置 Android SDK／JDK 路径，准备调试或发布密钥库，并为联网游戏启用 INTERNET 权限。
• macOS／iOS 分发需要签名／公证；未签名的 macOS 应用会被 Gatekeeper 拦截。
• 调试版与发布版。 --export-debug 会启用远程调试和调试检查；发布时请使用 --export-release。

参考资料

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

相关技能

• godot-multiplayer — 导出为无头构建的专用服务器代码。
• steam-publish／itch-publish — 将构建发布给玩家。
• prototype-fast／game-jam — 用于分享的快速 Web／桌面构建。