项目跨版本迁移操作指南
迁移的本质
Godot 的主版本之间（比如 3.x → 4.x、4.2 → 4.6）会引入 API 废弃、节点改名、属性移动等变动。把项目从旧版本引擎下迁到新版本，本质上是让代码和资源适配新 API。Godot 编辑器本身会做一部分自动迁移工作，但很多地方需要手动调整。
GodotHub 在迁移过程中的角色是帮你平滑切换引擎版本——把版本切换的体力活做掉，让你专注在代码层面的适配上。
标准迁移流程
第一步：备份
在开始任何迁移操作之前，先给项目做一次完整备份。GodotHub 不自动做这个，你需要自己 git commit 或复制整个项目目录。
第二步：下载新版本引擎
在 GodotHub 的引擎管理界面下载目标版本，比如 Godot 4.5。下载完成后确认它出现在已安装列表里。
第三步：修改版本绑定
在项目管理界面，把目标项目的引擎绑定改成新版本。GodotHub 会自动检查新版本是否已安装、导出模板是否可用。
第四步：打开项目触发迁移
双击打开项目，Godot 编辑器启动时会检测到版本变更，自动执行：
- 扫描项目里的
.gd和.cs文件，标记废弃的 API 调用 - 尝试修复已知的节点名称和属性变更
- 更新
project.godot里的版本号和配置
第五步：手动调整
编辑器自动迁移完成后，打开脚本面板检查编译错误。Godot 4.x 系列内部的小版本升级通常变动不大，大部分项目迁移后只需要修几处废弃 API。如果是跨主版本（3.x → 4.x），改动量会比较大，建议逐模块测试。
高频迁移问题
| 问题 | 处理方式 |
|---|---|
| API 标记为废弃但还能跑 | 可以暂时不动，但要在代码里加上 @warning_ignore 或直接按 IDE 提示替换成新 API |
| 节点属性在新版本里不存在 | 打开 Godot 官方 API 文档搜索替代方案 |
| 项目用了某个第三方插件，但插件还没适配新版本 | 找替代插件，或等作者更新 |
| 迁移后编辑器启动慢了很多 | 清掉 .godot/ 缓存目录让编辑器重建索引 |
回退
如果迁移后遇到无法解决的问题，随时可以：
- 把 GodotHub 里的项目引擎绑定改回旧版本
- 用旧版本引擎打开项目（如果你还保留了旧版本的话）
- 或直接恢复之前的备份