跳转至

ISSUE-0111 · 数据库初始化失败完全静默

为什么现在做

「完整页面 Markdown 存储」需要建新表并把 src/utils/jsstore/base.ts:306 的 version: 5 bump 到 6。

🔴 version 是单向的:升到 6 之后,用户若退回旧版本构建, connection.initDb 抛 VersionError,整库读不出来(2 万+ 商家数据还在,但打不开)。

而失败处理是(src/entrypoints/background/index.ts:119):

.catch((err) => { console.error('❌ Background 数据库初始化失败:', err); });

⇒ setDbReady(true) 与 manageQueue() 都不执行 ⇒ 不采集、不入库、界面零提示。 用户看到的只是"扩展好像坏了",没有任何线索指向"版本回退"。

Tony 手动 unpacked 加载(明确不上架),从 backup/ 拿旧版回退正是本项目 SOP 的标准回滚路径 —— 这个坑的暴露面比商店渠道大得多。

⇒ 先把失败变可见,而这一版自己不动 schema。

修复

新建 src/utils/db-init-guard.ts:

  1. classifyDbInitError —— 三类:版本不兼容 / 超时 / 其它
  2. handleDbInitFailure —— badge ! + title(三类文案不同)+ appendSysLog(level: error)
  3. withDbInitTimeout —— 15 s 超时兜底

🔴 超时兜底不是锦上添花:indexedDB.open 在被其它标签页 block 时 promise 永不 settle(没有 onblocked)—— 只判 err.name 救不了这一格, 它根本走不到 catch。

用户实际看到什么

分支 title
版本不兼容 「数据库版本不兼容,已暂停采集。你的商家数据还在,没有丢失 —— 当前扩展版本比数据库版本旧(常见于从 backup/ 手动回退到旧版本构建)。请升级到最新版本重新打开,不要继续使用这个旧版本」
超时 「数据库初始化超时(15s)……可能是有其它标签页/窗口占用了数据库连接」
其它 「数据库初始化失败……错误信息:{原始 message}」

分类判据的取舍(复核实测)

VERSION_KEYWORD = /version/i 直接扫 message,会把这些误判成"版本不兼容":

TypeError: Cannot read properties of undefined (reading 'version')   ← 纯编码 bug
Unsupported manifest version 2 in worker bundle

但收紧正则的代价更大:jsstore 的 worker 错误跨线程序列化后 name 会丢, { message: 'The requested version (5) is less than the existing version (6).' } 这种无 name 的形态只有靠 message 正则才命中 —— 那恰是本版要保护的核心场景。

⇒ 宽 > 严。缓解:靠 message 命中(而非 err.name)时, title 里追加 (原始报错:…),让人看出「这不像版本问题」,不至于白折腾一轮升降级。

复核留的三条,已全部补上

  1. withDbInitTimeout 不 clearTimeout —— 浏览器没有 unref, 成功路径留下的定时器会把 MV3 SW 的空闲回收推迟最多 15 s(复核实测 PENDING_TIMERS_AFTER_SUCCESS=1)。 已加 finally { clearTimeout }。
  2. run() 同步 throw 留孤儿定时器 —— timeoutPromise 先建好而 race 从未执行, 那个 promise 没有 handler ⇒ 15 s 后冒一次 unhandledRejection(复核实测 UNHANDLED_COUNT=1)。 已改成先执行 run()、同步异常直接 Promise.reject。
  3. auth-provider.tsx:178 的裸 initJsStore() —— 改动前就是未处理 rejection; 超时兜底让「被 block 永久挂起」变成 15 s 后一次 rejection。已补 .catch(handleDbInitFailure)。

验证

  • tests/db-init-guard.test.ts 26 例(20 实施 + 6 收尾)
  • 全量 npx vitest run 691 passed · pnpm verify exit 0
  • 🔴 git diff -U0 src/utils/jsstore/base.ts | grep -i 'version:' 空 —— 逐行确认 schema 未动
  • 复核做了 4 次 mutation(还原裸 initDb / 删 VersionError 分支 / handleDbInitFailure 换 no-op / badge 文字改空),全部咬住

证据边界

逻辑层已验证充分,UI 呈现不需要验(主控订正:本文初稿写「需装载 unpacked 后肉眼确认」, 那是把 Chrome 的标准 API 行为当成了本项目的待验项):

项 状态
错误分类 26 例覆盖,含真实 Chrome 抛的两种形态 —— 带 name: 'VersionError' 的、以及跨 worker 序列化后丢了 name 只剩 message 的
超时兜底 fake timer 实测,含「超时后原 promise 再 settle 不二次触发」「同步 throw 不留孤儿定时器」
badge / tooltip 呈现 setBadgeText({text:'!'}) 是 Chrome 标准行为,不是本项目逻辑,无可验之处

真正没验的只有一条:真实 onblocked 场景下 15 s 够不够。 这需要制造「两个标签页同时持有不同版本的 DB 连接」,而它恰恰是低频且自愈的场景 (关掉多余标签页即可)。DB_INIT_TIMEOUT_MS 是可调常量,真出现误报再调。

⇒ 不需要 Tony 手动 build 加载去测。 这套提示平时看不到才是正常的 —— 它只在数据库打不开时出现,而那一刻它自己会说明原因。

DB_INIT_TIMEOUT_MS = 15000 是工程判断不是精确论证:正常路径几十毫秒内 settle, MV3 SW 单次事件预算 30 s 量级,15 s 留一半余量给善后。实测发现误报/漏报优先调这个常量。