1. 为什么要在Shader编辑器里折腾ToolTip
如果你写过自定义的ShaderGUI，或者给美术同学做过Shader参数面板，大概率遇到过这个场景：美术跑过来问“这个滑块到底是调什么的”，你只能翻出代码一行行解释。Shader的Inspector面板天生就比普通MonoBehaviour面板复杂，因为大量参数是浮点、向量、纹理，光看名字根本猜不出用途。Unity原生的ShaderInspector对ToolTip的支持其实很有限，[Tooltip]特性在Shader属性块里根本不生效，这是很多人第一次踩的坑。
我在几个渲染管线项目里都遇到过这个问题，尤其是做角色材质、后处理堆栈这类参数密集的Shader时，一个面板上几十个属性，没有提示信息简直是灾难。后来我决定在自定义ShaderEditor里把ToolTip这套机制补上，让鼠标悬停就能看到参数说明。这件事听起来简单，但实际做下来涉及GUIContent的构造、EditorGUILayout的布局控制、以及如何从Shader属性块里解析出注释信息这几个关键点。这篇内容就是把这套方案的完整实现思路和踩过的坑整理出来，适合已经写过基础ShaderGUI、想进一步提升编辑器体验的开发者。如果你还没接触过ShaderGUI，建议先补一下ShaderGUI基类和MaterialEditor的基本用法，不然下面的内容会有点吃力。
核心思路其实一句话就能概括：把Shader属性块里的注释当作ToolTip内容，在绘制每个属性时构造带tooltip的GUIContent。但魔鬼在细节里，怎么解析注释、怎么保证不破坏原有布局、怎么处理不同类型的属性，这些才是真正花时间的地方。
2. Shader属性块里的注释到底能不能被读到
2.1 Unity对Shader属性的解析机制
要理解为什么[Tooltip]在Shader里不生效，得先搞清楚Unity是怎么解析Shader文件的。Shader文件本质上是一段类ShaderLab的文本，Unity在导入时会用内部的解析器把Properties块里的每个属性提取出来，生成一个Shader对象，属性信息存在Shader.GetPropertyCount()和Shader.GetPropertyName()这些API背后。关键点在于：这个解析器只认属性声明本身，不认C#那种特性语法。你在属性前面写[Tooltip("xxx")]，Unity的Shader编译器会直接忽略，甚至可能报语法警告。
那注释呢？//开头的注释在ShaderLab里是合法的，Unity的解析器会跳过它们，但不会把它们和属性关联起来。也就是说，Unity本身没有提供任何从Shader文件读取属性注释的官方API。这是整个方案最大的障碍，也是为什么很多人做到一半就放弃了。
我试过几种绕过的思路。第一种是用ShaderUtil.GetShaderPropertyDescription之类的内部API，但这些API要么不公开，要么返回的信息里根本没有注释。第二种是反射读取Shader对象的私有字段，实测下来不同Unity版本字段名不一样，维护成本太高。第三种就是最笨但最稳的办法：自己读Shader源文件，手动解析Properties块。听起来土，但可控性最强，而且Shader文件路径可以通过AssetDatabase.GetAssetPath(shader)拿到，读取完全没问题。
2.2 手动解析Properties块的完整逻辑
解析的核心是逐行扫描Shader文本，定位Properties块的起止位置，然后对每一行做模式匹配。一个典型的属性行长这样：
// 基础颜色，控制整体色调 _BaseColor ("Base Color", Color) = (1,1,1,1)我的解析策略是维护一个“待定注释”变量。遇到//开头的行，就把内容存起来；遇到属性声明行，就把存起来的注释和这个属性名绑定；遇到空行或者其他内容，就清空待定注释。这样能处理注释在属性上方的情况，这也是最常见的写法。
private Dictionary<string, string> ParseTooltips(string shaderPath) { var result = new Dictionary<string, string>(); var lines = File.ReadAllLines(shaderPath); string pendingComment = null; bool inProperties = false; int braceDepth = 0; foreach (var rawLine in lines) { var line = rawLine.Trim(); if (!inProperties) { if (line.StartsWith("Properties")) { inProperties = true; braceDepth = 0; } continue; } if (line.StartsWith("{")) { braceDepth++; continue; } if (line.StartsWith("}")) { braceDepth--; if (braceDepth <= 0) break; continue; } if (line.StartsWith("//")) { pendingComment = line.Substring(2).Trim(); continue; } // 匹配属性声明：_Name ("Display", Type) = Default var match = Regex.Match(line, @"^(\w+)\s*\("); if (match.Success && pendingComment != null) { result[match.Groups[1].Value] = pendingComment; pendingComment = null; } else if (string.IsNullOrEmpty(line)) { pendingComment = null; } } return result; }这段代码有几个细节值得说。braceDepth的处理是为了应对Properties块里可能出现的嵌套结构，虽然标准Shader里Properties块一般不会嵌套，但有些自定义写法会加额外的花括号，保险起见还是处理一下。正则^(\w+)\s*\(只匹配属性名后面紧跟左括号的情况，能过滤掉大部分非属性行。pendingComment在遇到空行时清空，是为了避免注释和属性之间隔了太多行导致误关联。
注意：这个解析器假设注释紧贴在属性上方。如果你的项目里习惯把注释写在属性行末尾，需要额外处理行内
//的情况，逻辑会复杂一些，建议统一团队规范，注释一律写在属性上方。
2.3 缓存策略：别每次重绘都读文件
OnGUI在编辑器里调用频率非常高，鼠标移动、窗口重绘都会触发。如果每次OnGUI都去读Shader文件、跑正则，性能会很差，尤其是Shader文件大的时候。我的做法是在ShaderGUI.OnShaderChanged或者第一次OnGUI时解析一次，把结果缓存在字典里，后续直接用。
private Dictionary<string, string> _tooltipCache; private Shader _cachedShader; public override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] properties) { var shader = materialEditor.target is Material mat ? mat.shader : null; if (shader != _cachedShader) { _cachedShader = shader; var path = AssetDatabase.GetAssetPath(shader); _tooltipCache = ParseTooltips(path); } // 后续绘制逻辑 }这里用_cachedShader做变更检测，只有Shader换了才重新解析。注意AssetDatabase.GetAssetPath对内置Shader会返回空字符串，这种情况直接跳过解析，用空字典兜底，不然会抛异常。
3. 把注释变成ToolTip的绘制改造
3.1 GUIContent的构造与EditorGUILayout的配合
Unity的IMGUI体系里，ToolTip是通过GUIContent的tooltip字段实现的。当你把一个带tooltip的GUIContent传给EditorGUILayout.PropertyField或者GUILayout.Label，鼠标悬停时Unity会自动弹出提示框。所以核心工作就是把原来直接传property.displayName的地方，改成传一个构造好的GUIContent。
private GUIContent GetContent(MaterialProperty prop) { string tooltip = null; _tooltipCache?.TryGetValue(prop.name, out tooltip); return new GUIContent(prop.displayName, tooltip); }看起来很简单对吧？但实际用的时候会发现一个问题：EditorGUILayout.PropertyField有个重载是接受GUIContent的，但如果你用的是MaterialEditor.DefaultShaderProperty或者ShaderProperty，它们内部对label的处理逻辑不一样，有些版本会忽略你传进去的tooltip。我实测下来，最稳的方式是自己用EditorGUILayout.PropertyField(prop, content)，而不是依赖MaterialEditor的封装方法。
public override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] properties) { // ...缓存逻辑 foreach (var prop in properties) { var content = GetContent(prop); EditorGUILayout.PropertyField(prop, content); } }这样每个属性都会带上tooltip。但代价是你失去了MaterialEditor默认的一些布局优化，比如纹理属性会自动带缩略图、颜色属性会带拾色器。这些需要自己补回来，后面会讲。
3.2 不同属性类型的差异化处理
Shader属性有好几种类型：Float、Range、Color、Vector、Texture、Int。EditorGUILayout.PropertyField对大部分类型都能自动识别并绘制合适的控件，但Texture类型有个坑：默认绘制出来的纹理槽位没有缩略图预览，美术同学会很不习惯。我的做法是对Texture类型单独处理，用MaterialEditor.TextureProperty，但它不接受GUIContent参数，所以tooltip得换个方式加。
if (prop.type == MaterialProperty.PropType.Texture) { // TextureProperty不支持GUIContent，用Label补tooltip var label = new GUIContent(prop.displayName, GetTooltip(prop.name)); EditorGUILayout.LabelField(label); materialEditor.TextureProperty(prop, string.Empty); } else { EditorGUILayout.PropertyField(prop, GetContent(prop)); }这样纹理属性上方会有一个带tooltip的标签，下面跟着纹理槽位。虽然不如原生PropertyField紧凑，但功能上没问题。Range类型要注意，EditorGUILayout.PropertyField会自动绘制成滑块，tooltip也能正常显示，不需要特殊处理。Color类型会弹出拾色器，tooltip同样有效。
| 属性类型 | 推荐绘制方式 | ToolTip支持情况 |
|---|---|---|
| Float | EditorGUILayout.PropertyField | 原生支持 |
| Range | EditorGUILayout.PropertyField | 原生支持 |
| Color | EditorGUILayout.PropertyField | 原生支持 |
| Vector | EditorGUILayout.PropertyField | 原生支持 |
| Texture | Label + TextureProperty | 需手动补Label |
| Int | EditorGUILayout.PropertyField | 原生支持 |
3.3 分组与折叠对ToolTip的影响
实际项目里，Shader属性通常会分组显示，用MaterialEditor的ShaderProperty配合BeginFoldoutHeaderGroup做折叠。折叠组本身也可以有tooltip，这个用EditorGUILayout.BeginFoldoutHeaderGroup的GUIContent参数就能实现。但要注意，折叠组内的属性在折叠状态下不会触发OnGUI绘制，所以tooltip缓存必须在折叠之前就准备好，不能依赖绘制时懒加载。
var groupContent = new GUIContent("基础设置", "控制材质的基础颜色和透明度"); bool expanded = EditorGUILayout.BeginFoldoutHeaderGroup(_foldoutState, groupContent); if (expanded) { foreach (var prop in groupProperties) { EditorGUILayout.PropertyField(prop, GetContent(prop)); } } EditorGUILayout.EndFoldoutHeaderGroup();这里_foldoutState需要自己维护，通常用MaterialEditor的serializedObject或者一个静态字典按材质实例存储。我一般用SessionState或者EditorPrefs存折叠状态，这样关闭Unity再打开还能记住上次的展开情况，体验会好很多。
4. 实测中遇到的几个坑和绕行方案
4.1 注释解析的边界情况
第一个坑是多行注释。有些Shader里属性说明比较长，会写成多行：
// 这个参数控制高光强度 // 范围0到1，越大越亮 _Specular ("Specular", Range(0,1)) = 0.5我的解析器只取最后一行注释，前面的会丢。改进方案是用一个List<string>收集连续的注释行，遇到属性时用换行符拼接。但ToolTip太长会显示不全，Unity的tooltip框有最大宽度限制，所以实际用的时候建议注释控制在一行内，太长就精简。
第二个坑是属性名大小写。Shader属性名是大小写敏感的，但有些项目里注释和属性名之间可能有空格差异，正则匹配时要注意\w+已经涵盖了大小写字母和下划线，一般没问题。但如果属性名里有数字开头（虽然不合法但有人这么写），\w+也能匹配，不过Unity本身会报错，所以不用太担心。
第三个坑是内置Shader。AssetDatabase.GetAssetPath对Unity内置的Shader（比如Standard、Unlit）返回空字符串，这时候解析会失败。我的处理是加个判断，路径为空就直接返回空字典，绘制时tooltip为null，GUIContent会自动忽略，不会报错。
4.2 ToolTip不显示的几种可能原因
实测下来，tooltip不显示通常有这几个原因。第一是GUIContent构造时tooltip传了null或空字符串，这种情况Unity不会弹提示，检查一下缓存字典里有没有对应key。第二是PropertyField的重载选错了，如果你用的是EditorGUILayout.PropertyField(prop)不带GUIContent参数，那tooltip永远不会显示。第三是编辑器皮肤问题，某些自定义皮肤或者旧版本Unity对tooltip的渲染有bug，换回默认皮肤试试。
还有一个比较隐蔽的原因：属性被禁用（disabled）。如果你用EditorGUI.BeginDisabledGroup包住了属性，tooltip在某些Unity版本里会失效。这个我没找到完美的解决办法，只能尽量避免在禁用组里放需要tooltip的属性。
提示：调试tooltip是否生效，可以在
GetContent里加一行Debug.Log(content.tooltip)，确认内容确实被构造出来了。如果日志有输出但界面不显示，那就是绘制方式的问题。
4.3 性能与缓存失效的处理
前面提到用_cachedShader做缓存，但有个场景会出问题：Shader文件被修改后，缓存不会自动刷新。比如你在编辑器里改了Shader的注释，Inspector面板不会立即更新，得手动刷新或者重新选中材质。解决办法是监听AssetDatabase的刷新事件，或者用EditorApplication.update定期检查文件修改时间。
private DateTime _lastWriteTime; private void CheckShaderModified() { var path = AssetDatabase.GetAssetPath(_cachedShader); if (string.IsNullOrEmpty(path)) return; var writeTime = File.GetLastWriteTime(path); if (writeTime != _lastWriteTime) { _lastWriteTime = writeTime; _tooltipCache = ParseTooltips(path); } }在OnGUI开头调用CheckShaderModified，这样Shader一保存，tooltip就会更新。文件IO在编辑器里开销不大，而且GetLastWriteTime比读整个文件轻量得多，实测对帧率没有明显影响。
5. 让这套机制更好用的几个扩展思路
5.1 从注释里提取更丰富的元信息
既然已经能解析注释了，不妨把注释格式规范化，让它携带更多信息。比如用@符号标记特殊字段：
// @group 基础设置 // @tip 控制整体色调，影响漫反射颜色 _BaseColor ("Base Color", Color) = (1,1,1,1)解析时识别@group就把属性归到对应分组，识别@tip就作为tooltip内容。这样一套注释既能驱动分组，又能驱动tooltip，Shader文件本身就是配置源，不用额外维护C#代码里的映射表。我在一个后处理Shader项目里用了这套方案，新增属性时只改Shader文件，C#端完全不用动，维护成本降了很多。
5.2 支持富文本和快捷键提示
Unity的tooltip支持简单的富文本标签，比如<b>加粗、<color>改色。你可以在注释里直接写这些标签，GUIContent会原样传给tooltip渲染器。实测<b>和<i>是生效的，<color>在部分Unity版本里有效，可以试试。另外，如果某个参数有快捷键操作（比如按住Shift拖动可以微调），也可以在tooltip里写清楚，美术同学会觉得很贴心。
5.3 和MaterialPropertyDrawer的配合
如果你已经用了MaterialPropertyDrawer来做自定义绘制，tooltip的注入点会不一样。Drawer的OnGUI方法里拿不到外部的GUIContent，需要自己在Drawer内部构造。我的建议是把tooltip解析逻辑抽成一个静态工具类，Drawer和ShaderGUI都调这个工具类，避免重复代码。
public static class ShaderTooltipUtility { public static string GetTooltip(Shader shader, string propertyName) { // 缓存 + 解析逻辑 } }这样无论你在哪里绘制属性，都能拿到tooltip内容。Drawer里用EditorGUILayout.PropertyField时传入构造好的GUIContent即可。
5.4 多语言支持的可行性
如果项目有出海需求，tooltip可能需要多语言。我的做法是在注释里用|分隔不同语言，比如// 基础颜色|Base Color，解析时按当前编辑器语言选对应文本。Unity有Application.systemLanguage可以判断，但编辑器语言和系统语言不一定一致，更稳的方式是读EditorPrefs里的语言设置。这套方案我还没在正式项目里大规模用，因为维护多语言注释本身也是成本，小项目没必要。
6. 一些实操中的个人体会
这套ToolTip机制我在三个项目里落地过，最大的感受是：Shader注释的规范比代码实现更重要。代码写一次就固定了，但注释是团队每个人都要写的，如果规范不统一，解析出来的tooltip会乱七八糟。我的建议是在项目初期就定好注释格式，比如“注释必须紧贴属性上方，单行不超过30字，用中文描述用途”，然后在Code Review里检查。
另一个体会是不要过度依赖tooltip。tooltip是辅助，属性名本身应该尽量自解释。如果某个参数必须靠tooltip才能看懂，那可能是命名有问题。我见过一个Shader属性叫_Param1，tooltip写了一大段解释，这种就是典型的命名失败。好的做法是属性名用_RimPower、_SpecularIntensity这种一看就懂的词，tooltip只补充取值范围和特殊行为。
最后分享一个小技巧：在GetContent里可以给tooltip加个前缀，比如[范围0-1]，这样美术一眼就能看到取值范围，不用把范围写进注释里。这个前缀可以根据属性类型自动生成，Range类型自动加范围，Color类型加“点击选择颜色”，Texture类型加“拖入纹理资源”。这种自动化的小细节，用起来会觉得很顺手。
这套方案的核心代码量其实不大，解析加绘制加起来两三百行，但带来的编辑器体验提升很明显。如果你也在做ShaderGUI，强烈建议把tooltip这套加上，美术同学的反馈会告诉你值不值得。
