Godot GDScript 代码审查与重构时避免静态类型…

在 Godot 项目中编写、审查或重构 GDScript 代码时，规避静态类型、信号通信、节点访问、Callable、异步与集合操作等方面的典型陷阱。

适用场景

解决思路

1. 热路径仍使用 Variant 时，为变量和返回值添加类型注解，优先使用类型化集合（typed Array/Dictionary）。
2. _process 中的通用数学运算改用类型化辅助函数（absf、ceili、clampf）。
3. 编辑器安全线（safe-lines）缺失时，用 := 或显式类型修复类型推断。
4. 子节点需要父节点响应时，向上发射信号（emit signal up），绝不直接调用父节点方法。
5. 跨脚本传递载荷时，使用类型化信号声明 signal name(arg: Type)。
6. 连接信号时优先在 _ready() 中连接，而非使用编辑器里不可见的连线。
7. 需要子节点时使用 @onready 或 %UniqueName，绝不在 _init() 中获取。
8. 场景实例化节点需要构造参数时，使用 @export 注入，因为 _init(args) 会破坏 PackedScene.instantiate()。
9. 每帧路径查找时缓存一次，绝不在 _process 中使用 $ 或 get_node。
10. 回调需要额外上下文时使用 Callable.bind(...)。
11. 需要丢弃未使用的信号参数时使用 Callable.unbind(n)。
12. 一次性超时逻辑可用内联 lambda；若需 create_callback 式的长生命周期则保留引用。
13. 无线程地串联定时器时使用 await 链。
14. 需要全局状态但不想臃肿 Autoload 时使用 static var，并在用完后将大型静态变量置空。
15. 遍历 Dictionary 时若要删除元素，先克隆键（dict.keys().duplicate()）再遍历。
16. 不确定键是否存在时，用 dict.get("key", default) 替代 dict["key"]。
17. 为关键 UI/节点勾选 Access as Scene Unique Name，并通过 %Name 读取。
18. 脚本布局顺序：extends → class_name → signals/enums/consts → exports/onready → lifecycle → public → _private。
19. 绝不将 @onready 与 @export 用于同一变量（初始化顺序会导致 @onready 覆盖 Inspector 值）。
20. 绝不在遍历 Dictionary 时修改其大小。
21. 绝不使用基于字符串的 connect("signal", ...)，始终使用 Signal 对象语法（button.pressed.connect(...)）。
22. 绝不尝试覆盖非虚的原生引擎方法（如 queue_free()、get_class()）。
23. 绝不使用 Parent.method() 调用，遵守 Signal Up, Call Down。
24. 绝不使用 is 后接硬转换，改用 as 并检查 null。
25. 绝不用 print() 做生产调试，改用 push_error()、push_warning() 或断点。
26. 绝不在 _ready() 中预加载巨大资源，改用 ResourceLoader.load_threaded_request() 异步加载。
27. Autoload 中能用 static var 满足时绝不使用全局变量。
28. 不要为通用散文风格或 Godot 引擎版本升级（3→4 / 4.x）加载此技能。
29. 不要预加载所有脚本，只打开正在实现的核心指令对应的 MANDATORY 指针。
30. 不要将 EditorScript 工具（type_checker、performance_analyzer、signal_architecture_validator）当作运行时游戏代码。

适用边界 · 注意事项

• 通用散文风格审查或 Godot 引擎版本升级（3→4 / 4.x 迁移）不适用。
• 不要预加载全部脚本，只按需打开对应核心指令的 MANDATORY 指针。
• EditorScript 工具（type_checker、performance_analyzer、signal_architecture_validator）不适用于运行时游戏代码。