为 Godot 项目配置严格的 GDScript 静态类型检查

使用者常见痛点

• 项目代码量逐渐增大，却发现大量未标注类型导致运行时错误频出。
• 开启警告后插件代码噪声淹没了自己的问题。怎么说呢，
• 团队对“WARN” 与 “ERROR” 的区别认知不足。导致调试效率低下，
• 缺乏统一的配置模板每次新建项目都要手动设置。按理说，

背景

GDScript 从 Godot 4 起支持完整的静态类型程序。默认情况下许多类型相关的警告仅为提示，不会阻止游戏运行。话说回来，对于追求代码质量的项目，可以将其提高为错误级别。让编辑器在编译阶段就拦截类型问题。

主要思路很简单：每一项警告都可以独立设置为三个等级之一：

等级值	含义	效果
IGNORE	完全忽略，不显示	-
WARN	黄色警告，不阻止运行	仅在编辑器中提示
ERROR	红色错误。 阻止编译	必须修复后才能运行

快速配置

在项目根目录的 project.godot 中添加下面内容：

# 启用警告程序
gdscript/warnings/enable=true
# 跳过 addons/ 目录
gdscript/warnings/exclude_addons=true
# ====== 类型安全 — ERROR ======
gdscript/warnings/untyped_declaration=ERROR
gdscript/warnings/unsafe_property_access=ERROR
gdscript/warnings/unsafe_method_access=ERROR
gdscript/warnings/unsafe_cast=ERROR
gdscript/warnings/unsafe_call_argument=ERROR
gdscript/warnings/incompatible_ternary=ERROR
gdscript/warnings/narrowing_conversion=ERROR
gdscript/warnings/int_as_enum_without_cast=ERROR
gdscript/warnings/int_as_enum_without_match=ERROR
gdscript/warnings/confusable_identifier=ERROR
gdscript/warnings/redundant_static_unreachable=ERROR
# ====== 未使用 / 影子变量 — WARN ======
gdscript/warnings/unused_variable=WARN
gdscript/warnings/unused_parameter=WARN
gdscript/warnings/unused_signal=WARN
gdscript/warnings/unused_local_constant=WARN
gdscript/warnings/unused_private_class_variable=WARN
gdscript/warnings/shadowed_variable=WARN
gdscript/warnings/shadowed_variable_base_class=WARN
gdscript/warnings/shadowed_global_identifier=WARN
# ====== 代码质量 — WARN ======
gdscript/warnings/unreachable_code=WARN
gdscript/warnings/unreachable_pattern=WARN
gdscript/warnings/standalone_expression=WARN
gdscript/warnings/standalone_ternary=WARN
gdscript/warnings/deprecated_keyword=WARN
gdscript/warnings/confusable_local_declaration=WARN
gdscript/warnings/empty_assignment=WARN
gdscript/warnings/return_value_discarded=WARN
# ====== 推断风格 — WARN ======
gdscript/warnings/inferred_declaration=WARN

如果更喜欢图形化操作，也可以通过编辑器完成：

1. 打开 Project → Project Settings → Advanced Settings → Debug → GDScript → Warnings
2. 逐项将对应警告等级切换为 WARN/ERROR
3. 保存并重启编辑器，使配置生效。

完整警告项参考

🔴 类型安全 — 设为 ERROR

这些警告直接关系到运行时类型安全，建议始终设为错误级别。

?，?Actually ignore;We'll continue ...

设置键	英文名称	中文名称	触发场景
untypeddeclaration	Untyped Declaration- 变量、参数或返回值缺少类型注解
unsafepropertyaccess	Unsafe Property Access- 在 Variant 或动态类型问属性
unsafemethodaccess	Unsafe Method Access- 在 Variant 或动态类型上调用方法
unsafecast	Unsafe Cast- 无法验证的 a as B 转换
unsafecallargument	Unsafe Call Argument- 参数与期望类型不匹配
incompatibleternary	I​ncompatible Ternary- 三元运算符两分支返回不同类型
conversion`

GDScript 从 Godot 4 开始原生支持完整静态类型程序。默认情况下大多数与类型相关的问题仅以 warn 的形式出现，不会阻止游戏运行。对于追求零 Bug、可维护性的项目。你可以把这些提示提高至 Error ，让编辑器在编译阶段即拦截并强制修复。

主要思路很简单：

<\/tr>\ <\/ad>\ \ \

等级值	含义	效果
IGNORE<\/cod e><\/t d>\

\ 完全忽略。不显示<\/ t d><\/t r>\ \ WARN<\/ cod e><\/t d>\ 黄色警告，不阻止运行<\/ t d><\ 仅在编辑器中弹出提示<\/ t d><\/t r>\ \ ERR OR<\/ cod e><\/ t d>\ 红色错误，阻止编译<\/t d>\ 必须先修复才能继续运行<\/ td> <\/tbody>\ <\/ta ble>

。

---