1. 项目概述为什么我们需要一个运行时检视器在Unity开发中尤其是制作编辑器工具、调试复杂逻辑或者开发需要实时调整参数的运行时应用如游戏、模拟器、数字孪生时我们常常会羡慕编辑器的Inspector窗口。它能让我们直观地看到并修改任何GameObject或组件的属性。但一旦打包成应用这个强大的调试工具就消失了。你只能依赖日志输出、自定义UI或者反复打包测试效率极低。这就是UnityRuntimeInspector的价值所在。它本质上是一个在游戏运行时Runtime复现了Unity编辑器Inspector和Hierarchy面板功能的插件。你可以把它想象成一个“随身携带的编辑器”直接嵌入到你的游戏UI中。无论是调整一个角色的移动速度实时修改光照参数还是查看某个复杂脚本内部变量的实时状态它都能做到。对于需要现场演示、快速迭代或者为玩家提供高级自定义功能的项目来说这几乎是不可或缺的工具。我最初接触这个插件是在开发一个策略游戏的关卡编辑器时。策划和测试同学需要在真机上快速调整单位的属性而不想每次都麻烦程序员重新打包。UnityRuntimeInspector完美地解决了这个问题。但和所有强大的工具一样用起来顺手之前总得踩几个坑。这篇文章我就结合自己多年的使用经验把那些官方文档可能没细说但在实际项目中高频出现的问题和解决方案给你一次性讲透。2. 核心问题一安装与基础配置的“坑”别看安装就是拖个Prefab这里面的门道决定了你后续使用的顺畅程度。2.1 安装方式选择与版本兼容性项目提供了多种安装方式UnityPackage、Git URL、OpenUPM。我强烈推荐使用Package Manager Git URL的方式。这不仅仅是为了方便更新更重要的是能更好地管理依赖避免项目库中散落一堆DLL文件。在Package Manager中点击“”号选择“Add package from git URL”然后填入https://github.com/yasirkula/UnityRuntimeInspector.git。这种方式会将插件作为项目的一个包来管理清晰明了。第一个大坑Unity版本与Input System。如果你使用的是Unity 2019.2.5或更早的版本并且项目启用了新的Input System包你会遇到编译错误。因为旧版本Unity不支持新的Input System。解决方案是在Player Settings的Scripting Define Symbols中为对应平台添加ENABLE_INPUT_SYSTEM这个编译指令。但请注意这个指令是平台特定的。如果你之后切换了构建平台比如从PC切换到Android必须记得为新的平台也手动添加一次这个指令否则在新平台上又会报错。这是很多人容易忽略的一点。第二个坑Unity 2018.4及更早版本。在这些老版本上插件引用的Unity.InputSystem程序集可能无法解析。解决方法是找到插件的Runtime程序集定义文件RuntimeInspector.Runtime.asmdef在它的Assembly Definition References列表中手动移除对Unity.InputSystem的引用。虽然这会失去对新Input System的支持但在老版本上这是唯一的办法。2.2 Prefab拖入场景后的基础连接安装好后你会看到RuntimeHierarchy和RuntimeInspector两个Prefab。把它们拖到你的Canvas下只是第一步。为了让它们联动起来你需要手动建立连接。单向连接这是最容易被误解的地方。RuntimeHierarchy组件上有一个Connected Inspector属性你把RuntimeInspector的实例拖给它这样在Hierarchy面板中选择物体时Inspector面板就会自动显示该物体的属性。反过来RuntimeInspector组件上有一个Connected Hierarchy属性你把RuntimeHierarchy的实例拖给它这样当你在Inspector中高亮显示一个物体引用字段时Hierarchy面板中的对应物体会被选中。关键点这两个连接是独立的、单向的。只设置一个另一个方向的联动就不会生效。很多新手只连了一个然后抱怨“为什么我点了没反应”。务必检查这两个属性是否都已正确赋值。多实例插件支持在同一个场景中存在多个Inspector和Hierarchy实例并且可以配置成不同的模式。比如你可以用一个Inspector始终监视玩家角色用另一个Inspector来动态检查当前选中的环境物体。3. 核心问题二性能优化与垃圾回收GC控制RuntimeInspector在运行时通过反射Reflection来获取和设置对象的属性值。对于值类型如int, float, Vector3这个过程涉及“装箱”Boxing必然会产生垃圾Garbage从而可能触发垃圾回收GC导致游戏卡顿。在移动平台或性能敏感的场景中这可能是致命的。3.1 理解并调整刷新间隔Refresh Interval这是控制性能最关键的参数位于RuntimeInspector和RuntimeHierarchy组件的Inspector面板上。Inspector的Refresh Interval它决定了属性值在UI上更新的频率。默认是0.25秒4次/秒。每次刷新所有显示的字段都会通过反射获取一次新值。降低频率能显著减少GC压力。对于大多数调试场景设置为0.5秒甚至1秒一次完全足够。你可以在需要精细调整时通过代码临时调高频率调整完再调回去。// 临时提高刷新率进行微调 runtimeInspector.RefreshInterval 0.1f; // ... 执行一些调整操作 ... runtimeInspector.RefreshInterval 1.0f; // 调回省电模式Hierarchy的Refresh Interval和Object Names Refresh IntervalHierarchy的刷新主要是同步物体的创建、销毁和层级关系。访问GameObject.name属性本身也会产生GC。因此插件贴心地分离了Object Names Refresh Interval。你可以让层级结构高频刷新比如0.25秒而让物体名称低频刷新比如2秒这样既能及时反映物体变化又避免了因频繁获取名称而产生的过多垃圾。实操心得不要盲目追求“实时”。根据你的应用场景设定合理的刷新间隔。在移动端我通常将Inspector刷新设为1秒Hierarchy刷新设为0.5秒名称刷新设为5秒。在编辑器内调试时再用回默认值。3.2 对象池容量Pool Capacity与UI元素复用插件内部使用了对象池来复用UI元素如每一行的绘制器避免频繁的Instantiate和Destroy调用。Pool Capacity定义了每种类型UI元素池的初始容量。如何设置在PC或主机平台如果你的Inspector可能需要同时显示大量字段比如展开一个包含上百个元素的数组可以适当调高这个值例如从默认的10调到50。这能避免在需要突然创建大量UI元素时的瞬时开销。不要过度设置池容量并非越大越好。过大的池会占用更多内存。通常只有在性能分析中观察到UI元素频繁创建/销毁导致卡顿时才需要调整这个值。对于大多数情况默认值足够。4. 核心问题三自定义与过滤——打造专属调试面板默认的Inspector会显示对象的所有可序列化字段和属性。但在实际项目中我们往往只想关注特定的一些变量或者需要隐藏一些内部实现细节。4.1 使用Settings资产进行变量过滤这是最直接、无需编码的过滤方式。你可以在RuntimeInspector组件的Settings数组中添加自定义的Settings资产通过Assets - Create - yasirkula - RuntimeInspector - Settings创建。隐藏变量Hidden Variables在这里你可以指定某个类型及其派生类并列出要隐藏的变量名。甚至可以使用通配符*来隐藏该类型的所有变量。场景你有一个Monster基类其中包含内部使用的_pathfindingGrid字段。你不想在运行时调试时让策划看到这个字段就可以为Monster类型添加隐藏变量_pathfindingGrid。暴露变量Exposed Variables这是“隐藏-暴露”模式的另一面。如果你先用*隐藏了某个类型的所有变量然后又想只暴露其中的health和damage就可以在这两个列表里分别添加health和damage。优先级变量的暴露遵循一个过滤链Exposed VariablesHidden VariablesExpose Fields/Properties设置。也就是说如果一个变量在Exposed Variables里它一定会显示如果不在但在Hidden Variables里它一定不显示如果两者都不在则根据Expose Fields和Expose Properties的全局设置来决定。重要提示不要直接修改插件自带的InternalSettings。务必创建自己的Settings资产并添加到Settings数组中。否则插件更新时你的修改可能会被覆盖。4.2 通过脚本API进行动态过滤对于更复杂的、需要根据运行时状态决定的过滤逻辑就需要使用脚本API了。过滤组件列表ComponentFilter你可以为RuntimeInspector指定一个委托在生成GameObject的组件列表时进行过滤。例如隐藏所有MeshCollider组件runtimeInspector.ComponentFilter (GameObject gameObject, ListComponent components) { components.RemoveAll(c c is MeshCollider); };过滤Hierarchy中的物体GameObjectFilter你可以为RuntimeHierarchy指定一个委托决定哪些Transform应该显示在层级树中。例如隐藏所有标签为“EditorOnly”的物体runtimeHierarchy.GameObjectFilter (Transform obj) { return !obj.CompareTag(EditorOnly); };更全局的方法是使用RuntimeInspectorUtils.IgnoredTransformsInHierarchy这个HashSetTransform。添加到这里的Transform会被所有RuntimeHierarchy实例忽略。切记在物体被销毁前要记得从集合中移除否则可能导致内存泄漏因为HashSet持有引用。拦截并改变被检视的对象OnInspectedObjectChanging你可以在对象被检视前进行拦截。例如只允许检视带有Rigidbody的物体runtimeInspector.OnInspectedObjectChanging (previous, newObj) { GameObject go newObj as GameObject; if (go ! null go.GetComponentRigidbody() null) { return null; // 返回null表示阻止检视 } return newObj; // 返回newObj表示允许检视 };5. 核心问题四扩展与自定义绘制器Custom Drawers当内置的绘制器如NumberField, TextField无法满足你的需求时比如你想为一个自定义的InventoryItem类提供一个更友好的、带图标和颜色选择的UI你就需要自定义绘制器。5.1 方法一创建Prefab绘制器灵活但复杂这是最强大的方式你需要创建一个继承自InspectorField或ExpandableInspectorField、ObjectReferenceField的组件并制作成Prefab然后将其添加到Settings资产的Standard Drawers或Reference Drawers列表中。步骤简述创建一个UI Prefab例如一个包含Image图标、InputField数量和ColorPicker按钮的布局。挂载一个继承自InspectorField的脚本。重写关键方法SupportsType(Type type): 返回这个绘制器支持的类型例如typeof(InventoryItem)。OnBound(MemberInfo variable): 当绘制器绑定到一个变量时调用在这里可以获取初始值并更新UI。Refresh(): 当需要刷新显示时调用在这里从Value属性读取最新值并更新UI元素。OnSkinChanged(): 确保你的UI颜色、字体等能适配插件的皮肤系统。在你的UI元素如按钮事件中修改Value属性从而将用户输入写回被绑定的变量。将制作好的Prefab拖入Settings资产中对应类型的列表底部列表从上到下匹配最后一个匹配的生效。这种方式给你完全的UI控制权但工作量较大适合需要特殊布局的复杂类型。5.2 方法二实现IRuntimeInspectorCustomEditor接口简单快捷如果你只是想重新组织或过滤某个已有类型的显示字段这种方式更简单。你不需要创建Prefab只需编写一个C#类。[RuntimeInspectorCustomEditor(typeof(MyCustomData), true)] // true表示也应用于派生类 public class MyCustomDataEditor : IRuntimeInspectorCustomEditor { private NumberField healthField; private TextField nameField; public void GenerateElements(ObjectField parent) { // 只为我们关心的字段创建绘制器 healthField (NumberField)parent.CreateDrawerForVariable(typeof(MyCustomData).GetField(health), 生命值); nameField (TextField)parent.CreateDrawerForVariable(typeof(MyCustomData).GetField(_name), 角色名); // 可以添加自定义的UI元素比如一个按钮 var buttonDrawer parent.CreateDrawer(typeof(void), 打印信息, () null, // Getter无返回值 (val) { // Setter当“字段”被“设置”时触发这里用作按钮回调 MyCustomData data (MyCustomData)parent.Value; Debug.Log($角色: {data.Name}, 生命: {data.Health}); }); // 将按钮的绘制器样式调整得像个按钮需要自定义皮肤或调整代码此处为概念 } public void Refresh() { // 如果需要根据其他字段的值来动态显示/隐藏某些字段可以在这里处理 // 例如当生命值为0时将名字显示为灰色需要访问具体的UI组件 } public void Cleanup() { // 清理任何非托管资源通常不需要做任何事情 healthField null; nameField null; } }关键点你需要告诉RuntimeInspector这个扩展方法持有类在哪里。在你的游戏启动脚本如一个GameManager的Awake方法中添加这行代码RuntimeInspectorUtils.ExposedExtensionMethodsHolder typeof(MyCustomDataEditor);注意ExposedExtensionMethodsHolder是一个Type属性它期望的是一个静态类里面包含了用[RuntimeInspectorButton]标记的扩展方法。对于IRuntimeInspectorCustomEditor通常不需要设置这个除非你同时使用了按钮属性。IRuntimeInspectorCustomEditor的实现类本身通过RuntimeInspectorCustomEditor属性被插件自动发现。5.3 为内置类型添加按钮RuntimeInspectorButton你想在检视Rigidbody时直接加一个“重置速度”的按钮可以通过扩展方法实现。创建一个静态类。为Rigidbody类型编写一个扩展方法并标记[RuntimeInspectorButton]。将包含此扩展方法的类赋值给RuntimeInspectorUtils.ExposedExtensionMethodsHolder。public static class RuntimeInspectorExtensions { [RuntimeInspectorButton(重置速度, false, ButtonVisibility.InitializedObjects)] public static void ResetVelocity(this Rigidbody rb) { if (rb ! null) { rb.velocity Vector3.zero; rb.angularVelocity Vector3.zero; } } } // 在初始化时 RuntimeInspectorUtils.ExposedExtensionMethodsHolder typeof(RuntimeInspectorExtensions);这样当你在RuntimeInspector中检视一个Rigidbody组件时下方就会出现一个“重置速度”的按钮。6. 核心问题五伪场景Pseudo-Scenes的高级用法Hierarchy不仅可以显示Unity的真实场景还能显示你自定义的“伪场景”。这是组织游戏内对象的神器比如“所有敌人”、“所有可交互物体”、“UI特效层”。6.1 动态管理伪场景通过RuntimeHierarchy的脚本API你可以动态添加、移除物体到伪场景。public RuntimeHierarchy runtimeHierarchy; // 将玩家和所有敌人添加到一个叫“Actors”的伪场景 void GroupActors() { ListTransform actors new ListTransform(); actors.Add(player.transform); actors.AddRange(enemyManager.GetAllEnemies().Select(e e.transform)); runtimeHierarchy.AddToPseudoScene(Actors, actors); // 如果“Actors”场景不存在会自动创建 } // 从伪场景移除一个物体如果场景变空则删除该场景 void RemoveActorFromScene(Transform actor) { runtimeHierarchy.RemoveFromPseudoScene(Actors, actor, true); }6.2 使用PseudoSceneSourceTransform组件进行自动同步手动管理列表很麻烦。PseudoSceneSourceTransform组件可以帮你自动同步一个父物体下的所有子物体到指定的伪场景。创建一个空的GameObject命名为“EnemiesContainer”。将所有敌人作为它的子物体。给“EnemiesContainer”添加PseudoSceneSourceTransform组件。在组件的Pseudo Scene Name字段填入“Enemies”。勾选Hide On Disable可选。这样当“EnemiesContainer”被禁用时所有敌人物体会从Hierarchy的伪场景中隐藏但不会从游戏世界中移除。注意事项PseudoSceneSourceTransform是通过监听子物体变化TransformChanged来实现同步的这会有一定的性能开销。如果子物体数量巨大且频繁变动需谨慎使用。7. 常见问题排查与实战技巧实录以下是我在项目中真实遇到的一些问题及其解决方案希望能帮你省下几个小时甚至几天的调试时间。问题现象可能原因解决方案Inspector中字段显示为“(Not Supported)”1. 该字段类型没有对应的内置绘制器。2. 自定义绘制器Prefab未正确添加到Settings中或SupportsType逻辑有误。3. 字段是私有且未标记[SerializeField]同时Expose Fields设置为Serializable Only。1. 检查类型是否为简单可序列化类型。复杂类可能需要自定义绘制器。2. 检查自定义绘制器Prefab是否已放入Settings列表并确保SupportsType方法返回true。3. 将字段改为public或加上[SerializeField]或将Expose Fields改为All不推荐会暴露过多内部字段。拖拽Hierarchy中的物体到Inspector的引用字段无效1. Inspector的Connected Hierarchy未设置。2. Hierarchy的Can Reorganize Items未启用且拖拽操作触发了重新父级化而非赋值。3. 目标字段类型与拖拽的物体类型不匹配例如需要GameObject却拖了一个Transform。1. 检查并设置Connected Hierarchy。2. 如果只想赋值确保Hierarchy的Can Reorganize Items为false或者从Hierarchy拖出时使用长按触发“创建拖拽引用项”而非直接拖拽物体本身。3. Unity的引用赋值通常是类型兼容的GameObject字段可以接受Transform但自定义类不行。检查类型。在移动设备上触摸操作不灵敏或误触发1.Pointer Long Press Duration长按判定时间太短。2.Double Click Threshold双击判定间隔太长或太短。3. UI元素如折叠箭头太小不易点中。1. 针对移动设备将Pointer Long Press Duration从默认的0.5秒提高到0.8-1.0秒。2. 调整Double Click Threshold到一个舒适的值例如0.4秒。3. 修改插件的UISkin增加可点击区域的尺寸。搜索功能卡顿特别是在物体很多时Search Refresh Interval设置得太低导致每帧都在进行字符串匹配。显著提高Search Refresh Interval例如从0.25秒改为0.5秒或1秒。用户输入搜索词后不需要毫秒级响应。自定义绘制器中的输入框无法提交数据在自定义绘制器的输入框事件中直接修改了UI的Text而没有通过修改Value属性来触发绑定的Setter。确保所有用户输入最终都通过设置this.Value newValue;来更新。这是反射数据绑定的唯一入口。脚本重新编译后RuntimeInspector引用丢失或报空Unity在脚本重编译后会重新加载部分域可能导致事件委托丢失或静态引用重置。在OnEnable或Start方法中重新绑定所有必要的委托如ComponentFilter,GameObjectFilter并重新检查ExposedExtensionMethodsHolder的赋值。在WebGL平台出现功能异常或性能极差1. WebGL对反射的支持有差异和限制。2. 频繁的UI刷新和GC在WebGL的单线程环境下影响更明显。1. 避免使用过于复杂的反射操作优先使用CreateDrawer带Getter/Setter委托的方式而非完全依赖反射。2. 进一步降低所有刷新间隔并精简在Inspector中显示的变量数量。最后一个小技巧如果你发现Inspector在检视某些特定脚本时特别卡可以尝试在脚本中为那些不需要在运行时调试的字段添加[System.NonSerialized]属性。这样Unity的序列化系统会忽略它RuntimeInspector通常也不会显示它既能减少数据量也能避免不必要的反射开销。但这会阻止该字段在编辑器中序列化请根据情况使用。