看到“Source Generator 用在 Unity UI”这个方向，我第一反应不是“终于不用写一堆属性了”，而是最近在项目里连续处理了两个热词级问题——TextMeshPro 被 UI 挡到、以及 UI 上动态画线后节点引用动不动断掉。这两件事表面看和源代码生成八竿子打不着，但排查到最后，根子都落在一个地方：Unity UI 里大量的连接关系都是弱类型的，编译器根本不管，运行时才爆炸。Source Generator（以下按社区习惯简称 SG）确实能在 UI 领域做很多事，但如果谁把它的卖点总结成“少写属性”，那基本是把锤子用成了螺丝刀。
这篇文章我不打算罗列一堆生成器 API，而是从一个实际做 UI 模块的视角，讲讲 SG 真正该用在 Unity UI 的哪些位置，以及哪些问题它救不了。
1. 先说结论：Unity UI 真正缺的不是“少写属性”，是编译期的 UI 契约
1.1 拿 SG 生成属性包装，是 UI 领域最不值得做的方向
打开任何一篇讲 C# Source Generator 的入门文章，你大概率会看到一个 demo：让一个普通类实现 INotifyPropertyChanged，然后自动给字段生成属性包装，省掉手写一堆OnPropertyChanged(nameof(xxx))的样板代码。这个方向在 WPF、MAUI 这类 MVVM 场景里很有价值，但放到 Unity UI 里，你很快会发现一个问题：Unity 的 uGUI 本身就是一个非常“命令式”的 UI 系统，没有官方数据绑定，ViewModel 的自动化属性往往只对自研 UI 框架有用。
而且，真正做过复杂 Unity UI 的人都懂，写 UI 逻辑时最烦的从来不是多写几个属性。你打开一个技能树面板，里面有几十个节点、连线、Tooltip、滚动视口、按键响应，真正消耗精力的地方是这些对象之间如何互相引用、如何通信、如何保证界面层级与点击区域不错乱。属性包装帮不了这些忙。
如果把 SG 的定位理解成“代码驼鹿”，那你大概率会在项目里引入它之后，只做出一堆生成出来的 getter/setter，然后发现重构 UI 布局时，该断的引用照样断，该找不到的 TextMeshPro 照样被 Panel 挡住。于是结论就变成了“SG 不过如此”，这很可惜。
1.2 Unity UI 的大多数故障来自弱类型断链
我在不同项目里反复见到这几类运行时错误：
- Inspector 里手动拖拽的
[SerializeField]引用，随着 prefab 被反复修改，某一天变成 Missing； - 在代码里用
GameObject.Find("Canvas/Panel/SubPanel/Text")或者一串字符串路径去查节点，UI 里任何一个物体改个名，运行前完全感知不到； - 用
SendMessage("OnSkillClicked", ...)或者 UnityEvent 的字符串方法名做通信，方法一旦改名，Inspector 和代码都不会报错； - 为了做动态画线或者弹窗遮挡，在大量 Image 上手动开关
RaycastTarget，总有漏网之鱼挡在 TextMeshPro 上面，把鼠标点击和 Tooltip 全部吃光。
这些问题的共同特征是：存在大量编译器无法校验的连接。你在源代码里写了一段“我要连到那个节点”的意图，但这个意图并没有被转译成强类型的代码结构，编译器只能眼睁睁放行。
SG 的价值恰好在于，它能让源生成器读取代码本身的语法和语义信息，把这些弱类型连接变成可检查的强类型结构。不是说它能猜到你场景里有没有那个物体，而是说“你准备如何引用一个 UI 对象”这件事，可以被暴露在编译器的视野里。任何断链如果能在你敲下 Ctrl+S 的时候就变成编译错误，你根本不需要在运行时打开 UI 面板去点来点去找问题。
2. 顺着热词复盘：TextMeshPro 被 UI 挡住的根因与 SG 的连接点
2.1 现象复盘：TMP 文本被挡为什么总在运行期才暴露
先还原一个典型问题画面。你做了一个比较复杂的战斗结算面板，上面有一层 TextMeshPro 用来显示伤害数字或玩家名字，下面还叠着几个半透明的 Panel 和若干 Image。测试的时候你发现，文字显示没问题，但鼠标点击某个按钮时没反应，或者当你把鼠标悬停在玩家名字上时，Tooltip 不弹出来。
这种问题有一个非常典型的排查链路：先查层级顺序，再查 Canvas 下的 GraphicRaycaster，最后查到某个 Image 把RaycastTarget勾上了，射线被它拦截。TextMeshPro 本身也是一个MaskableGraphic，它自己也可以参与射线检测，所以很多时候问题不只是“文字被 Image 挡住”，而是“文字组件自己把射线吃了”，导致它后面的按钮点不到。
为什么会拖到运行期才暴露？因为 UI 的 Raycast 完全由运行时的事件系统决定。编译器不会知道 Canvas 的渲染顺序，不会检查你有几个 RaycastTarget 是多余的，更没法判断 “这个半透明背景是不是要拦截点击”。每次手改一个 prefab 或复制出一个新弹窗，这套配置就要靠人肉重新检查一遍。
2.2 常规修法：开关 RaycastTarget 和 CanvasGroup，本质上都是散落的人工配置
社区里最常见的修法，是把不需要点击的 Image 上的RaycastTarget取消勾选。这方法简单直接，适合一时救火。但它有一个隐性成本：这些勾选状态并没有统一的登记处，也没有代码级的所有者。你可能某一天为了让某个全屏图也响应点击，重新勾上一个RaycastTarget，结果它又把上一层 TMP 的点击拦截了，前一天的修复直接失效。
另一种做法是维护一个“UI 射线控制”公共方法，在面板打开或关闭时批量设置一组组件的raycastTarget = false。这比手动可靠一点，但你要在方法里写大量组件路径或者对象引用，时间一长，代码会退化成又长又脆的字符串清单。
坦白说，SG 并不能直接帮你决定哪一层该挡、哪一层不该挡，它也不是引擎的射线检测补丁。这类问题的最终技术答案还是Canvas层级、GraphicRaycaster以及各组件的raycastTarget搭配问题。但 SG 能解决一个非常实际的工程问题：把“哪些 UI 元素参与射线交互”这份配置变成一个可以由编译器审查的静态清单。
比如你可以在代码里标记一个类：
public class DamageNumberView : MonoBehaviour { // 不参与点击拦截，仅用于飘字展示 }SG 扫描到这类标记后，可以生成一个静态配置类，把所有“应禁用射线拦截”或“应允许拦截”的目标类型集合出来，再配合编辑器的 OnValidate 或一个检查脚本去比对实际场景里的组件状态。这样一来，场景里的 RaycastTarget 勾选状态不再是藏在 prefab 里的不可见配置，而是一份带编译期依据的契约。谁要是新建了一个全屏 Image 挡住了 TMP，代码评审和脚本检查都能直接指出来。
2.3 真正的教训：你缺的不是一个个修，是一张 UI 射线交互地图
回头看这个热词问题，很多人从搜索引擎找到的答案都是“把 RaycastTarget 关掉”，这种点状修复我当然也用过。但做多了以后你会发现，UI 工程里更多时候缺的不是某个开关，而是一张“射线交互地图”——哪些 UI 是纯展示、哪些 UI 要接收点击、哪些 UI 处于弹窗层、哪些 UI 永远不拦截射线。只要这张地图没有被明确写下来，就会反复出现挡到的问题。
SG 的定位在这里非常清楚：它不能当运行时指南针，但它是画地图的好工具。它能把代码里被 Attribute 标明的 UI 意图静态汇总，生成可以被其他代码和 Editor 工具读取的强类型配置。每次关掉一个 RaycastTarget，都是在对地图说“这个区域不参与交互”，而不再是一次性手改。
3. 实践案例：动态画线节点的强类型注册是怎么生成的
3.1 为什么用“动态画线”来举例
“unity ui 动态画线”这个搜索词这几年一直挺热，因为现在很多项目会做技能树连线、地图路径、流程图编辑器，甚至抽卡连线动画。要在 uGUI 上动态画一条线，方案很多：用自定义 Graphic 重写 OnPopulateMesh，用 LineRenderer 叠在 UI Camera 上，或者用现成的 UILineRenderer 插件。线本身不难画，难的是它所连接的那些节点。
拿技能树来说，每个技能节点是一个带 Icon、名称、冷却 CD 的 UI 部件，节点之间存在前后置关系，点击节点时要弹出详情页，还要把多个节点连成一条完整的成长线。你真正需要维护的是节点的引用、坐标、点击回调、以及线与线之间的空间关系。当节点数量从 5 个涨到 50 个，你会发现手写字段根本维护不过来。
3.2 平时那种“数组拖上去 + Find 路径”的做法为什么会痛
很多团队的做法是直接在面板上拖一个节点数组：
[SerializeField] private SkillNodeWidget[] nodes;这种代码写起来确实快，但隐患也不少。第一，有人从 prefab 里加了一个新节点，忘了拖进数组，运行时该节点就不存在于连线系统。第二，节点之间要连线时，你不得不通过名字去找目标 RectTransform，一旦改名，断链。第三，节点类型或者方法名变了，旧的字符串查找根本不会提醒你。
当然你也可以写编辑器脚本来做数据校验，但往往只有项目到测试阶段才发现一堆“空引用”。这背后的本质，是节点注册表没有在编译期被确立下来。
3.3 让 SG 生成一个节点注册表，而不只是替你打一堆字
我在项目里试过一种模式：用 Attribute 标记 UI 节点或者连线端点，再由 SG 读取当前编译单元里所有被标记的成员，为它们生成静态注册类。
比如你定义一个 Attribute：
[AttributeUsage(AttributeTargets.Field)] public sealed class LineEndpointAttribute : Attribute { public string Key { get; } public LineEndpointAttribute(string key) { Key = key; } }实际使用时：
public class SkillTreeLineController : MonoBehaviour { [LineEndpoint("start")] public RectTransform startPoint; [LineEndpoint("end")] public RectTransform endPoint; }SG 在编译期扫描这个类里所有带LineEndpointAttribute的字段，自动生成一个 partial 类。这个生成物里包含所有端点的强类型入口：
public partial class SkillTreeLineController { // 以下是 Source Generator 生成的代码，请勿手动修改 public enum LineEndpointKey { start, end } public RectTransform GetEndpoint(LineEndpointKey key) { switch (key) { case LineEndpointKey.start: return startPoint; case LineEndpointKey.end: return endPoint; default: throw new System.ArgumentOutOfRangeException(nameof(key), key, null); } } public void SetEndpoint(LineEndpointKey key, RectTransform value) { switch (key) { case LineEndpointKey.start: startPoint = value; break; case LineEndpointKey.end: endPoint = value; break; } } }这段生成的代码价值在哪？不是帮你少写了几个字段，而是你在其他地方引用连线端点时，不再需要写"start"这种魔法字符串，而是写controller.GetEndpoint(SkillTreeLineController.LineEndpointKey.start)。如果startPoint字段在重构中被删掉，生成代码会自动消失，所有引用它的编译错误会立刻列出来；如果字段类型从RectTransform改成Transform，调用处同样会立即报类型错误。
这才是 UI 领域真正需要的“代码生成”：把引用从人的记忆和字符串里，搬进编译器的视野里。
3.4 动态连线时被 TMP 和按钮“夹击”的坑
画线本身还会碰到另一层 UI 干扰：线条画出来后如果不做射线处理，它会挡住底下节点的点击；如果它不参与任何交互，又可能被 Tooltip 文本或者节点 Icon 盖住。当你动态创建大量线时，这个问题会被放大。
SG 在这种场景下可以做的是配合属性生成一个“不需要参与交互”的静态标记类，帮你把所有动态线条统一归类。线条组件在实例化后，可以根据这个静态类决定是否关闭自己的 RaycastTarget、是否设置 CanvasGroup 的 blocksRaycasts。这个标记不是散落在场景文件里，而是代码层面确定的契约，后续新同事接手的阻力会小很多。
4. 把 UI 事件连接从字符串/反射提升为编译期闭环
4.1 UI 模块一多，全局事件字符串成了最大的隐患
很多 Unity UI 项目会封一个类似MessageCenter的全局事件总线。发消息的人写MessageCenter.Send("SkillNodeClick", nodeId)，收消息的人写MessageCenter.AddListener("SkillNodeClick", OnSkillNodeClick)。这种模式解耦了面板与面板，但字符串常量一旦拼错，编译器没有任何反馈，只有运行时不触发回调。等你在几十个 UI 脚本里查一个漏掉的监听，能查掉半个下午。
反射在这个链路里也常见，比如用某个名称去查找方法或属性，然后通过Invoke调用。反射在纯 Editor 环境下问题不大，但一旦上了 IL2CPP，加上代码裁剪和泛型，很容易出现“编辑器里跑得好好的，真机上某个 UI 事件彻底没反应”的现象。
4.2 SG 生成事件门面：让发送方和接收方都走强类型入口
事件通信的最佳形式，是给每个事件语义建立一个类型或者方法入口。SG 完全可以自动做这件事。
你可以定义一个特性：
[AttributeUsage(AttributeTargets.Struct)] public sealed class UIEventAttribute : Attribute { }然后在某个公共命名空间里写下要做成事件的消息结构：
[UIEvent] public partial struct SkillNodeClicked { public int NodeId; public Vector3 ScreenPosition; }Source Generator 扫描到带UIEventAttribute的类型后，生成一个静态发送器：
public static class SkillNodeClickedEvent { public static void Raise(int nodeId, Vector3 screenPosition) { UIRouter.Raise(new SkillNodeClicked { NodeId = nodeId, ScreenPosition = screenPosition }); } }接收方不再直接监听一个字符串，而是通过生成的门面订阅这个事件：
public class SkillNodeTooltip : MonoBehaviour { private void OnEnable() { SkillNodeClickedEvent.AddListener(OnSkillNodeClicked); } private void OnDisable() { SkillNodeClickedEvent.RemoveListener(OnSkillNodeClicked); } private void OnSkillNodeClicked(SkillNodeClicked evt) { // do something } }这样修改后，任何事件名写错的情况都会变成编译错误，因为你要调用的就是SkillNodeClickedEvent.Raise这个方法。事件结构体字段发生变化时，所有 Raise 调用也会被编译器强制同步。这套方案在 IL2CPP 下同样安全，因为它没有反射参与，所有代码都在编译期变成了直接的静态方法调用。
4.3 和手写一个静态类相比，SG 到底多做了哪些事
这里有一个很自然的疑问：既然最终代码就是一个静态类和一个事件结构，那我手写不也行吗？何必引生成器。
区别在于维护成本和一致性：当 UI 事件从 10 个涨到 100 个时，手写的东西很容易漏掉AddListener和RemoveListener的成对实现，或者忘记把事件注册到UIRouter里。只要 Generate 一次，这些机械且容易出错的代码就永远不会漏。更重要的是，生成器可以基于整个编译单元的“结果”来生成，比如它可以检查是否所有事件结构都被正确命名，是否有两个事件用了相同的路由标识，并在编译期把这些冲突报出来。
这种“代码生成 + 自定义诊断”的组合，才是 Unity UI 工程里真正值钱的地方。它不只是在替我们打字，而是在替我们做静态分析，确保 UI 事件层的规则被大家统一遵守。
5. 接入 Unity 工程的工程化细节和常见坑
5.1 生成器程序集应该怎么放
如果你打算在项目里上 SG，不要图省事直接把它和游戏代码放同一个 asmdef。源生成器本身是一个纯 .NET Standard 的库，它运行在 Roslyn 编译进程里，不应该依赖 UnityEngine。你要做的是建一个独立目录，比如Assets/SourceGenerators/MyUiGenerator，给它单独配一个 asmdef，目标框架选.NET Standard 2.0，然后从 NuGet 拉一份Microsoft.CodeAnalysis.CSharp的包引用。具体版本要和当前 Unity 内置的 Roslyn 版本匹配，不同版本错位时生成器可能直接在编辑器里抛异常。
Unity 2021.2 以后的版本已经内置了源生成器执行环境，但这个环境本身不负责替你管理 NuGet。常见的操作是用某个 NuGet 客户端或者手动把 DLL 放进一个Plugins文件夹，保证它可以被编译进程加载。如果你用 asmdef，还需要记得把生成器程序集的 autoReferenced 设成 false，再在需要它的程序集里显式引用，避免每个程序集都把它拉进去。
5.2 生成器里写 Unity API 是大忌
我一开始踩过一个大坑：想在生成器内部调用UnityEditor.AssetDatabase.LoadAssetAtPath，去 prefab 里读节点列表，然后生成节点枚举。结果生成器在编译进程里运行时，根本没有加载 Unity 编辑器程序集，或者即使加载了，AssetDatabase 的上下文也不可用。
结论是：SG 只能处理编译器能看到的元数据与语法树。它不能查场景文件、不能读 AssetBundle、不能依赖运行时注册表。所有需要访问 Unity 资源库的逻辑，都不适合塞进生成器，而应该写在编辑器脚本里，在进入编译之前或者编译完成之后执行。
如果你确实需要把场景里的节点列表变成强类型代码，正确的做法是两步走：编辑器脚本负责把资源里的信息导出成一个中间文件，然后 SG 读这个中间文件并生成代码。这样既保留了 SG 的强类型优势，又不至于去生成器里硬刚 Unity API。
5.3 用增量生成器，别让每次编译都全量扫项目
SG 刚流行的那段时间，很多人用ISourceGenerator接口写生成器，每次编译都把所有 SyntaxTree 翻一遍。Unity 的一大特点是脚本编译极其频繁，你切一次窗口、加一个空格都会触发重编译。如果生成器每次都要扫描上万行代码并重复生成，编辑器会很卡。
新一点的 API 是IIncrementalGenerator，它允许你按SyntaxProvider和ForAttributeWithMetadataName这种粒度做增量计算。只有被 Attribute 标记的类型发生变化时，生成逻辑才会重新执行。无论你是给 Unity UI 写事件门面还是节点注册表，都应该尽量走增量生成的结构。
另外，如果想给生成器写单元测试，可以在测试工程里直接使用CSharpGeneratorDriver，把一段字符串形式的示例代码编译进内存，再检查生成的文本是否符合预期。Unity 项目不一定非要在 Unity 编辑器里跑这套测试，你可以放到一个独立的 .NET 测试项目里，速度会快很多。
5.4 生成出来的代码别提交，但生成逻辑一定要可调试
默认情况下，源生成器生成的文件不会出现在你的项目目录里。有些人为了“看得见”，会把这些生成结果拷贝一份提交到版本库，这非常不推荐。拷贝出来以后，实际编译用的代码和你仓库里的代码会出现双份，重构时维护成本极高。正确做法是把生成器逻辑当一个“编译期的黑盒”，通过单元测试和快照验证输出内容，而不是把它产物化。
调试生成器时有一个很实用的技巧：在生成器代码里不要用Debug.Log，因为那是在编译进程里运行的，输出普通日志非常不可控。应该在发现异常或不一致时用context.ReportDiagnostic报告一条诊断信息，Unity 会因为编译器报了错误或警告而把消息显示在 Console 窗口里。这样你至少保留了可见的错误反馈链路。
5.5 SG 的边界：哪些 UI 问题它真的救不了
最后必须把边界说清楚。SG 不能做的事情比能做的事情还重要。第一，它看不到场景里某个 prefab 的实际层级状态，所以“拖拽引用在 prefab 修改后丢失”这个问题它没有办法直接感知，需要搭配编辑器脚本对 prefab 和场景做检查。第二，它不能解决 TMP 被 UI 挡住的物理层面问题，挡没挡住最终还是由 Canvas 渲染顺序和 GraphicRaycaster 决定。第三，它不适用于那种“动态变化极其频繁、每一次运行时状态都不同”的逻辑，比如每帧都在变化的自定义连线坐标，那种东西应该是普通运行时代码的范畴，不是编译期生成器的主场。
带着这个边界认知去衡量项目里的痛点，你会更容易判断某件事适不适合上 SG。
6. 我的选型经验和最后一点技巧
6.1 项目规模到了什么程度，才值得引入 SG
Unity UI 模块如果只有两三个面板，手动拖引用和字符串事件根本没有生存压力，上 SG 反而是提前复杂化。可一旦界面数量开始膨胀，比如出现技能树、地图、邮件、商店、背包等好几十个界面，并且界面之间存在连线、遮挡、动态创建、事件通知时，弱类型连接造成的 Bug 会成为开发效率的隐形杀手。这时候引入 SG 才有明确的收益：它能把数量最多、最容易错的那批“连接代码”变成编译器可校验的静态结构。
作为选型参考，我一般是这么判断的：如果某个 UI 模块里，字符查找路径超过 50 处，或者全局事件字符串超过 30 个，或者需要在多个脚本里维护同一组 UI 元素引用，就值得用生成器做一遍体检并生成静态门面。
6.2 个人技巧：让生成代码标记来源，避免调试进黑洞
即使做了边界内的事情，生成的代码仍然会给调试带来困惑。我的习惯是在生成器输出的类上打[GeneratedCode("MyUiGenerator", "1.0")]标签，这样在异常堆栈里可以明显看出这行代码来自生成器，而不是手写。如果你的 Unity 调试器允许跳过某些代码，可以给生成的成员加上 DebuggerNonUserCode 特性，这样单步调试时不会一头扎进大量生成的方法体。
另一个经验是，生成器里的 Attribute 尽量不写在业务文件之外，而是与目标代码放在一起，比如把UIEventAttribute定义放在一个公共 UI 程序集中。Attribute 本身要能被目标代码引用，而生成器只需要通过字符串方式识别它的名字，太多额外耦合会让生成器很难复用。
6.3 这类方案后续还能怎么扩展
SG 在 Unity UI 里的扩展空间，我目前比较看好两个方向：一是和 UI Toolkit 的 UXML 结合，让模板里的元素名通过生成器变成强类型访问器；二是把它当作 UI 自动化测试的元数据入口，生成器输出一套可供测试框架调用的节点检索表，减少测试脚本里写大量元素路径。这两个方向暂时还有很多工程细节要打磨，但方向是确定的——把 UI 的隐式约定逐渐变成显式的、编译期可检查的代码结构。
在实际项目里跑通这套方案之后，我对 SG 的理解也从“代码生成器”变成了“编译期契约工具”。面对 Unity UI 这类所有事情都要等到运行期才见真章的系统，把尽量多的错误提前到编译阶段暴露，价值远大于让代码少打几行。
