fix(site/v0.8.0): 站点版本同步 + 现场失败修复(file:// 打不开 OPFS 的可操作错误)

用户报告"站点演示失败了",实测复现并定位根因:

- 现象:直接双击 site/demo.html(file://)→ 点「🌲 Aria」→
  " 数据库初始化失败: Failed to open AriaEngine database "demo""(Memory 正常)。
- 根因:file:// 属不透明来源,Chromium 拒绝 navigator.storage.getDirectory()
  并抛 SecurityError;此时 isSecureContext 仍为 true、API 也存在,无法提前探测。
  引擎把它包成 ARIA_OPEN_ERROR 时丢掉了底层错误 → 消息对用户不可操作。
- 修复:OPFSBackend.open() 显式检查并抛 ARIA_OPFS_UNAVAILABLE,消息给出两条出路
  (用 http(s) 打开 / 改用 mode:'memory'),原始 SecurityError 挂 cause;
  site/demo.html 额外用中文说明"为什么失败 + 怎么修"。

顺带修掉一个更普遍的问题:DatabaseError 的第三个参数只进 details,err.cause
恒为 undefined,而文档/注释多处写"底层错误作为 cause 保留"。现在两者都成立
(details 语义不变;cause 声明为公开字段并接入标准错误链)。

站点版本同步:demo.html(title / 状态栏 / SQL 预置脚本 / console 日志)与
benchmark.html(title)此前仍是 v0.7.4(日志甚至是 v0.4.2)→ 统一 v0.8.0;
docs.html 的 AriaEngine 版本演进列表补上 v0.8.0 条目、错误码表补
ARIA_OPFS_UNAVAILABLE;README 补"OPFS 需要 http(s) 页面"的浏览器兼容说明。

回归与门禁:tests/engine/aria-opfs-unavailable.test.ts(5 项,含正常环境正控);
变异 R19 / R20 均被拦住(总计 42/42);93 套件 / 1985 用例;覆盖率
90.59 / 82.61 / 94.14 / 93.50(阈值 90/82/94/93);e2e 14/14;lint + 两份 tsc 干净;
dist 重建(251,731 B / gzip 63,431 B)并已同步全部体积宣称。
This commit is contained in:
thzxx
2026-09-15 17:09:29 +08:00
parent 0b44620721
commit c1c3036abd
25 changed files with 439 additions and 55 deletions
+25
View File
@@ -415,6 +415,31 @@ MUTATIONS = [
new=""" void missing; // [MUTATION] 不上报空洞""",
test=WALSEG, pattern='内部空洞',
),
dict(
name='R20 DatabaseError 不再暴露标准 cause(根因丢失)',
file='src/constants.ts',
old=""" if (details !== undefined) {
(this as { cause?: unknown }).cause = details;
}""",
new=""" void details; // [MUTATION] 修复前:只有 details,没有 cause""",
test='tests/engine/aria-opfs-unavailable.test.ts', pattern='DatabaseError',
),
dict(
name='R19 OPFS 不可用时吞掉原因(错误不可操作)',
file='src/engine/aria/store/opfs_backend.ts',
old=""" throw new DatabaseError(
`OPFS is not accessible here (${(error as Error).name}: ${(error as Error).message}). ` +
'Chromium blocks OPFS for file:// pages — serve the page over http(s) ' +
"(e.g. `npx serve .` / `node tests/e2e/server.cjs`) or use mode: 'memory'.",
'ARIA_OPFS_UNAVAILABLE',
error,
);""",
new=""" throw new DatabaseError(
'Failed to open OPFS backend',
'ARIA_OPFS_UNAVAILABLE',
); // [MUTATION] 丢掉原始 cause 与建议""",
test='tests/engine/aria-opfs-unavailable.test.ts', pattern='OPFSBackend',
),
dict(
name='R17 bloom 位数被忽略(bloomFilterBitsPerKey 配置无效)',
file='src/engine/aria/index/sstable_builder.ts',