企业官网建设流程全解析

• 桌面应用
• 跨平台
• 前端

导读

本文聚焦 Readest 阅读器一个隐蔽且破坏性极强的 bug：在包含脚注和插图的书籍中，连续 3 次以上点击/关闭脚注弹窗后，当前章节的插图会突然无法打开，直到关闭并重新打开阅读器才能恢复。其根源并不在 Readest 应用层，而在于底层引擎 foliate-js 的Loader.ref()引用计数机制——顶层章节加载共用了一个永不清理的#children桶，导致引用计数下溢、章节及其所有子资源（图片）的 blob URL 被提前撤销。本文基于仓库中的根因分析文档 footnote-popup-revokes-section-blobs.md，结合 foliate-js 与 Readest 的源码实现，完整还原问题现象、精确定位根因、梳理复现验证方法，并剖析修复方案（foliate#78/readest#5756）的严谨设计与内在约束。

一、问题现象：脚注点三次，插图就“死”了

1.1 用户视角的表现

用户报告（中文反馈）描述了一个非常反直觉的现象：阅读一本同时包含脚注和插图的小说时，对脚注内容反复点击（3 次以上），就会发现章节内的插图无法再打开——点击图片没有任何反应，必须关闭并重新打开阅读器才能恢复。页面文字本身显示正常，只有"打开图片"这个动作失效。

1.2 为什么"页面正常、图片打不开"

这个"一半正常一半坏"的观感是理解问题本质的关键：<img>元素一旦完成解码，即使其 blob URL 被URL.revokeObjectURL()撤销，已经绘制出来的图像依然停留在页面上（complete: true、naturalWidth: 1502等属性仍然存在）。只有发起新的 fetch时才会失败。

在 Readest 中，点击图片的完整链路是：

1. iframe 内的点击事件被 iframeEventHandlers.ts 捕获，reflowable 书籍中单击图片会window.postMessage({ type: 'iframe-open-media', bookKey, ...media }, '*')；
2. 应用层 useIframeEvents.ts 收到该消息后，由 FoliateViewer.tsx 调用convertBlobUrlToDataUrl(src)把 blob URL 转成 data URL 再展示图片查看器；
3. 若 blob URL 已被撤销，convertBlobUrlToDataUrl内部 fetch 抛出的就是TypeError: Failed to fetch，被catch捕获后仅输出console.error('Failed to load image:', error)，图片查看器永远不会打开。

所以"插图打不开"并不是图片丢失，而是承载图片的 blob URL 被提前销毁。

二、根因定位：Loader.ref()的 undefined-parent 共享桶

2.1 引用计数模型

foliate-js 的Loader类（packages/foliate-js/epub.js）负责加载并缓存 EPUB 资源，通过引用计数 + 父子依赖管理生命周期：

• #refCount：每个 href 的引用计数，归零时调用URL.revokeObjectURL撤销 blob URL；
• #children：以parent为键的 Map，记录某个父资源引用了哪些子资源——父资源卸载时会递归unref所有子资源（这正是插图跟着章节一起被撤销的机制）；
• #cache/#cacheXHTMLContent：blob URL 与 XHTML 内容缓存。

2.2 Bug 的三个关键机制

机制一：顶层加载共用#children.get(undefined)桶。顶层章节加载（视图打开一个章节）时parent为undefined，修复前的ref()会把所有顶层资源记入同一个#children.get(undefined)桶——而createURL在parent为 undefined 时不会把资源写入子桶，这造成两个函数对 undefined-parent 处理不一致：

• 首次加载走createURL：直接设置#refCount = 1，不进入子桶；
• 第二次引用走ref()：#children.get(undefined)桶里已经存在该 href，被!childList?.includes(href)守卫挡下，跳过自增——也就是说，第二次引用被当作"重复引用"而忽略。

机制二：unref只有减没有加，计数必然下溢。每次视图销毁都会调用unload()进而unref()减一，但没有任何代码会调用unref(undefined)去清理共享桶。于是顶层章节的引用计数持续减一，最终下溢到 0，触发URL.revokeObjectURL(url)，并递归撤销#children.get(href)下的所有子资源——即章节内的全部插图，而此时主视图仍在展示这些插图。

2.3 精确的测量周期

文档给出了脚注弹窗目标位于当前已展示章节时的完整引用计数周期（S 代表章节 XHTML，图片为子资源）：

• 打开#1：ref1→2（创建children[undefined]=[S]），关闭#1：2→1 —— 图片仍然存活；
• 打开#2：被跳过（桶里已有 S，ref不执行自增），关闭#2：1→0 ——撤销 S 及其所有子 blob；
• 之后每次关闭都会再次触发撤销（每次关闭释放 2 个 URL：章节 XHTML + 图片）。

也就是说，问题在第 2 次关闭弹窗时就已破坏，这与用户"点击 3 次以上"的体感完全吻合。

2.4 为什么第一次打开是好的

关键不对称性在于createURL：它只在parent存在时才写子桶，所以第一次打开脚注弹窗（弹窗会在同一本书上再开一个 view）时，ref正确地执行了 1→2 的自增；只有第二次打开才被共享桶的守卫误伤而跳过自增。这就是"第一次正常、第二次开始崩"的精确原因。

2.5 触发链

从代码路径看，整条破坏链为：

Paginator.destroy() → #destroyAllViews() → #destroyView(index) → sections[index].unload() → Loader.unref() → 计数归零 → URL.revokeObjectURL(章节blob) → 递归撤销 children 图片 blob

对应实现见 paginator.js：#destroyView在销毁视图后调用sections[index]?.unload?.()，#destroyAllViews则遍历所有视图执行销毁——脚注弹窗关闭、翻页离开等都会走到这条卸载路径。

