godot-export-builds

导出与构建

无头模式 / CI / 平台发布流程配置——不包含 Editor → Export 点击路径教程。

绝对不要做（专家级导出规则）

平台与验证

• 未经冒烟测试，绝对不要导出到生产环境——在 Editor 中运行 ≠ 满足 Web/移动端/主机平台的限制。
• 直接分发时绝对不要跳过 macOS 公证——Gatekeeper 会拦截未签名应用（Steam/App Store 分发可作为替代方案）。
• 绝对不要在构建中使用临时可写的 res:// 路径——存档/日志应写入 user://。

性能与体积

• 绝对不要将 Debug 模板作为正式版本发布——使用 --export-release。
• 绝对不要包含原始创作素材等无用文件——在预设中过滤掉 .md / .psd / 文档。
• 绝对不要忽略 Web/移动端的 VRAM 压缩——启用 ASTC/ETC2（像素艺术保持未压缩）。

安全性

• 绝对不要提交密钥库或密码——使用环境变量 + export_android_signing_env.ps1。
• 绝对不要在正式版本中保留调试作弊功能——使用 OS.has_feature("release") 进行限制。
• 专用服务器导出时绝对不要启用 Shader Baker——这会浪费构建时间；baker 面向有视觉表现的客户端。

---

平台决策树

目标	必须使用的脚本 / 操作	不要加载
桌面端冒烟测试（Win/Linux）	export_headless_pipeline.ps1 或 headless_build.sh	手动使用 Export UI 的教程
Web 冒烟测试	无头 Web 预设 + 体积报告	仅适用于桌面端的压缩假设
Android 正式版	export_android_signing_env.ps1	已提交的密钥库
macOS 直接分发	export_macos_notarize_cmd.ps1	不在 Steam 上发布时，以“Steam 已存在”为由跳过公证
专用服务器	无头服务器预设，关闭 baker	客户端 Shader Baker / UI 功能包
CI 多平台	export_ci_github_actions.yml（Godot 4.7 镜像）	过时的 4.2.x 容器版本固定项
Steam depot 上传	export_steam_upload.ps1	— 如果不在 Steam 上发布
PCK / DLC 补丁	export_pck_patch_loader.gd	— 如果没有 DLC
一键导出所有预设	export_universal_manager.gd	—
版本同步	export_version_sync.gd / version_manager.gd	仅在 UI 中硬编码版本标签
功能剥离	export_feature_flag_manager.gd	—
体积审计	export_build_size_report.gd	—
自定义引擎剥离	export_custom_build_stripper.py	— 除非使用自定义构建
导出后 zip/清单	export_post_process_hook.gd	—

**Editor Export UI / 模板下载相关说明：**请使用 Reference 中的 Official Documentation 链接，或参阅 export-setup-guide.md 中的 INI/CLI/平台检查清单。

可用脚本

必须：在实施前，先阅读与上述平台决策匹配的脚本。

• export_headless_pipeline.ps1
• headless_build.sh
• export_version_sync.gd / version_manager.gd
• export_post_process_hook.gd
• export_feature_flag_manager.gd
• export_pck_patch_loader.gd
• export_android_signing_env.ps1
• export_custom_build_stripper.py
• export_macos_notarize_cmd.ps1
• export_build_size_report.gd
• export_ci_github_actions.yml — 固定使用 4.7 模板/可执行文件
• export_steam_upload.ps1 — 通过 steamcmd + VDF 使用 SteamPipe
• export_universal_manager.gd

CI 约定（4.7）

工作流必须获取 Godot 4.7 编辑器和导出模板（而非 4.2.x）。优先使用仓库中已提交的 export_ci_github_actions.yml，而不是粘贴旧版 YAML。使用 actions/upload-artifact@v4 上传构建产物。

专家级导出模式

1. 平台专属补丁（增量更新）

使用 ProjectSettings.load_resource_pack(path, true) 挂载外部 PCK——同路径资源会覆盖基础资源。参见 export_pck_patch_loader.gd。

2. VRAM 压缩审计

