Back to Details

godot-export-builds

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Export & Builds

导出与构建

Expert guidance for building and distributing Godot games across platforms.
针对跨平台构建和分发Godot游戏的专业指南。

NEVER Do

绝对禁止操作

  • 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 
    res://
    and 
    user://
    paths. Absolute paths (
    C:/Users/...
    ) 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 
    .md
    , 
    docs/*
    , 
    .git
    via export filters. Reduces build size by 20-50%.
  • 绝对禁止未在目标平台测试就导出 — “在我机器上能运行”不代表在Windows/Linux/Android上也能运行。尽早并频繁测试。
  • 绝对禁止使用调试构建版本发布 — 调试构建版本的体积是正式版的5-10倍，运行速度更慢。生产环境务必使用--export-release参数导出。
  • 绝对禁止在导出中硬编码文件路径 — 使用
    res://
    和
    user://
    路径。绝对路径（如
    C:/Users/...
    ）在其他机器上会失效。
  • 绝对禁止跳过macOS的代码签名 — 未签名的macOS应用会触发Gatekeeper警告，用户将无法运行你的游戏。
  • 绝对禁止在导出中包含编辑器专属文件 — 通过导出过滤器排除
    .md
    、
    docs/*
    、
    .git
    文件。可将构建体积缩减20-50%。

Available Scripts

可用脚本

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部署。

Export Templates

导出模板

Install via Editor: Editor → Manage Export Templates → Download
通过编辑器安装： 编辑器 → 管理导出模板 → 下载

Basic Export Setup

基础导出设置

Create Export Preset

创建导出预设

  1. Project → Export
  2. Add preset (Windows, Linux, etc.)
  3. Configure settings
  4. Export Project
  1. 项目 → 导出
  2. 添加预设（Windows、Linux等）
  3. 配置设置
  4. 导出项目

Windows Export

Windows导出

ini
undefined
ini
undefined

Export settings

导出设置

Format: .exe (single file) or .pck + .exe

格式：.exe（单文件）或 .pck + .exe

Icon: .ico file

图标：.ico文件

Include: *.import, *.tres, *.tscn

包含文件：*.import, *.tres, *.tscn

undefined
undefined

Web Export

Web导出

ini
undefined
ini
undefined

Settings:

设置：

Export Type: Regular or GDExtension

导出类型：常规或GDExtension

Thread Support: For SharedArrayBuffer

线程支持：用于SharedArrayBuffer

VRAM Compression: Optimized for size

VRAM压缩：针对体积优化

undefined
undefined

Export Presets File

导出预设文件

ini
undefined
ini
undefined

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"
undefined
[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"
undefined

Command-Line Export

命令行导出

powershell
undefined
powershell
undefined

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
undefined
godot --headless --export-pack "Windows Desktop" builds/game.pck
undefined

Platform-Specific

平台专属设置

Android

Android

ini
undefined
ini
undefined

Requirements:

要求：

- Android SDK

- Android SDK

- OpenJDK 17

- OpenJDK 17

- Debug keystore

- 调试密钥库

Editor Settings:

编辑器设置：

Export → Android → SDK Path

导出 → Android → SDK路径

Export → Android → Keystore

导出 → Android → 密钥库

undefined
undefined

iOS

iOS

ini
undefined
ini
undefined

Requirements:

要求：

- macOS with Xcode

- 安装Xcode的macOS系统

- Apple Developer account

- Apple开发者账号

- Provisioning profile

- 描述文件

Export creates .xcodeproj

导出会生成.xcodeproj文件

Build in Xcode for App Store

在Xcode中构建用于App Store发布的版本

undefined
undefined

macOS

macOS

ini
undefined
ini
undefined

Settings:

设置：

Codesign: Developer ID certificate

代码签名：开发者ID证书

Notarization: Required for distribution

公证：分发时必须完成

Architecture: Universal (Intel + ARM)

架构：通用架构（Intel + ARM）

undefined
undefined

Feature Flags

功能标志

gdscript
undefined
gdscript
undefined

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
undefined
if OS.get_name() == "Windows": # Windows专属代码 pass
if OS.has_feature("web"): # Web构建版本 pass
if OS.has_feature("mobile"): # Android或iOS平台 pass
undefined

Project Settings for Export

导出用项目设置

ini
undefined
ini
undefined

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
undefined
textures/vram_compression/import_etc2_astc=true # 移动平台
undefined

Build Optimization

构建优化

Reduce Build Size

缩减构建体积

gdscript
undefined
gdscript
undefined

Remove unused imports

移除未使用的导入资源

Project Settings → Editor → Import Defaults

项目设置 → 编辑器 → 导入默认设置

Exclude editor-only files

排除编辑器专属文件

In export preset: Exclude filters

在导出预设中设置：排除过滤器

*.md .txt docs/
undefined
*.md .txt docs/
undefined

Strip Debug Symbols

剥离调试符号

ini
undefined
ini
undefined

Export preset options:

导出预设选项：

Debugging → Debug: Off

调试 → 调试模式：关闭

Binary Format → Architecture: 64-bit only

二进制格式 → 架构：仅64位

undefined
undefined

CI/CD with GitHub Actions

基于GitHub Actions的CI/CD

yaml
undefined
yaml
undefined

.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/
undefined
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/
undefined

Version Management

版本管理

gdscript
undefined
gdscript
undefined

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 + ")"
undefined
extends Node
const VERSION := "1.0.0" const BUILD := "2024.02.06"
func get_version_string() -> String: return "v" + VERSION + " (" + BUILD + ")"
undefined

Best Practices

最佳实践

1. Test Export Early

1. 尽早测试导出

Export to all target platforms early
Catch platform-specific issues fast
尽早导出到所有目标平台
快速发现平台专属问题

2. Use .gdignore

2. 使用.gdignore

undefined
undefined

Exclude folders from export

从导出中排除文件夹

Create .gdignore in folder

在目标文件夹中创建.gdignore文件

undefined
undefined

3. Separate Debug/Release

3. 区分调试版与正式版

Debug: Keep logs, dev tools
Release: Strip debug, optimize size
调试版：保留日志、开发工具
正式版：剥离调试信息、优化体积

Reference

参考资料

Related

相关内容

  • Master Skill: godot-master
  • 核心技能：godot-master