export-pipeline

Godot 4.3+ 中的导出流程

所有示例均适用于 Godot 4.3+，不使用已弃用的 API。先展示 GDScript，适用时再介绍 C#。

相关技能： godot-testing 用于 CI/CD 测试集成，godot-optimization 用于导出前性能检查，responsive-ui 用于平台专属分辨率设置，mobile-development 用于 Android/iOS 导出细节，web-export 用于浏览器构建和托管。

---

1. 导出预设

在编辑器中创建预设

打开 项目 → 导出，点击 添加…，然后选择目标平台。每个预设对应 export_presets.cfg 中的一项。你可以为同一平台创建多个预设（例如，Windows 的调试版本和发布版本）。

每个平台都需要进行一次性设置：

• 必须通过 编辑器 → 导出模板 下载 导出模板。
• 必须单独安装平台专属工具链（Android SDK、Xcode 等）。

export_presets.cfg

Godot 会将 export_presets.cfg 写入项目根目录。请提交此文件：标记为机密的选项（密钥库和代码签名的路径及密码、加密密钥）会写入 .godot/export_credentials.cfg，此文件绝不能提交。在 CI 中，请通过环境变量提供这些信息，例如 GODOT_ANDROID_KEYSTORE_RELEASE_PASSWORD。

预设结构示例（Windows 发布版本）：

[preset.0]

name="Windows Desktop"
platform="Windows Desktop"
runnable=true
dedicated_server=false
custom_features=""
export_filter="all_resources"
include_filter=""
exclude_filter=""
export_path="build/windows/MyGame.exe"
encryption_include_filters=""
encryption_exclude_filters=""
encrypt_pck=false
encrypt_directory=false

[preset.0.options]

custom_template/debug=""
custom_template/release=""
debug/export_console_wrapper=1
binary_format/embed_pck=true
texture_format/s3tc_bptc=true
texture_format/etc2_astc=false
binary_format/architecture="x86_64"
codesign/enable=false
codesign/timestamp=true
codesign/timestamp_server_url=""
codesign/digest_algorithm=1
codesign/description=""
codesign/custom_options=PackedStringArray()
application/icon=""
application/console_wrapper_icon=""
application/icon_interpolation=4
application/file_version=""
application/product_version=""
application/company_name=""
application/product_name=""
application/file_description=""
application/copyright=""
application/trademarks=""
application/export_angle=0
application/export_d3d12=0
application/d3d12_agility_sdk_multiarch=true
ssh_remote_deploy/enabled=false
ssh_remote_deploy/host="user@host_ip"
ssh_remote_deploy/port="22"
ssh_remote_deploy/extra_args_ssh=""
ssh_remote_deploy/extra_args_scp=""
ssh_remote_deploy/run_script="#!/usr/bin/env bash\nexport DISPLAY=:0\n\"{temp_dir}/{exe_name}\" {cmd_args}"
ssh_remote_deploy/cleanup_script="#!/usr/bin/env bash\nkill $(pgrep -x -f \"{temp_dir}/{exe_name} {cmd_args}\")\nrm -rf \"{temp_dir}\""

每当预设发生更改时，编辑器都会重写 export_presets.cfg。编辑器打开时请勿手动编辑此文件。

⚠️ Godot 4.7 中的更改：“可运行”标记已从导出预设中移出——runnable=（如上例所示，适用于 4.3–4.6）不再是 export_presets.cfg 中的每预设属性；4.7 编辑器会在同一文件中写入顶层 [runnable_presets] 区段（平台名称 → 预设名称），并且仍会读取旧版键。在 4.7 编辑器中保存后，该行从文件中消失时不必惊讶。请参阅 GH-114930。

**Godot 4.7+：**稀疏 PCK 导出（补丁包）支持加密文件索引，可与现有的 encrypt_pck / encrypt_directory 预设选项配合使用。(GH-113920)

---

2. 特定平台设置

