ARTICLE · 1360695
冒烟测试一直通过,插件却已经十三天没加载
11 月 15 日凌晨跑了一次启动冒烟。日志第 3 行躺着一句告警:1 entry did not activate,意思是有个条目没被激活。紧跟着两行是 failed to import,和一句 SyntaxError。宿主那个模块不提供名为 settingsNamespace 的导出。
这几行不是那天才有的,从升级那天起就一直在。冒烟检查却一直打绿勾,因为它只看服务有没有起来、端口通不通,从来没看插件本身有没有加载。插件静默罢工十三天,我这边一切看起来都正常。
这篇把三件事说清:新宿主把这些接口换成了什么,要改哪三处,改完用什么办法证明它真的能用。
一、最贵的失败,是一句话都不留的那种
技术上的失败分两种。一种是吵的:编译不过、SyntaxError、启动直接退出。这种反而好办,它当场拦住你,不修就过不去。
另一种是静的:构建通过,启动不报错,日志干净,功能就是不生效。上面那句「1 entry did not activate」还只是最客气的一种,它至少留了一行字;更常见的是连这行字都没有,查什么都查不到。
这篇里最耗时的两个坑都是静默型。第一个,配置项少标一个标记,整块设置区被安静地跳过,没有任何告警。第二个,查询时机早了几秒,读回来的列表里少了自己那一条,看起来像根本没注册成功。
判据要落在「条目在不在派生出来的表单里」,不要落在「服务起没起来」。
二、旧写法在新宿主上为什么过不去
旧模型里,插件自己申请一块配置区。一句话讲:把包名字符串转成带品牌标记的命名空间对象,再注册进去,宿主回一个作用域对象,读写都走它。
宿主升到 0.2.1-rc.3 之后,这两个入口一起被收走了。
宿主那份模块只剩 4 个导出。插件自己的依赖目录里躺着的是旧版本,那一版有 8 个导出,被删掉的两个都还在。于是出现一个很容易误判的现象:插件目录里明明有这个函数,运行时却说找不到。
原因是模块解析走宿主那一份,插件自带的那份只在编译期起作用,运行时根本不会被加载。在自带副本上改代码,改一百遍也不影响运行时。
三、新模型的四条规则
新模型把方向反过来:配置区不再由插件申请,而是由加载器按条目自动派生,命名依据就是条目 id。
1、条目 id 就是命名空间。补丁里写的是 id: custom-css,命名空间字符串就是 custom-css。写成包名对不上,这一条不改,后面全白忙。
2、配置结构由插件导出的 Config 决定。宿主读它,要求是个带 toJSON 的 schema 对象,据此生成设置页的表单。
3、字段要标 volatile() 才会出现在表单里。宿主那个生成表单的函数,遇到没有这个标记的 schema 就返回 undefined。这个条目于是在整个列表里被安静跳过。没有报错,没有告警,就是查不到。
4、写操作带版本号。每条描述带一个 revision。写入时要把它原样传回去,对不上就抛 SETTINGS_CONFLICT。这是为了防止两个人同时改配置互相覆盖。
前三条决定插件能不能出现在设置页,第四条决定两个人同时改的时候会不会互相覆盖。缺任何一条,外面看到的样子都一样:查不到。

(图一:旧模型里插件自己注册命名空间;新模型由加载器从条目配置派生,插件能拿到的命名空间只能从查询结果里取回)
四、四个容易卡住的地方
坑一,配置要导出,字段还要标 volatile()。第一版只导出了结构定义,没加标记。构建通过,启动不报错,但查询返回的 21 个条目里没有自己。21 这个数字是重点:整棵树里只有 21 个条目有派生表单,自己的不在其中。翻编译产物确认导出没问题,真正的原因是生成表单那一步把没标记的条目过滤掉了。
坑二,插件锁的依赖版本比宿主老。补上标记之后,TypeScript 报「这个类型上不存在该属性」。查版本就清楚了:插件装的是 3.18.1,宿主带的是 3.18.5,这个方法后者才有。插件锁的依赖比宿主落后,宿主加了新接口,插件在自己的类型定义里看不见。换成宿主同版本再编译就好了。
坑三,在初始化回调里查自己,永远查不到。查不到那次的输出是 entries=21 match=none。原因在过滤条件里:只有「已经加载完成」的条目才会被返回。初始化回调执行的那一刻,自己这条还在加载中,自然被滤掉。把查询挪到启动稳定之后,数字变成 22,多出来的那一条就是自己,版本号 0,值是配置里的两个默认值。21 变成 22 这个对比,是整件事里最好用的一次自证:条目存在、结构被认、默认值被填上,一次全看到了。
坑四,上下文会失效,服务引用要提前抓在手里。延迟查询一开始是失败的,报的是在非活动上下文里取不到服务。原来每次都通过那个上下文现取,启动流程走完之后它进入非活动状态,再取就抛异常。修法很简单:在回调里先把服务对象存进一个变量,后面全用这个变量。
附带一条同类发现:想绕开这套接口直接读条目列表,会被拒绝,提示没有声明依赖。框架的服务访问要预先声明,没声明就不给读。

(图二:三个观测点。初始化时查到 21 条没有自己,启动稳定后 22 条含自己,写入测试把版本推到 1、拒绝旧版本、再回到 2)
五、读得到,不等于写得进
读通了不代表能写。加了一段写入自测,只在环境变量打开时才跑,用真实宿主走完一个完整周期。先用版本 0 写进一段测试样式,回读版本变成 1;再故意拿已经过期的版本 0 写一次,宿主拒绝,错误码是冲突;收尾把值写回默认,版本推到 2。
三行输出对应三件事:写路径通了、并发保护还在、测试没留下垃圾。
落盘位置也变了。旧版写在配置文件的独立段里,新版直接写进 profile 补丁文件中这条目的 config 下面。插件不用管路径,宿主替它落盘,比旧模型省事。
判断有没有真接上,看两条:写入能不能推进版本号,旧版本会不会被拒。两条都过,才算真接上。
六、三条自查判据,和一条回滚命令
从便宜到贵,三条判据:
1、启动日志里有没有 failed to import、does not provide an export。有,就先查插件用了宿主哪个已删除的导出。
2、条目列表里有没有自己,条目数对不对。查不到就查两件事:配置有没有导出、字段有没有标 volatile。
3、写入能不能推进版本号、旧版本会不会被拒。
回滚很简单,也不影响数据:改前的源码还在 git 里,checkout 回来重新构建就回去了。代价是插件会重新变成「条目未激活」,冒烟多一条告警,其他功能不受影响。
还有一句现状要交代:线上那个正在跑的进程(11 月 14 日晚起)加载的还是旧代码。要等它下次重启,才会用上修好的版本。早上六点半不适合动它,重启留给合适的时间点。今天验过的是两件事:插件树重新装配一遍,条目正常激活;读写路径在真实宿主上跑一遍,三个断言全过。
觉得有用点个关注。想免费进星球的,公众号后台回复「星球」,我把链接回给你。微信上回消息的就是我,可能慢一点。















































































