企业官网建设流程全解析

• 文档
• 教程
• 游戏开发

本文以官方文档 release_policy.rst 为骨架，结合仓库中的迁移指南与兼容性处理文档，系统讲解 Godot 引擎的版本号语义、稳定分支支持时间线、新项目版本选择、项目升级决策以及跨版本兼容性准则，帮助开发者在选型与升级时做出有依据的判断。

Godot Engine 的发布策略并非一成不变，而是一直在演进中。官方文档明确指出：下面描述的是"一般预期"，实际发生什么取决于核心贡献者的选择与社区在特定时期的需求。理解这套规则，对游戏开发者选择合适的引擎版本、规划项目升级节奏、评估第三方资源兼容性都至关重要。

Godot 版本号体系：基于 major.minor.patch 的"引擎化"语义版本

Godot 松散地遵循 语义化版本（Semantic Versioning）的major.minor.patch三段式版本号，但对每个段的解释针对游戏引擎的复杂性做了适配，而不是严格照搬软件库的语义。

major：主版本（重大兼容性破坏）

major版本号在发生重大兼容性破坏时递增，这类破坏意味着项目从一个主版本迁移到另一个主版本需要大量的移植工作。

最典型的例子就是从 Godot 3.x 迁移到 Godot 4.x：项目需要先运行一个转换工具（conversion tool），然后对工具无法自动处理的遗留部分手动进行大量额外调整。这一过程在仓库的 从 Godot 3 升级到 Godot 4 中有完整操作指引。

minor：次版本（兼容性不重大破坏的特性版本）

minor版本号用于不破坏兼容性的特性发布。文档明确说明，少数特定区域的轻微兼容性破坏可能在 minor 版本中发生，但绝大多数项目不应受影响，也不需要显著的移植工作。

原因在于：Godot 作为游戏引擎，覆盖了渲染、物理、脚本等多个领域。在某个领域修复 bug 或实现新特性时，有时不得不改变某个特性的行为或修改某个类的接口，即使引擎其余 API 仍然保持向后兼容。官方给出了一条实用建议：

建议：所有用户都应当升级到新的 minor 版本，但升级前需要做一些测试，确保项目仍然按预期工作。

patch：补丁版本（维护发布）

patch版本号用于维护发布（maintenance releases），聚焦于：

• 修复 bug 和安全问题；
• 实现平台支持的新需求；
• 回溯移植安全可用性增强。

补丁版本是向后兼容的。补丁版本可能包含不影响现有 API 的少量新特性，因此对现有项目没有风险。

建议：对给定稳定分支的所有用户，更新到新的补丁版本被认为是安全的，并且被强烈推荐。

稳定分支的定义

major.minor的组合被称为稳定分支（stable branch）。每个稳定分支以一次major.minor发布开始（patch 位不写0），并在同名 Git 分支中继续开发维护发布。例如，4.0 稳定分支的补丁更新在4.0Git 分支中开发。

发布支持时间线

支持原则

稳定分支的支持遵循以下原则：

1. 至少支持到下一个稳定分支发布并收到首个补丁更新；
2. 实际上，官方以best effort（尽力而为）的方式，只要还有需要维护更新的活跃用户，就继续支持稳定分支；
3. 每个新主版本发布时，官方会把上一个稳定分支设为长期支持发布（long-term supported release），尽力为无法把复杂项目移植到新主版本的用户修复问题。3.x 分支就是这一政策的当前受益者；
4. 在某个 minor 版本序列中，只有最新的补丁发布受到支持。如果使用较旧补丁版本遇到问题，请先升级到该序列最新的补丁版本再测试，然后才在 GitHub 上报 issue。

支持状态图例

版本支持状态一览（以本仓库文档为准）

重要提示：预发布（pre-release）的 Godot 版本不应用于生产环境，它们仅用于测试目的。

从这张表可以读出关键信号：当前master（4.8）处于开发中，4.7 与 4.6 是完整支持的稳定分支，4.5 已进入仅接收安全与平台修复的部分支持阶段；而 4.4 及更早的 4.x 分支均已生命周期结束。这与仓库构建配置中标识的文档版本（conf.py 中godot_version为 4.7）一致——本仓库文档正对应 Godot 4.7 时代。

