Godot 引擎 C 脚本诊断规则全解：从 Godot.SourceGenerators 的 AnalyzerReleases.Shipped.md 读懂 GD 系列报错

本文以 AnalyzerReleases.Shipped.md 这一 Roslyn 分析器"发布追踪"（Release Tracking）清单文件为核心骨架，完整梳理 Godot 4.x C# 支持（Mono 模块）中 Godot.SourceGenerators 组件自 4.0 至 4.4 各版本引入的全部 GD 系列诊断规则。读完本文，你将掌握三类能力：一、看懂每个 GD 报错 ID（GD0001–GD0402）的触发场景与修复方式；二、理解 Shipped/Unshipped 双清单文件在 Roslyn 分析器工程化中的定位与 csproj 集成方式；三、顺着文档中的每条规则，定位到仓库中对应的规则定义、报告点与测试用例，完成源码级验证。

一、AnalyzerReleases.Shipped.md 是什么：Roslyn 分析器的发布追踪清单

AnalyzerReleases.Shipped.md 是 .NET 编译器平台（Roslyn）生态中分析器/代码修复工具的标准约定文件之一。配套还有 AnalyzerReleases.Unshipped.md（当前仓库中该文件为空，见 AnalyzerReleases.Unshipped.md）。二者的分工是：

• Shipped 清单：记录"已经随某个版本发布"的所有诊断规则，按 Release 版本分节，每节下用表格列出规则 ID、类别（Category）、严重级别（Severity）与备注；
• Unshipped 清单：记录"尚未发布"的新规则，规则正式发版后从 Unshipped 迁移到 Shipped 的对应版本节中。

在 Godot.SourceGenerators.csproj 中，这两个文件通过 AdditionalFiles 项被显式纳入构建：

<!-- Analyzer release tracking -->
<ItemGroup>
  <AdditionalFiles Include="AnalyzerReleases.Shipped.md" />
  <AdditionalFiles Include="AnalyzerReleases.Unshipped.md" />
</ItemGroup>

同一段 csproj 还体现了 Godot 对该工具链的工程化约束：项目以 netstandard2.0 为目标框架、LangVersion 10，开启 EnforceExtendedAnalyzerRules（对分析器扩展规则强制执行），依赖 Microsoft.CodeAnalysis.CSharp.Workspaces 3.11.0，并在打包时把生成的 DLL 放入 NuGet 包的 analyzers/dotnet/cs 目录——这意味着该程序集以"分析器/生成器"身份注入用户的 C# 编译过程，而非作为普通类库被引用（IncludeBuildOutput 被设为 false 以印证此点）。当前仓库中该包版本为 4.8.0，而 Shipped 清单记录到的最新规则批次为 Release 4.4，说明 4.5 之后暂未新增对外可见的诊断规则。

二、Shipped 清单完整内容：四个版本的 GD 规则发布史

下面完整继承原文档的四节 Release 表格（原表中每条规则均附有指向 Godot 官方文档站对应诊断页的 Documentation 链接，此处按规范不再列出外部 URL，可按规则 ID 在 Godot 官方文档的 C# 诊断章节检索）：

Release 4.0（GD0001–GD0002、GD0101–GD0106、GD0201–GD0203、GD0301–GD0303，共 14 条）

Rule ID	Category	Severity	Notes
GD0001	Usage	Error	ScriptPathAttributeGenerator
GD0002	Usage	Error	ScriptPathAttributeGenerator
GD0101	Usage	Error	ScriptPropertyDefValGenerator
GD0102	Usage	Error	ScriptPropertyDefValGenerator
GD0103	Usage	Error	ScriptPropertiesGenerator
GD0104	Usage	Error	ScriptPropertiesGenerator
GD0105	Usage	Error	ScriptPropertyDefValGenerator
GD0106	Usage	Error	ScriptPropertyDefValGenerator
GD0201	Usage	Error	ScriptSignalsGenerator
GD0202	Usage	Error	ScriptSignalsGenerator
GD0203	Usage	Error	ScriptSignalsGenerator
GD0301	Usage	Error	MustBeVariantAnalyzer
GD0302	Usage	Error	MustBeVariantAnalyzer
GD0303	Usage	Error	MustBeVariantAnalyzer

Release 4.2（2 条）

Rule ID	Category	Severity	Notes
GD0107	Usage	Error	ScriptPropertyDefValGenerator
GD0401	Usage	Error	GlobalClassAnalyzer
GD0402	Usage	Error	GlobalClassAnalyzer

Release 4.3（1 条）

Rule ID	Category	Severity	Notes
GD0003	Usage	Error	ScriptPathAttributeGenerator

Release 4.4（4 条）

Rule ID	Category	Severity	Notes
GD0108	Usage	Error	ScriptPropertiesGenerator
GD0109	Usage	Error	ScriptPropertiesGenerator
GD0110	Usage	Error	ScriptPropertiesGenerator
GD0111	Usage	Error	ScriptPropertiesGenerator

