Godot 当前最佳实践（4.7 视角，post-cutoff）

Last verified: 2026-09-12（源：官方迁移指南 4.5/4.6/4.7 逐条核实 + 4.7 release 页）用途：训练数据（~4.4）之后的实践差异速查。写码代理在以下事项上不要按训练数据默认值行事。

1. 新建 project.godot 的默认值差异（最易踩坑）

设置	训练数据默认（≤4.4）	4.7 实际新项目默认	生效版本
`display/window/stretch/mode`	`disabled`	`canvas_items`	4.7（新项目）
`display/window/stretch/aspect`	`keep`	`expand`	4.7（新项目）
`rendering/rendering_device/driver.windows`	Vulkan（Forward+）	D3D12	4.6（新项目）
`physics/3d/physics_engine`	GodotPhysics3D	Jolt	4.6（新项目；本项目 2D、无 3D 物理，无关）

本项目为 2D 棋盘 UI：stretch mode / aspect 的最终选择归渲染器实现期 ADR，但须知道引擎新项目默认值已不是训练数据里的那个——新建工程后检查这三项。

2. GDScript 4.7 两条语义变化（建议入编码规范）

打包数组元素赋值不再触发属性 setter（4.7，GH-113228）：my_packed_array[i] = v 不再调用所在对象的 property setter——依赖 setter 副作用的写法必须改为显式赋回 + 显式调用 setter。D2 schema 类若以 setter 做校验，注意此差异。
类型化返回的方法覆盖必须显式 return（4.7，GH-115763）：覆盖带返回类型的方法时返回类型自动继承，缺少 return 直接报错（旧版隐式返回 null）——虚方法覆盖一律显式写 return。

3. 资源与文件

Resource.duplicate(true)（4.5 起）：深复制只覆盖内部子资源，不再覆盖外部子资源；需旧行为用 duplicate_deep(DEEP_DUPLICATE_ALL)。D2 表资源含外部子资源时注意复制语义。
FileAccess.get_as_text() 的 skip_cr 参数已移除（4.6）——换行处理如需自定义须自行实现。
TSCN 格式（4.6）：load_steps 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 会变大（可 Project > Tools > Upgrade Project Files 预升级，减少一次性大 diff）。
ProjectSettings.add_property_info()（4.5）：对缺失/非法键（含 usage）告警；改用 set_as_basic() / set_restart_if_changed() / set_as_internal()。

4. 2D / UI / 文本

CanvasItem 线条绘制不再自动加抗锯齿羽化（4.7）——粗线/描边需手动方案（D1 自绘棋盘格边框时注意）。
输入设备 ID：比较输入来源时用 InputEvent.DEVICE_ID_MOUSE / DEVICE_ID_KEYBOARD 常量，不要硬编码 0（4.7）——D1 输入路由。
字体导入 hinting 默认 1 → 3（4.7）；TextServer/Font/CanvasItem 全部 draw 方法新增可选 oversampling 参数（4.5）——自绘文字（数字标签）可显式控制过采样。
RichTextLabel 图片参数两轮变化：4.5 size_in_percent → width_in_percent+height_in_percent；4.7 → width_unit/height_unit（bool → ImageUnit），常量 UPDATE_WIDTH_IN_PERCENT → UPDATE_WIDTH_UNIT。
Glow 默认值大改（4.6）：blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排——2D 后处理发光的视觉基底已变，调参以 4.7 默认为起点。
Control.grab_focus / has_focus 新增可选参数（4.6，hide_focus / ignore_hidden_focus）——焦点可视化管理更细。

5. 4.7 已核实新特性（本项目可用的增量）

Tween.tween_await()：信号等待语法糖——注意 B1 结算逻辑禁 await 是设计约束（可回放步骤流），该 API 不改变该约束
Control offset_transform_*：平移/旋转/缩放 Control 不影响容器布局——D1 HUD 局部动效可用
CollisionShape2D 单向碰撞方向属性（+ PhysicsServer2D.body_set_shape_as_one_way_collision 的 direction 参数）——本项目棋盘非物理驱动，暂不依赖
conic gradient、AtlasTexture 进 TextureRect——D1 贴图/着色可选
DrawableTexture2D、AreaLight3D、HDR 输出、内置 VirtualJoystick、新 Asset Store——本项目暂不依赖
Font.find_variation 扩展（palette_index / custom_colors）、TreeItem.select 扩展——低相关

6. 本项目不消费的域（相关变更可忽略）

3D 渲染与物理（Jolt 行为变化 / SoftBody / WorldBoundary / SpringBone / LookAtModifier）、XR/OpenXR、网络（StreamPeerTCP/TCPServer 方法上移、RPC 更名）、GLTF 导入（int64 字段）、移动端导出（Android 模板结构变化、.NET 9）、编辑器插件 API（ImportFlags / VCS / ExportPlatform）。

4.6 KiB Raw Blame History Unescape Escape