新项目应该使用哪个版本？

官方推荐新项目使用 Godot 4.x，理由如下：

• 4.x 系列将在 3.x 停止接收更新之后长期得到支持；
• 一个需要注意的短板是：大量第三方文档尚未更新到 Godot 4.x。如果你必须跟随一套面向 Godot 3.x 的教程，官方建议把 从 Godot 3 升级到 Godot 4 单独开一个标签页放在手边，以便在尝试某个被重命名的节点或方法而遇到脚本报错时，随时核对哪些方法名发生了变化。

例外情况：如果你的项目需要 4.x 中缺失的特性（例如 GLES2/WebGL 1.0 支持），则应改用 Godot 3.x 启动新项目。

是否应把现有项目升级到新引擎版本？

升级是一项本质上存在风险的工程决策。官方给出三条通用建议：

1. 升级前先备份：使用版本控制或制作项目备份，防止升级失败造成数据丢失；
2. 官方承诺尽力保持 minor 尤其是 patch 版本与现有项目兼容；
3. 升级决策因版本类型而异，见下表。

patch 版本：推荐跟进

一般建议项目跟随新的patch发布（例如从 4.0.2 升级到 4.0.3）。理由：

• 获得 bug 修复、安全更新与平台支持更新（对移动平台尤其重要）；
• 官方社区平台上只有最后一个 patch 发布能获得支持，停留在旧补丁版本等于失去支持。

minor 版本：逐案评估

是否需要升级 minor 版本，应按具体情况逐案判断：

• 官方在让升级过程尽量无痛上投入了大量工作，但 minor 版本中仍可能存在一些破坏性变更；
• minor 版本存在更大的回归风险；
• minor 版本中某些修复可能改变类的预期行为（这是修复 bug 所必需的），在文档中标记为 experimental（实验性）的类尤其如此。

major 版本：默认停留

• major 版本带来大量新功能，但也移除既有功能，并可能提高硬件要求（可参考 系统需求）；
• major 升级的工作量远超 minor 升级；
• 官方建议：如果你对项目当前运行状态满意，就停留在启动项目时所处的主版本。例如项目从 3.5 开始，建议升级到 3.5.2 乃至未来的 3.6，但除非项目确实需要 4.0+ 的新特性，否则不建议升到 4.0+。

下一个版本何时发布？

Godot 贡献者不受截止日期约束，但官方力求相对频繁地发布 minor 版本：

• 在 4.0 漫长的发布周期之后，团队转向了更快的开发节奏：4.1 在 4.0 之后 4 个月发布，4.2 又在 4.1 之后 4 个月发布；
• 频繁的 minor 发布让新特性更快交付（可能先以 experimental 状态发布）、更快获得用户反馈并迭代改进；
• 维护（patch）版本按需发布，开发周期可能非常短，为当前稳定分支用户提供最新的生产环境 bug 修复。

就 3.x 线而言，文档记录了当时的判断：3.7 尚无计划发布日期，而当时的稳定版本 3.6 可能是 Godot 3.x 的最后一个稳定分支；3.x 按 best-effort 原则支持，只要贡献者继续维护就持续支持。

跨版本兼容性标准：什么变更允许出现在哪个版本

这一节是给引擎贡献者判断某次改动对某个发布是否安全用的。列表并非穷尽，只勾勒 Godot 开发中最常见的情况。

允许出现在 patch 版本的变更

• 以对大多数项目无重大负面影响的方式修复 bug（例如视觉或物理 bug）。Godot 的物理引擎不是确定性的，因此物理 bug 修复不被视为破坏兼容性；如果修复 bug 可能影响大量项目，则应将其做成可选的（例如通过项目设置或独立方法）；
• 为方法新增可选参数；
• 小规模编辑器可用性调整。

值得注意的是，官方在后续的每个 patch 发布中对修复采取更保守的态度。例如 4.0.1 可能接收比 4.0.4 更有冲击力的修复。

允许出现在 minor 版本、但禁止出现在 patch 版本的变更