从四个版本节的演进可以看出 Godot C# 诊断规则的增长轨迹：4.0 建立覆盖"类声明、导出成员、信号、泛型 Variant"的基础规则集；4.2 补充 Node 导出约束与 [GlobalClass] 全局类约束；4.3 收紧脚本文件内类名唯一性；4.4 一次性加入 4 条 [ExportToolButton] 工具按钮相关规则。全部 23 条规则的 Category 均为 Usage、Severity 均为 Error 且默认启用——即这些不是风格建议，而是直接阻断编译的硬性约束。

三、23 条规则的语义全景：结合 Common.cs 的权威定义

Shipped 表格只有 ID 与归属，而每条规则的标题、消息模板与修复建议在源码中统一定义于 Common.cs。该文件为每个规则构造一个 DiagnosticDescriptor，且 helpLinkUri 由统一模板拼接（Common.cs 第 8 行）：

private static readonly string _helpLinkFormat =
    $"{VersionDocsUrl}/tutorials/scripting/c_sharp/diagnostics/{{0}}.html";

这正是 Shipped 表格中 Documentation 列链接的来源——诊断报错时 IDE 中的"帮助链接"与文档站页面一一对应。所有规则均设置 isEnabledByDefault: true。按 ID 前缀分组后，各规则的完整语义如下：

3.1 GD0001–GD0003：脚本类声明规则（partial 与类名唯一性）

ID	规则标题	修复建议（源码 description 原文要点）
GD0001	派生自 GodotObject 的类型缺少 partial 修饰符	继承 GodotObject 的类必须声明为 partial
GD0002	包含 GodotObject 派生嵌套类的外部类缺少 partial 修饰符	派生类及其所有包含类型都必须加 partial
GD0003	同一脚本文件中存在同名的多个类	一个脚本文件只能有一个类名与文件名匹配

从源码看，GD0001/GD0002 由 ClassPartialModifierAnalyzer.cs 报告：分析器注册 SyntaxKind.ClassDeclaration 语法节点动作，先通过 InheritsFrom("GodotSharp", GodotClasses.GodotObject) 判定基类，再检查 IsPartial()；对嵌套场景则沿父类链逐层检查。该文件还附带一个 ClassPartialModifierCodeFixProvider 代码修复（第 62–111 行），能在 IDE 中一键"Add partial modifier"。而 GD0003 则直接报告于 ScriptPathAttributeGenerator.cs（正确路径为 ScriptPathAttributeGenerator.cs 第 101 行）——这也是 Shipped 表格 Notes 列将 GD0001/GD0002 标注在 ScriptPathAttributeGenerator 名下（4.0 版本时的归属记录）的由来。

为什么强制 partial？因为 Godot 的 C# 脚本采用"源生成器 + partial 类"架构：生成器需要往用户类中追加部分定义（属性包装、序列化钩子、信号绑定等），只有 partial 类才能被合并，这正是 Godot C# 脚本区别于普通 C# 类的根本约束。

3.2 GD0101–GD0111：导出成员（[Export]）与工具按钮规则

这一组共 11 条，是清单中最大的一族，覆盖 [Export] 属性与 4.4 新增的 [ExportToolButton] 特性：

ID	触发场景	修复建议要点
GD0101	导出成员是 static	只有实例字段/属性可导出，去掉 static 或 [Export]
GD0102	导出成员类型不受支持	改用受支持的类型，或去掉 [Export]
GD0103	导出成员只读	导出成员必须可写
GD0104	导出属性只写（write-only）	导出属性必须可读
GD0105	导出成员是索引器（indexer）	去掉 [Export]
GD0106	导出属性是显式接口实现	去掉 [Export]
GD0107	非 Node 派生类型导出了 Node 成员	Node 导出仅支持 Node 派生类（4.2 新增）
GD0108	[ExportToolButton] 用在了非 Tool 类上	加 [Tool] 特性或去掉 [ExportToolButton]
GD0109	[ExportToolButton] 与其他 [Export] 同时使用	二者互斥，保留其一
GD0110	工具按钮成员不是 Callable 类型	[ExportToolButton] 仅支持 Callable 类型成员
GD0111	工具按钮不是表达式体属性	必须是形如 new Callable(...) 或 Callable.From(...) 的表达式体属性

关于 Notes 列的归属，需要一点源码级澄清：Shipped 表格将 GD0103/GD0104 记在 ScriptPropertiesGenerator 名下，而从源码结构看，GD0101–GD0107 的报告点集中在 ScriptPropertyDefValGenerator.cs（其中 GD0104 同时也在 ScriptPropertiesGenerator.cs 第 463 行有报告点），GD0108–GD0111 则报告于 ScriptPropertiesGenerator.cs（第 286、440、475、570 行）。两个生成器同属一个源生成器程序、职责不同：ScriptPropertyDefValGenerator 负责导出字段的默认值与合法性校验，ScriptPropertiesGenerator 负责属性导出包装与工具按钮，表格 Notes 列记录的是规则随哪个生成器首次发布。

