Expert guidance for building and distributing Godot games across platforms.
- NEVER export without testing on target platform first — "Works on my machine" doesn't mean it works on Windows/Linux/Android. Test early and often.
- NEVER use debug builds for release — Debug builds are 5-10x larger and slower. Always export with --export-release for production.
- NEVER hardcode file paths in exports — Use and paths. Absolute paths () break on other machines.
- NEVER skip code signing on macOS — Unsigned macOS apps trigger Gatekeeper warnings. Users won't run your game.
- NEVER include editor-only files in exports — Exclude , , via export filters. Reduces build size by 20-50%.
- 绝对禁止未在目标平台测试就导出 — “在我机器上能运行”不代表在Windows/Linux/Android上也能运行。尽早并频繁测试。
- 绝对禁止使用调试构建版本发布 — 调试构建版本的体积是正式版的5-10倍，运行速度更慢。生产环境务必使用--export-release参数导出。
- 绝对禁止在导出中硬编码文件路径 — 使用和路径。绝对路径（如）在其他机器上会失效。
- 绝对禁止跳过macOS的代码签名 — 未签名的macOS应用会触发Gatekeeper警告，用户将无法运行你的游戏。
- 绝对禁止在导出中包含编辑器专属文件 — 通过导出过滤器排除、、文件。可将构建体积缩减20-50%。
MANDATORY: Read the appropriate script before implementing the corresponding pattern.
version_manager.gd
version_manager.gd
AutoLoad for managing game version, build hash, and window titles.
用于管理游戏版本、构建哈希值和窗口标题的AutoLoad脚本。
headless_build.sh
headless_build.sh
CI/CD headless export script. Automates version injection, godot --headless --export-release, code signing, and butler deployment.
适用于CI/CD的无头模式导出脚本。可自动完成版本注入、godot --headless --export-release、代码签名以及butler部署。
Install via Editor:
Editor → Manage Export Templates → Download
通过编辑器安装：
编辑器 → 管理导出模板 → 下载
Create Export Preset
创建导出预设
- Project → Export
- Add preset (Windows, Linux, etc.)
- Configure settings
- Export Project
- 项目 → 导出
- 添加预设（Windows、Linux等）
- 配置设置
- 导出项目
Format: .exe (single file) or .pck + .exe
格式：.exe（单文件）或 .pck + .exe
Include: *.import, *.tres, *.tscn
包含文件：*.import, *.tres, *.tscn
Export Type: Regular or GDExtension
导出类型：常规或GDExtension
Thread Support: For SharedArrayBuffer
线程支持：用于SharedArrayBuffer
VRAM Compression: Optimized for size
VRAM压缩：针对体积优化
Export Presets File
导出预设文件
export_presets.cfg
export_presets.cfg
[preset.0]
name="Windows Desktop"
platform="Windows Desktop"
runnable=true
export_path="builds/windows/game.exe"
[preset.0.options]
binary_format/64_bits=true
application/icon="res://icon.ico"
[preset.0]
name="Windows Desktop"
platform="Windows Desktop"
runnable=true
export_path="builds/windows/game.exe"
[preset.0.options]
binary_format/64_bits=true
application/icon="res://icon.ico"
Export from command line
从命令行导出
godot --headless --export-release "Windows Desktop" builds/game.exe
godot --headless --export-release "Windows Desktop" builds/game.exe
Export debug build
导出调试构建版本
godot --headless --export-debug "Windows Desktop" builds/game_debug.exe
godot --headless --export-debug "Windows Desktop" builds/game_debug.exe
PCK only (for patching)
仅导出PCK文件（用于补丁更新）
godot --headless --export-pack "Windows Desktop" builds/game.pck
godot --headless --export-pack "Windows Desktop" builds/game.pck
- Android SDK
- Android SDK
Export → Android → SDK Path
导出 → Android → SDK路径
Export → Android → Keystore
导出 → Android → 密钥库
- macOS with Xcode
- 安装Xcode的macOS系统
- Apple Developer account
- Apple开发者账号
- Provisioning profile
- 描述文件
Export creates .xcodeproj
导出会生成.xcodeproj文件
Build in Xcode for App Store
在Xcode中构建用于App Store发布的版本
Codesign: Developer ID certificate
代码签名：开发者ID证书
Notarization: Required for distribution
公证：分发时必须完成
Architecture: Universal (Intel + ARM)
架构：通用架构（Intel + ARM）
Check platform at runtime
在运行时检查平台
if OS.get_name() == "Windows":
# Windows-specific code
pass
if OS.has_feature("web"):
# Web build
pass
if OS.has_feature("mobile"):
# Android or iOS
pass
if OS.get_name() == "Windows":
# Windows专属代码
pass
if OS.has_feature("web"):
# Web构建版本
pass
if OS.has_feature("mobile"):
# Android或iOS平台
pass
Project Settings for Export
导出用项目设置
project.godot
project.godot
[application]
config/name="My Game"
config/version="1.0.0"
run/main_scene="res://scenes/main.tscn"
config/icon="res://icon.svg"
[rendering]
[application]
config/name="My Game"
config/version="1.0.0"
run/main_scene="res://scenes/main.tscn"
config/icon="res://icon.svg"
[rendering]
Optimize for target platforms
针对目标平台优化
textures/vram_compression/import_etc2_astc=true # Mobile
textures/vram_compression/import_etc2_astc=true # 移动平台
Remove unused imports
移除未使用的导入资源
Project Settings → Editor → Import Defaults
项目设置 → 编辑器 → 导入默认设置
Exclude editor-only files
排除编辑器专属文件
In export preset: Exclude filters
在导出预设中设置：排除过滤器
Strip Debug Symbols
剥离调试符号
Export preset options:
导出预设选项：
Debugging → Debug: Off
调试 → 调试模式：关闭
Binary Format → Architecture: 64-bit only
二进制格式 → 架构：仅64位
CI/CD with GitHub Actions
基于GitHub Actions的CI/CD
.github/workflows/export.yml
.github/workflows/export.yml
name: Export Godot Game
on:
push:
tags: ['v*']
jobs:
export:
runs-on: ubuntu-latest
container:
image: barichello/godot-ci:4.2.1
steps:
- uses: actions/checkout@v4
- name: Export Windows
run: |
mkdir -p builds/windows
godot --headless --export-release "Windows Desktop" builds/windows/game.exe
- name: Upload Artifact
uses: actions/upload-artifact@v3
with:
name: windows-build
path: builds/windows/
name: Export Godot Game
on:
push:
tags: ['v*']
jobs:
export:
runs-on: ubuntu-latest
container:
image: barichello/godot-ci:4.2.1
steps:
- uses: actions/checkout@v4
- name: Export Windows
run: |
mkdir -p builds/windows
godot --headless --export-release "Windows Desktop" builds/windows/game.exe
- name: Upload Artifact
uses: actions/upload-artifact@v3
with:
name: windows-build
path: builds/windows/
version.gd (AutoLoad)
version.gd（AutoLoad）
extends Node
const VERSION := "1.0.0"
const BUILD := "2024.02.06"
func get_version_string() -> String:
return "v" + VERSION + " (" + BUILD + ")"
extends Node
const VERSION := "1.0.0"
const BUILD := "2024.02.06"
func get_version_string() -> String:
return "v" + VERSION + " (" + BUILD + ")"
1. Test Export Early
1. 尽早测试导出
Export to all target platforms early
Catch platform-specific issues fast
2. Use .gdignore
2. 使用.gdignore
Exclude folders from export
从导出中排除文件夹
Create .gdignore in folder
在目标文件夹中创建.gdignore文件
3. Separate Debug/Release
3. 区分调试版与正式版
Debug: Keep logs, dev tools
Release: Strip debug, optimize size
调试版：保留日志、开发工具
正式版：剥离调试信息、优化体积
- Master Skill: godot-master