• 重要的新特性；
• 重命名方法参数。原因很关键：C# 中方法参数可以按名称传递（GDScript 则不行），因此这会破坏某些使用 C# 的项目；
• 弃用（deprecate）方法、成员变量或类。做法是在其类引用中添加弃用标记，该标记会显示在编辑器中；被标记弃用的方法计划在下一个major版本中移除；
• 影响默认项目主题视觉效果的变化；
• 为更好满足用户预期而显著改变行为或输出的 bug 修复。对比之下，patch 版本可能倾向于保留有 bug 的行为，以避免破坏已经依赖该 bug 或使用变通方案的现有项目；
• 导致视觉变化的性能优化。

被视为破坏兼容性、只能在 major 版本中进行的变更

• 重命名或移除方法、成员变量或类；
• 修改节点的继承树，使其继承自不同的类；
• 以影响现有项目的方式改变项目设置的默认值。若只想影响新项目，应由项目管理器写入修改后的project.godot文件。

由于 Godot 5.0 尚未分支，官方当前不鼓励进行此类破坏兼容性的改动。

方法签名修改的 GDExtension 兼容要求

无论以何种方式修改方法签名（包括添加可选参数），都必须创建GDExtension 兼容方法（GDExtension compatibility method）。这样现有的 GDExtension 才能在 patch 与 minor 版本间继续工作，用户无需重新编译它们。具体操作流程详见 处理兼容性破坏。

以该文档中的实际案例（PR #88047）为例，可以直观看到这套机制的运作方式：

修改前（core/math/a_star_grid_2d.h）：

Vector<Vector2> get_point_path(const Vector2i &p_from, const Vector2i &p_to); TypedArray<Vector2i> get_id_path(const Vector2i &p_from, const Vector2i &p_to);

修改后（新增可选参数allow_partial_path）：

Vector<Vector2> get_point_path(const Vector2i &p_from, const Vector2i &p_to, bool p_allow_partial_path = false); TypedArray<Vector2i> get_id_path(const Vector2i &p_from, const Vector2i &p_to, bool p_allow_partial_path = false);

随后在protected段添加兼容绑定方法（通常紧挨_bind_methods()），命名规范为：以下划线开头表示内部方法，以_bind_compat_结尾并附上引入该变更的 PR 编号：

#ifndef DISABLE_DEPRECATED TypedArray<Vector2i> _get_id_path_bind_compat_88047(const Vector2i &p_from, const Vector2i &p_to); Vector<Vector2> _get_point_path_bind_compat_88047(const Vector2i &p_from, const Vector2i &p_to); static void _bind_compatibility_methods(); #endif

兼容方法应实现在紧邻原文件的*.compat.inc文件中（本例为core/math/a_star_grid_2d.compat.inc），其中通过ClassDB::bind_compatibility_method()注册旧签名，并直接调用修改后的方法（保持默认参数一致），而不是复制实现：

TypedArray<Vector2i> AStarGrid2D::_get_id_path_bind_compat_88047(const Vector2i &p_from_id, const Vector2i &p_to_id) { return get_id_path(p_from_id, p_to_id, false); } void AStarGrid2D::_bind_compatibility_methods() { ClassDB::bind_compatibility_method(D_METHOD("get_id_path", "from_id", "to_id"), &AStarGrid2D::_get_id_path_bind_compat_88047); ClassDB::bind_compatibility_method(D_METHOD("get_point_path", "from_id", "to_id"), &AStarGrid2D::_get_point_path_bind_compat_88047); }

最后通过--dump-extension-api与--validate-extension-api两个命令行参数校验 API 变更，并把校验输出（格式如Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.）连同变更说明写入按 PR 编号命名的验证文件（如misc/extension_api_validation/4.2-stable/GH-88047.txt）。若出现Hash changed错误，则说明兼容绑定缺失或错误，需要修复绑定而非把错误写入验证文件。

这一整套机制正是"patch 版本向后兼容、GDExtension 无需重编译"承诺的底层保障，也解释了为何官方能在频繁发布的同时维持稳定的 API 兼容面。

总结：发布策略决策速查

理解这套发布策略，本质上是理解 Godot 社区"频繁交付、谨慎破坏"的工程哲学：patch 求稳、minor 求新、major 求变，而 GDExtension 兼容机制则像安全网一样，让 API 演进过程中的既有生态始终可运行。

• 文档
• 教程
• 游戏开发