3.3 GD0201–GD0203：信号（[Signal]）委托签名规则

ID	触发场景
GD0201	[Signal] 委托名称未以 EventHandler 结尾
GD0202	信号委托签名中的参数类型不受支持
GD0203	信号委托签名未返回 void

三条均由 ScriptSignalsGenerator.cs 报告。这一组确立了 Godot 4.x C# 信号写法的基本契约：信号以 C# 委托声明、名称必须带 EventHandler 后缀、参数与返回值必须符合 Variant 兼容约束。

3.4 GD0301–GD0303：泛型与 [MustBeVariant] 约束

ID	触发场景
GD0301	泛型实参不是 Variant 兼容类型
GD0302	泛型形参未标注 [MustBeVariant] 特性
GD0303	某个必须 Variant 兼容的类型实参的父符号未被处理（源码注释说明"这是引擎自身的问题，应上报 bug"）

三条由 MustBeVariantAnalyzer.cs 报告。值得注意的是 GD0303 的语义定位与其他规则不同——它面向的不是用户代码错误，而是引擎内部检查兜底。

3.5 GD0401–GD0402：[GlobalClass] 全局类规则（4.2 新增）

ID	触发场景
GD0401	标注 [GlobalClass] 的类未派生自 GodotObject 或其派生类
GD0402	标注 [GlobalClass] 的类是泛型类

由 GlobalClassAnalyzer.cs 报告，约束"全局类"这一跨脚本复用机制：全局类必须是 Godot 对象类型的非泛型具名类型。

四、追踪机制如何闭环：从清单到测试用例

Shipped 清单的价值在于让"对外发布的规则集合"可审计。仓库中与该清单对应的验证设施非常完整：

• 测试工程：Godot.SourceGenerators.Tests 用 Roslyn 的 CSharpAnalyzerVerifier / CSharpSourceGeneratorVerifier（见 CSharpAnalyzerVerifier.cs、CSharpSourceGeneratorVerifier.cs）在编译期对每条规则做"应报/不应报"断言；
• 输入样本：TestData/Sources/ 目录下按规则命名，如 ClassPartialModifier.GD0001.cs、Generic.GD0003.cs、SameName.GD0003.cs、GlobalClass.GD0401.cs、MustBeVariant.GD0302.cs 等，与 Shipped 表格中的规则 ID 一一对应；
• 期望输出：TestData/GeneratedSources/ 保存各生成器针对样本应产出的生成代码快照（如 Bar_ScriptPath.generated.cs、ScriptBoilerplate_ScriptProperties.generated.cs），构成对生成器行为的回归基线；
• 测试驱动类：如 ExportDiagnosticsTests.cs、GlobalClassAnalyzerTests.cs、MustBeVariantAnalyzerTests.cs，按规则族组织。

从源码结构看，整个工程形成了一条闭环：Common.cs 集中定义规则 → 各分析器/生成器报告规则 → AnalyzerReleases.Shipped.md 记录发布轨迹 → Tests 目录用样本代码反向验证每一环。开发者若要新增一条 GD 规则，规范做法是先写入 Unshipped 清单、发版时迁入 Shipped 的版本节，并同时补齐 TestData 样本与测试断言。

五、实操速查：遇到 GD 报错时该看哪里

1. 在 IDE 中看到 GDxxxx 报错时，"Help link" 直达该 ID 的官方诊断页（链接格式由 Common.cs 第 8 行统一生成）；
2. 查触发条件与修复文案：以规则 ID 为关键词检索 Common.cs，messageFormat 是编辑器里显示的原文，description 参数是官方修复建议；
3. 查报告点与判定逻辑：按 Shipped 表格 Notes 列找到对应生成器/分析器文件（如 GD0107 看 ScriptPropertyDefValGenerator.cs，GD0401 看 GlobalClassAnalyzer.cs）；
4. 查行为回归：在 Godot.SourceGenerators.Tests/TestData/ 中找到同名样本文件，对照 Sources 与 GeneratedSources 理解该规则在真实编译中的输入输出；
5. 查版本引入时间：回到本文第二部分对应的 Release 节，确认该规则从哪个 Godot 版本开始生效——这在使用旧版 SDK 迁移项目时尤其有用。

六、小结

AnalyzerReleases.Shipped.md 看似只有一张规则表，实则是 Godot C# 脚本工具链的"对外契约总账"：它把 4.0 至 4.4 四个版本发布的 23 条 Error 级诊断规则按版本归档，与 Common.cs 中的 DiagnosticDescriptor 定义、各分析器/生成器的报告点、以及 Godot.SourceGenerators.Tests 的完整测试基线相互咬合。理解这份清单，就理解了 Godot 引擎如何在 C# 编译阶段前置拦截"非 partial 的 Godot 类、非法导出成员、不合规信号委托、越界的泛型与全局类"等一切会导致运行时注册失败的脚本错误。