godot-version-migration

Godot 版本迁移

负责协调从早期 Godot 到库目标版本的引擎版本升级。领域技能文档记录的是当前 API；本中心负责升级路径。

库目标版本： Godot 4.7+

资料库：文档更新日志 · 交互式更新日志 · 下载存档 · GitHub 发布页面 · 迁移索引

绝对禁止

• 绝对不要跳过主版本——按 1.x → 2.x → 最新 3.x → 4.0 的顺序升级，然后再进行任何 4.x 次版本升级。
• 绝对不要跳过 4.x 版本——每次只升级一个次版本，按 4.0 → 4.1 → … → 4.7 进行；每次升级后都要先稳定下来。
• 绝对不要声称可以自动将 1.x 转换为 4.x，或实现位精确的自动迁移。
• 绝对不要把领域技能正文当作迁移更新日志——请加载 references/<topic>.md（该文件镜像自各技能的 references/migration-notes.md）。
• 绝对不要一次性加载所有模块说明——只加载项目中实际包含的子系统对应的说明。
• 绝对不要在高层多人游戏中混用服务器和客户端的 Godot 次版本（尤其是跨越 4.2→4.3 的 SceneMultiplayer 协议变更时）。
• 绝对不要在没有 VCS 备份的情况下为 Mesh 选择“Restart & Upgrade”（4.1→4.2 网格格式变更）。
• 绝对不要在没有完整备份的情况下运行 3→4 转换器（该工具不会备份）。

检测版本

1. 读取 project.godot（config_version、config/features）或旧版 engine.cfg。
2. 如果文件信息不明确，请询问用户。
3. 在 references/era-index.md 中确定所属时代。

工作流路由器（必须遵循）

检测到的时代	加载	不要
1.x / 早期 2	legacy/pre-2-context.md	臆造 1→4 转换器
2.x	legacy/2-to-3.md，然后稳定到最新 3.x	直接跳到 4.7 说明
3.x	bridges/3-to-4.md + 官方 3→4 指南	跳过稳定到最新 3.x 的关卡
4.x < 4.7	官方逐版本升级指南 + 针对涉及系统的 hop-index.md 模块说明	跳过次版本
已是 4.7+	godot-master / 领域技能	把本中心当作编程教程

步骤（4.x 次版本）

1. 当 current < 4.7 时，每次只升级一个版本至 current + 0.1。
2. 打开目标版本的官方升级页面。
3. 从 hop-index.md 中只打开项目实际包含的子系统对应的模块说明。
4. 应用修复；在新编辑器中打开项目；进行试玩测试；然后重复。

升级表

主版本 / 过渡版本

时代	资源
1.x 考古	legacy/pre-2-context.md
2.x → 3.x	legacy/2-to-3.md
3.x → 4.0	bridges/3-to-4.md · 官方指南
升级路径概览	era-index.md

4.x 次要版本

升级路径	官方指南
4.0 → 4.1	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.1.html
4.1 → 4.2	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.2.html
4.2 → 4.3	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.3.html
4.3 → 4.4	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.4.html
4.4 → 4.5	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html
4.5 → 4.6	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html
4.6 → 4.7	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html

跨技能检查清单：references/hop-index.md

模块目录

镜像的 Domain Skill 迁移说明位于 references/<topic>.md（例如 references/2d-physics.md）。Hub 原生的 legacy/、bridges/ 和 era-index.md 并非 Domain Skill 镜像。

sync_godot_version_migration.py --all

参考资料

官方文档

• 迁移到新版本
• 从 Godot 3 升级到 Godot 4
• 文档更新日志

相关技能

主技能

• godot-master — 迁移完成后，为当前 Domain Skill 模块提供路由的库。

下游 / 使用方

• godot-analyst — 升级路径完成后，基于目标 API 评估架构。
• godot-auditor — 升级后验证禁止列表和旧版语法。
• godot-builder — 每次升级后，针对新引擎目标运行 CI / 无头烘焙。

配套技能

• godot-project-foundations — 使用目标版本时的项目设置 / 结构。
• godot-gdscript-mastery — 完成 3→4 / 4.x 语言升级后使用的类型化 GDScript 2.0 惯用写法。
• godot-export-builds — 每次涉及平台的升级后重新验证导出。