三、修复方案：两个半边缺一不可

修复（foliate-jsc1f0c3c，Readesta193cbc3）的核心结论是：这个问题需要两个半边配合修复，只修第一半会引入资源泄漏。

3.1 半边一：ref()顶层引用必须始终自增

修复后的ref()（epub.js）在parent缺失（顶层章节加载）时无条件自增引用计数并直接返回缓存 URL，跳过 childList 去重逻辑：

ref(href, parent) { if (!parent) { this.#refCount.set(href, this.#refCount.get(href) + 1) return this.#cache.get(href) } const childList = this.#children.get(parent) if (!childList?.includes(href)) { this.#refCount.set(href, this.#refCount.get(href) + 1) if (childList) childList.push(href) else this.#children.set(parent, [href]) } return this.#cache.get(href) }

这样每次顶层视图（主视图、脚注弹窗视图）加载章节都会正确 +1，unload时再 -1，计数严格配对。

3.2 半边二：loadItemXHTMLContent不得再持有引用

仅修ref()会引入一个更隐蔽的问题：Paginator对每个视图会同时调用section.load()和section.loadContent()（paginator.js），但只对应一次unload()。修复前，那个有缺陷的共享桶恰好"吸收"了第二次调用（loadContent内部走loadItem→ 缓存命中 →ref被守卫挡下），所以引用计数能勉强平衡；修好ref()后，第二次调用会真的再 +1，导致每个打开过的章节永远无法释放——这就是文档警告"fixref()alone and every section the reader ever opened is retained forever"的原因。

因此修复同时要求loadItemXHTMLContent（epub.js）复用调用方已持有的引用，而不是再取一个永远不会被释放的引用：

async loadItemXHTMLContent(item, parents = []) { // Callers read the source of a section they have just loaded (the // renderer pairs `section.load()` with `section.loadContent()`), and // there is no matching unload for this call, so reuse the reference // they already hold rather than taking one that is never released. const url = this.#cache.get(item?.href) ?? await this.loadItem(item, parents) if (url) return this.#cacheXHTMLContent.get(url)?.data }

实现上优先从#cache直接取缓存（不经过ref()），只有缓存未命中时才降级调用loadItem加载。

3.3 调用方枚举：为什么这两个半边是完整的

文档强调，loadItem与loadItemXHTMLContent是仅有的两个顶层loadItem调用入口；而loadHref/replaceString等路径总是传入非空parents（走loadItem的常规父级分支）。因此修复覆盖了所有顶层加载场景，不存在遗漏的第三方调用方会导致计数失衡。

四、复现与验证方法

4.1 无需测试书籍的注入式复现

由于用户处于登录态、直接导入测试书会造成数据污染，文档给出了一个不写库的注入式验证配方：

1. 打开任意 EPUB，向当前章节文档注入<a epub:type="noteref" href="<ownFileName>#id">以及对应的锚点目标；
2. 用合成的MouseEvent在锚点上触发点击（Readest 的 iframe 事件处理见 iframeEventHandlers.ts）；
3. 通过应用自身的document.querySelector('.footnote-content foliate-view')找到脚注弹窗内容区（该容器定义于 FootnotePopup.tsx），调用其.close()与.remove()关闭弹窗；
4. 在两个开/关周期之间用fetch(imgUrl)探测图片 blob URL 是否仍然可用。

4.2 触发"图片打不开"的等价手段

除了鼠标点击，tap-to-open 行为还可以通过向应用 post 消息精确复现：

{ type: 'iframe-open-media', bookKey, elementType: 'image', src }

这正是 iframeEventHandlers.ts 在 reflowable 书籍中单击图片时真实发送的消息负载，对应测试用例见 iframeEventHandlers.test.ts。

4.3 验证环境与状态

该问题已于 2026-08-17 在 Chrome 中针对pnpm dev-web环境、foliate-js9fde61a1版本验证属实；修复以foliate#78（合并为c1f0c3c）与readest#5756（合并为a193cbc3）两个 PR 合入，设备端（桌面/移动真机）验证当时仍待进行——这意味着阅读器用户如需确认真机表现，可在发布包含该修复的版本后按上述步骤复测。

五、经验总结：从本 bug 可以带走什么

1. 引用计数的对称性比"去重"更重要：ref的跳过自增去重逻辑只适用于"父子依赖"场景，绝不能套用到"生命周期独立"的顶层加载；一旦unref无条件执行而ref有条件执行，计数必然漂移。
2. 共享桶是隐性全局状态：#children.get(undefined)这个"无名桶"没有任何清理入口，属于典型的隐性共享状态。父键缺失时，要么显式约定语义（顶层引用总是独立计数），要么拒绝写入子桶（createURL与ref必须保持一致）。
3. "缓存命中即复用"并不总安全：loadItemXHTMLContent直接复用#cache引用，本质是把"谁持有引用"的职责显式化——调用方section.load()+section.loadContent()配对一次unload()，因此只能取一次引用。
4. 修复 bug 时要枚举所有调用方：本案例中"只修ref()"会让计数失衡方向反转（从下溢泄漏变成永久泄漏），正是调用方枚举（loadHref/replaceString总是传非空 parents）保证了双半边修复的完备性。

六、相关上下文

本问题与 Readest 脚注弹窗的另外两个已知问题同源相关，可交叉参考仓库记忆文档：

• footnote-popup-selection-5646.md：脚注弹窗内选择/选区相关问题；
• loaddocument-xhtml-parsererror-5625.md：loadDocumentXHTML 解析错误问题。

这些记忆文档共同构成了 Readest 对 foliate-js 底层引擎 bug 的"现场档案"，对后续引擎升级回归测试有直接参考价值。

• 桌面应用
• 跨平台
• 前端