跳转至

ISSUE-0213 组合库初始化挡在 React 渲染前面

现象(Tony 实测 v0.16.29)

商家列表一直转圈、计数显示 0(左侧导航却有 87,563);关掉主面板再打开也打不开。 chrome://extensions 错误页连报两条 Uncaught (in promise) Error: Could not establish connection. Receiving end does not exist.

根因:模块顶层的副作用排在了渲染前面

src/utils/jsstore/combo-db.ts 的模块顶层有立即执行的副作用:

export const comboConnection = new Connection();
comboConnection.addPlugin(workerInjector);   // 建 Web Worker

而 v0.16.29(SPEC-027 第二刀)为了「接线必须发生在任何读端调用之前」, 把它静态 import 到了 createRoot().render() 前面:

import { getTaskRollup } from '@/utils/jsstore/combo-db';  // ← 组合库在这里被拉起
setTaskRollupReader(getTaskRollup);
ReactDOM.createRoot(...).render(...)                        // ← 渲染排在它后面

⇒ 组合库初始化一慢/一抛,整个主面板打不开。

🔴 这是同一个坑的第二次

main.tsx 的第 1 行注释讲的就是 ISSUE-0052「ext-context-guard import-time init」:

必须第一行 import —— listener 在 import 时立即装

那条注释教会了「有些东西要提前」,却没写「什么东西不能提前」。 于是下一个人(SPEC-027 第二刀)把一个会建 Worker、会开 IndexedDB 连接的模块 也提到了前面,理由同样充分(「接线要早于读端」)。

⇒ 「import 时机」这件事上,本仓只记了正例,没记反例。

🔴🔴 根因订正(v0.16.32 双路对抗审抓到,主控写错了)

上面写的「建 Web Worker」是错的 —— 那是主控未经验证的推测。

本仓 combo-db.ts:14-21 的注释白纸黑字写着(而且标了「实查」):

「多一个 Connection = 多一个 Worker」这条在本项目不成立: jsstore/dist/worker_injector 的实现是 setup(r){ r.$worker = require('...worker.commonjs2.min.js') } —— 它把 worker 代码内联成普通模块,不起真 Worker。 否则 MV3 service worker 里根本跑不起来(MV3 SW 不支持 new Worker())。

⇒ comboConnection.addPlugin(workerInjector) 不创建 Web Worker。 主控在本文与 commit message 里写的「建 Web Worker」是推测被写成了事实, 而本仓铁律之一正是「不把未验证或不存在的产出写成事实」。

那真正的机制是什么

UNVERIFIABLE。 两路独立审查(terra-dsh / dshf)都判不了: - 排除了循环 import(task-store 只 type-import task-rollup,combo-db 的依赖均不 import task-store) - addPlugin 不起真 Worker - 但症状是真的(Tony 实测:v0.16.29 主面板打不开,v0.16.31 恢复正常)

⇒ 修法有效、根因未明。 这一条必须如实记着,不许拿一个听起来合理的解释填上去 (本仓 collab-core 对写机理有明确要求:「往文档里写机理,先跑一次证给自己看; 证不了就只写观察到的现象,别补一个听起来合理的原因」——主控这次正是违反了它)。

🔴 同形态没修全(两路一致指出,P0)

src/utils/jsstore/base.ts:7-8 有完全相同的形态:

export const connection = new Connection();
connection.addPlugin(workerInjector);
而它经 main.tsx:8 → App.tsx:3 → auth/context/index.ts:3 → auth-provider.tsx:9 静态进入 render 前的依赖图;background 也在注册 onMessage 前静态导入它。

⇒ 主控只修了 combo-db 这一条路径,主库那条一模一样的路径没动。 「自己动手止血」在这一刀确实造成了质量下降:漏了同形态,还写错了根因。

另一处低估

commit 说「首拍可能显示一次未知态」。实际(dshf 核): task-view 的 rollup 轮询是 5000ms,而接线落地不会通知 React ⇒ 「—」会持续到下一次轮询,最长 5 秒,不是「一闪」。

修法(v0.16.31)

渲染优先。接线延后到 render() 之后、改为动态 import,失败只降级不致命:

ReactDOM.createRoot(...).render(...)

void import('@/utils/jsstore/combo-db')
  .then(({ getTaskRollup }) => setTaskRollupReader(getTaskRollup))
  .catch((e) => console.warn('[main] TaskRollup 读端接线失败,采量将显示未知:', e));

代价:首拍可能显示一次「未知」——而那本来就是 SPEC-027 规则 ② 设计好的行为 (读不到就显示未知,绝不回落)。用户看得到界面,比第一拍少等 5 秒重要得多。

判据

tests/task-ingested-ui-wiring.test.tsx 是真实入口模块的行为级判据,本次适配为 「等接线落地再断言」——等待不削弱判据:接线永远不来的话 waitFor 会超时红。 变异自证:打掉接线 ⇒ 红;还原 ⇒ 绿(逐字节 diff 确认)。

🔴 未做:缺一条「渲染优先」的判据

现在的测试只验「接线最终会发生」,没有验「render 发生在接线之前」。 也就是说:如果有人再把它挪回 render 前面,测试照样绿。

⇒ 真正防复发的判据应该断言两者的先后(例如 mock createRoot 记录调用时刻)。 未做,这是本 issue 最重要的遗留。

教训

「这个 import 必须早」和「这个 import 会做什么」是两件独立的事,而注释里只写了前者。

判断一个模块能不能提前 import,要看它的顶层有没有副作用,而不是看接线需求有多急。 combo-db 的顶层建 Worker + 开 IDB 连接 —— 它永远不该排在首屏渲染前面。

⇒ 给「模块顶层副作用」这个形态建扫描判据(本轮 scan:import-browser 已覆盖 browser.* API,但没覆盖 new Connection() / addPlugin 这类)。