• 桌面 Forward+：S3TC/BPTC
• 移动设备：ETC2 / ASTC
• 像素艺术：关闭压缩

3. SteamPipe 上传

在本地/CI 构建 → 使用 STEAM_USER / STEAM_PASS / STEAMCMD_PATH 环境变量和 app_build.vdf 运行 export_steam_upload.ps1。

4. 通用构建管理器

通过 export_universal_manager.gd 遍历 export_presets.cfg 中的预设，以确保一键构建的多平台一致性。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；仅在转接到相关领域时加载关联技能——不要预加载整个技能网络。

官方文档

• 导出（教程索引） — 在深入了解各个平台之前，先查看预设、模板、平台指南、功能标签和 PCK 工作流的索引。
• 导出项目 — 导出预设、模板安装、包含/排除筛选器，以及发布版与调试版模板的选择。
• 功能标签 — 用于在运行时剥离调试工具和平台分支的 OS.has_feature / 自定义标签。
• 命令行教程 — 用于 CI 和脚本化流水线的 --headless、--export-release、--export-debug 和 --export-pack。
• 导出资源包、补丁和模组 — 使用 ProjectSettings.load_resource_pack 挂载 PCK/DLC，以支持增量更新。
• 导出至 Android — 商店发布和 CI Android 构建所需的 SDK、密钥库和签名环境配置。
• 导出至 macOS — 通过 Gatekeeper 分发所需的代码签名、公证和通用二进制选项。
• 导出至 Web — Web 冒烟测试所需的线程/SharedArrayBuffer、VRAM 压缩和 HTML5 外壳约束。
• 导出至专用服务器 — 无头服务器模板，以及为何仅面向客户端的烘焙步骤（例如着色器烘焙器）会浪费服务器构建资源。
• EditorExportPlugin — 钩子 API，用于在团队共用的导出预设中执行导出后的 zip/清单处理步骤。
• 优化大小 — 当自定义模板必须比原版二进制文件更小时使用的 SCons 模块剥离和大小优化标志。
• 数据路径 — 了解 res:// 与 user:// 的区别，避免导出的构建写入只读打包路径。

相关技能

前置条件

• godot-project-foundations — 在设置导出预设和筛选器之前，项目布局、project.godot 版本/图标设置和导入默认值都必须正确。
• godot-gdscript-mastery — 版本同步、通用导出和后处理钩子中使用的 EditorScript / 插件类型和 OS.execute 模式。

补充

• godot-platform-desktop — Windows/Linux/macOS 运行时特性（图标、窗口管理、Steam），导出预设必须与之匹配。
• godot-platform-mobile — Android/iOS 权限、方向和输入方面的假设，应纳入移动端导出选项。
• godot-platform-web — Web 托管环境限制（CORS、线程、内存），决定 Web 导出类型和冒烟测试矩阵。
• godot-platform-console — 主机认证打包流程，超出桌面端／移动端导出模板的范畴。
• godot-adapt-desktop-to-mobile — 触控／UI／安全区域适配必须随带有移动端功能标签的构建一同发布，而不能只放在桌面端资源中。
• godot-debugging-profiling — 在归咎于预设筛选器之前，先分析导出版本与编辑器之间的差异（着色器编译、内存）。
• godot-testing-patterns — 针对无头／CI 构建产物运行自动化冒烟测试，避免只在编辑器中运行正常的内容未经验证就发布。
• godot-save-load-systems — 将数据持久化到 user://；导出筛选器不得移除玩家安装后仍需使用的存档架构。
• godot-resource-data-patterns — 资源打包和 .gdignore 管理可直接缩减导出体积。

下游／使用方

• godot-performance-optimization — 如果经过筛选、VRAM 压缩和模板选择后，发布构建仍无法满足预算，则升级处理。
• godot-server-architecture — 使用专用服务器导出预设和无头流水线来构建权威主机。
• godot-multiplayer-networking — 为专用服务器与监听服务器打包配置客户端／服务器二进制文件对和功能标签。

主索引

• godot-master — 知识库路由器和镜像模块入口；需要确定哪个领域技能负责跨领域导出或平台问题时，请打开此项。