Godot 4 GDScript 开发避坑指南 · 实战踩坑全记录开源项目

本项目面向所有使用或准备迁移到 Godot 4 的游戏开发者。Godot 4 是优秀的游戏引擎，但从 Godot 3 迁移或新手入门时，会遇到大量改名常量、移除的 API、废弃的类型、莫名其妙的解析错误，每个坑都可能耗费数小时。本指南收录了真实项目中逐一踩过并修复的坑，附完整修复方案，帮助开发者避开同样的陷阱、节省大量排错时间。适用于独立游戏开发、Godot 迁移、游戏编程教学等场景，开源免费，即取即用。

1、真实踩坑实录：收录从 Godot 3 迁移到 Godot 4 时真实遇到的每一个坑（自定义类不能作 const 类型、抽象类不能实例化、类型不存在、常量改名移位等），全部附修复代码。2、GDScript 语法避坑：覆盖 const 类型注解、抽象类构造、类型别名失效、TextServer 常量迁移等高频陷阱。3、完整修复方案：每个陷阱都给出已验证的修复代码与说明，不空谈理论，直接可复制。4、开源避坑手册：沉淀为结构化 SKILL 文档与开源仓库，长期更新，帮助后来者少走弯路。5、跨版本迁移指南：系统梳理 Godot 3→4 的破坏性变更，让迁移不再靠试错。

本项目由我在真实项目迁移 Godot 4 的过程中积累并整理而成。1、在把实际项目从 Godot 3 迁移到 Godot 4 时，系统记录每个报错与解决过程（如 const 自定义类报编译错误改为 var、AudioStreamRecorder 类型不存在改用 AudioEffectRecord 等）；2、将零散的踩坑笔记蒸馏为结构化避坑指南，每一条都附"陷阱现象→原因分析→修复方案"三段式；3、配套完整的 SKILL.md 技能文档，可在开发时随时调用；4、项目已在 dev.to 发布深度技术文章《I Migrated to Godot 4 and Hit These GDScript Traps》，获得开发者社区认可；5、开源至 GitHub，提供 MIT 协议与完整示例代码。