平台	关键设置 / 注意事项
Windows	设置 application/icon（.ico 文件）。代码签名需要 .pfx 证书；设置 codesign/enable=true，并通过环境变量提供 codesign/identity + codesign/password。如果没有代码签名，Windows SmartScreen 会向用户发出警告。
Linux	无需代码签名。生成的二进制文件带有可执行权限（0755）；如果上传或归档步骤移除了该权限位，请重新运行 chmod +x。分发时打包为 tarball 或 AppImage。
macOS	要让 Gatekeeper 允许启动且不显示警告，需要公证。设置 codesign/codesign（rcodesign，或在 Mac 上使用 Xcode codesign）和 notarization/notarization（rcodesign 或 Xcode notarytool）；导出时会提交公证。Info.plist 条目为 application/*（捆绑包 ID、版本）和 privacy/*（使用说明）。
Web	仅支持兼容性渲染器，且不支持 C#。预设的 variant/thread_support 默认关闭（Godot 4.3+），因此构建可以在任何静态主机上运行；启用线程的构建需要 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp 标头。导出的内容由 .html + .js + .wasm + .pck 组成。详情：web-export。
Android	发布签名需要密钥库。将 keystore/release 设置为 .keystore 路径，并通过环境变量提供 keystore/release_user + keystore/release_password。在预设中通过 permissions/* 声明权限。将 package/unique_name 设置为反向 DNS 格式的字符串（例如 com.studio.mygame）。
iOS	需要有效的 Apple 配置描述文件（.mobileprovision）。设置 application/bundle_identifier、application/code_sign_identity_release 和 application/provisioning_profile_uuid_release。分发构建需要 App Store 分发证书。

---

3. 从命令行导出

在无头模式下运行 Godot，无需打开 GUI 即可导出。这是 CI/CD 的标准做法。

发布导出

godot --headless --export-release "Windows Desktop" build/windows/MyGame.exe

调试导出

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

仅导出 .pck（不含可执行文件）

如果只想随固定的引擎二进制文件一起分发更新后的游戏数据（例如 DLC 或补丁分发），请使用 --export-pack：

godot --headless --export-pack "Windows Desktop" build/windows/MyGame.pck

**Godot 4.7+：**为 Android 导出补丁 PCK 时，可将 APK 或 AAB 作为基础包，从而将 PCK 补丁工作流扩展到 Android 构建。（GH-116553）

打包内存中的数据（Godot 4.7+）

PCKPacker.add_file_from_buffer(target_path, data, encrypt = false) 可将 PackedByteArray 直接打包到 PCK 中，无需在磁盘上创建临时文件；这在通过构建脚本生成补丁内容时非常方便：

var build_info: String = "v" + ProjectSettings.get_setting("application/config/version", "dev")
var packer := PCKPacker.new()
packer.pck_start("user://patch_1.pck")
packer.add_file_from_buffer("res://data/build_info.txt", build_info.to_utf8_buffer())
packer.flush()

string buildInfo = "v" + ProjectSettings.GetSetting("application/config/version", "dev").AsString();
var packer = new PckPacker();
packer.PckStart("user://patch_1.pck");
packer.AddFileFromBuffer("res://data/build_info.txt", buildInfo.ToUtf8Buffer());
packer.Flush();

关键命令行标志

标志	用途
--headless	不使用显示服务器；服务器 / CI 环境必需
--export-release "Preset Name" path	使用发布模板导出
--export-debug "Preset Name" path	使用调试模板导出
--export-pack "Preset Name" path	仅导出 .pck 资源包
--quit-after N	在主循环迭代 N 次后退出（导出时很少需要）

命令行标志中的预设名称必须与 export_presets.cfg 中的 name= 完全一致，包括大小写和空格。

---

4. 使用 GitHub Actions 实现 CI/CD

在 GitHub Actions 矩阵中运行 godot --headless --export-release，在每次推送和带标签的发布时构建 Windows、Linux 和 Web 构建产物。使用 chickensoft-games/setup-godot@v2 安装引擎和导出模板（C# 项目需设置 use-dotnet: true）。在导出前注入来自 git describe 的版本号，以确保二进制文件中的 application/config/version 正确。

完整的 .github/workflows/export.yml（包含矩阵预设、构建产物上传以及 Linux 可执行文件权限处理）请参见 references/ci-cd-github-actions.md。

---

5. 版本管理

在 application/config/version 中设置版本号，并在运行时使用 ProjectSettings.get_setting() 读取。若要在导出时注入来自 git 的版本号，请运行一个 --script 工具（继承自 SceneTree 的脚本），在导出步骤之前通过 OS.execute() 调用 git describe --tags --always --dirty。标签遵循语义化版本规范（v1.2.3）。

运行时版本标签、inject_version.gd 工具和标签约定请参见 references/versioning.md。

---

6. 分发：itch.io 和 Steam

itch.io 使用 Butler CLI：butler push build/windows/ my-studio/my-game:windows --userversion "$VERSION"。渠道名称遵循约定（windows、linux、macos、web、android）。在 CI 中，Ayowel/butler-to-itch@v1 Action 可一次推送所有构建产物；请将 API 密钥存储为 BUTLER_API_KEY 密钥。

Steam 需要三个组件：Steamworks SDK（不可再分发，请勿放入公开仓库）、用于引擎绑定的 GodotSteam 插件，以及由 steamcmd +run_app_build app_build.vdf 驱动的 depot 配置。Steam 集成不属于导出流程本身。

完整的 butler 安装说明、渠道命名表、deploy-itch GitHub Actions 作业和 Steam 组件说明，请参见 references/distribution-itch-steam.md。有关发布方面的内容——21 天应用费用等待期、至少两周的 Coming Soon 展示期、审核时间、商店素材尺寸、试玩版和 Next Fest 截止日期以及折扣规则——请参见 references/steam-release-planning.md。

---

7. 着色器烘焙器（Godot 4.5+）

Godot 4.5 引入了着色器烘焙器，这是一种在导出时为目标平台预编译着色器的工具。它主要缩短首次启动时的加载时间，在着色器转换较慢的 Direct3D 12 和 Metal 上效果最明显。它不会消除管线编译造成的卡顿，这仍需要通过管线预编译来解决。

启用

在项目 → 导出中，打开一个预设并找到着色器烘焙器部分。勾选已启用（shader_baker/enabled，默认关闭）。没有后端选择器：它只会针对目标平台的 rendering/rendering_device/driver 设置进行烘焙，且仅适用于 Forward+ 和 Mobile 渲染器。

着色器烘焙器会略微延长导出时间，并使 PCK 增大几 MB。烘焙后的着色器会嵌入 .pck 文件中。

各平台的影响

平台	后端	优势
macOS / iOS	Metal	提升最大——跳过首次加载时较慢的 SPIR-V → Metal 着色器转换
Windows	D3D12	提升显著——跳过 SPIR-V → DXIL 转换；管线仍会在运行时创建
Android（Mobile 渲染器）	Vulkan	缩短首次加载时间；对 Compatibility（GLES3）渲染器无影响
Linux / Windows	Vulkan	提升较小——Vulkan 可直接使用 SPIR-V

CI 工作流说明

通过编辑器 GUI 或 CLI（--export-release）导出时，Shader Baker 会自动运行。它由预设控制，而非单独的 CLI 标志。注意：编辑器只能为其自身操作系统支持的驱动程序进行烘焙——Linux 运行器只能烘焙 Vulkan，因此 D3D12 预设需要 Windows 运行器，Metal 预设需要 macOS 运行器。

# Shader Baker runs as part of normal export (no extra flag needed).
godot --headless --export-release "Windows Desktop" build/windows/MyGame.exe

---

8. Windows 导出 — 原生资源编辑（Godot 4.5+）

在 Godot 4.5 之前，在 Windows 上修改 .exe 元数据（版本信息、图标、版权、公司名称）需要使用外部工具 rcedit。Godot 4.5 会在导出时原生处理所有这些内容——无需下载或配置 rcedit。

原生编辑的内容

导出预设字段	对 .exe 的影响
application/file_version	属性 → 详细信息中显示的文件版本
application/product_version	产品版本
application/company_name	公司名称
application/product_name	产品名称
application/file_description	说明
application/copyright	法定版权信息
application/icon	图标图像（ICO、PNG、WebP 或 SVG），会转换并嵌入为可执行文件图标

设置

1. 打开 项目 → 导出 → Windows Desktop 预设。
2. 在预设选项的 应用程序 下填写 application/* 字段。
3. 正常导出——Godot 会将元数据直接写入 .exe。

从 CI 中移除 rcedit： 如果你的项目之前在 CI 中下载了 rcedit，并将其作为导出后的步骤调用，就可以移除该步骤。对于 Godot 4.5+，导出预设中的字段可以完全取代它。

---

9. 检查清单

• 已下载目标 Godot 版本的导出模板（Editor → Export Templates）
• 已将 export_presets.cfg 提交到版本控制
• 密钥库密码、代码签名密码、API 密钥等机密已存储在环境变量或 CI 机密中，绝不写入文件
• 每个预设都有唯一的 name=，且与 CLI --export-release 参数完全一致
• 在运行导出命令前创建输出目录（mkdir -p）
• 打包后 Linux 二进制文件仍具有可执行权限（如果权限位丢失，则运行 chmod +x）
• 导出时通过 git 标签填充 project.godot 中的 application/config/version
• Web 导出：关闭线程支持，或由主机发送 COOP + COEP 标头（参见 web-export）
• Android 发布预设使用已签名的密钥库，而非调试密钥库
• 用于分发的 macOS 构建已进行代码签名和公证
• 在 CI 中按平台上传构建产物，以便单独下载各平台的构建
• itch.io 渠道遵循命名约定（windows、linux、macos、web、android）
• Butler API 密钥存储为 CI 机密，而非硬编码
• Steam depot 配置不放入公共代码库
• 根据固定的提前时间核对 Steam 发布日期（等待费用支付 21 天、Coming Soon 页面展示两周、审核需 7 个工作日）
• 为 D3D12 和 Metal 目标启用 Shader Baker（仅 Forward+/Mobile），并分别从 Windows / macOS 主机导出（Godot 4.5+）
• 在导出预设中设置 Windows .exe 元数据（版本、图标、公司名称）——不再需要 rcedit（Godot 4.5+）