null | 郑俊耀

type

Post

status

Published

date

Sep 27, 2026

slug

summary

插件面板白屏，根因是客户端从宿主解构了已被移除的图标导出

一、现象：四盏绿灯都亮着，只有内容区是白的

某次宿主升级之后，我打开 Web GUI，一个第三方插件的面板坏了：入口在、外壳在——头部、搜索框、标签页都正常——唯独内容区一片空白。不是「加载中」，是渲染走到那一层直接炸掉，只剩控制台里一条 React 错误：

React 官方对这个编号的解释是 Element type is invalid：你交给 React 的「组件」不是一个能渲染的东西，而是 undefined。

真正把我带偏的，是这件事的另一半——这个插件的后端全绿：各类状态与能力查询接口全部正常返回；状态里没有忙碌标记、包管理器可用、护栏组件可用；客户端资源也正常加载、体积正常，而且已经登记进了启动清单；宿主这一次启动，零未激活、零报错。

插件启动了、路由通了、资源加载了、清单里也有它。四盏绿灯同时亮着，屏幕却是白的。

二、为什么「从后端查起」是错的

我的第一反应是查后端。这是写插件养成的肌肉记忆：面板出问题，先看路由。

我确实查了几轮，也排掉了一个很像的候选——那个面板的安装、更新、卸载这几类操作带一层护栏，只要有 agent 会话在跑就一律拒绝，并把拒绝原因写进日志。而那份日志停在更早的日期、没有新记录，说明用户的操作从未到达后端。据此排除「被护栏拦住」。我又列了别的候选：请求体为空？资源没进清单？包管理器不可用？每一条都被上面那四盏绿灯否掉。

这才是问题所在：我用来排除候选项的判据，全都只覆盖后端。 后端一无所知的那个方向，我根本没建立观测——而屏幕是白的，恰恰是那个方向的事。

绕了一圈才想明白：DSH 的插件兼容检查看的是依赖声明和「包在不在」，它不知道客户端的 React 组件在运行时能不能解构出来。客户端那一半是按符号解构宿主模块的——取一个对象，再按名字取它的属性。符号缺失不会在启动期报错，只在渲染那一刻炸成 Element type is invalid。所以「启动日志全绿」和「面板可用」本来就不相干。

三、定位：把前端真正用到的符号列出来，和宿主对一遍

正确的入口不是后端，而是插件客户端产物里那句 require。它的模块工厂第一件事就是把宿主包解构进一个局部变量——拿到变量名，就能引出它用到的全部符号：

思路只有两步：先从这个产物里抽出「它需要的符号清单」，再从已安装的宿主包里抽出「宿主提供的导出清单」，两个集合作差。中间的工程细节都不重要，唯一值得记的是一个实践上的坑：直接动态导入宿主包去枚举导出，会先撞上宿主包自己的依赖解析；静态读它的导出语句反而更省事。

故障当时那组差集很难看：需要解构的符号里，缺的全是图标。换成新版之后重跑，需要的符号少了一半以上，而且一个都不缺。

缺的又全是图标、又恰好是渲染路径上要当组件用的东西——这条差集就是决定性证据，根因不用再猜了。

四、根因：宿主裁剪了客户端导出，而插件停在旧版

根因是版本错配：宿主升级时裁剪了客户端 UI 包的图标导出集，而插件还停在为旧版构建的那个版本上。插件作者的客户端产物里硬编码了一批已经不存在的图标名，逐个解构成 undefined，再被塞进 JSX 当组件用，于是报 React error ＃130。

这不是运行时故障，是契约层面的错配：插件的后端一行没改、接口形状一行没改，变的只是「客户端从宿主拿哪些符号」，而这一层没有任何兼容闸门会拦住它。

修复本身很简单：把插件的客户端产物升到与当前宿主匹配的版本。重启验收时，后端指标一如既往地全绿——它们从头到尾都是绿的，证明不了修复是否生效。真正能证明的是另外几件事：清单里的版本引用变了、启动清单里这个插件的修订标识变了、符号差集重新变成空集。这几条对上了，面板才真正回来。

五、可迁移的判据

先看一眼「你的观测覆盖了哪个方向」。 当一个故障相关的所有观测都亮绿灯时，别继续在同一个方向找更多绿灯，而要反问一句：这个方向之外，我有没有装观测点。这次最贵的成本不是定位，是在无效方向上找证据的时间。

插件与宿主错配，第一入口是符号差集。 取客户端产物里 require("<宿主包>") 赋的那个变量名，抽出它访问过的全部属性，再与已安装宿主包的导出清单做差。不需要浏览器、不需要把插件跑起来，只要产物和宿主安装就位，一分钟出结论。

依赖声明不是兼容性判据。 声明只描述「包级」的依赖范围，而失败发生在「符号级」：作者很可能压根没更新声明。只看声明，会把坏掉的旧版判成合格、把修好的新版判成不兼容——两头都反。

启动日志干净、兼容检查通过，都不等于界面可用。 兼容闸门检查的是声明与存在性，客户端组件却是渲染时按符号取用的；缺符号在启动期完全静默。这两个结论必须分开建立。

验收要盯「变了什么」，不是「有没有报错」。 升级后该复核的是：清单里的修订标识是否更新、符号差集是否为空、需要解构的符号数是否收敛。启动日志在升级前后都是干净的，它证明不了任何事。

宿主升级后，复查所有本地插件的客户端半边。 宿主对客户端导出集没有稳定性承诺，这次只是图标；凡是在客户端依赖宿主 UI 包的插件，都可能被同一刀打到。

这次我花在「从后端查起」的时间，比定位本身多得多。教训很具体：当一个故障的所有观测都亮绿灯时，第一件该做的事不是继续在后端找更多绿灯，而是问一句——这个方向之外，我有没有装观测点。