EPUB

EPUB 解析读取 META-INF/container.xml、OPF package、spine、navigation/NCX 和 manifest。 章节 HTML 转为阅读器内容，资源引用解析到应用缓存中的本地文件。

目录来源优先级

目录不是只认一种来源，而是按“更结构化优先”的顺序尝试，任何一级解析失败或为空都会降级到 下一级，不会直接报错中止：

1. EPUB 3 nav 文档（manifest 里 properties="nav" 的条目）——优先，层级和标题最准确
2. EPUB 2 NCX（.ncx，manifest 里 nav 缺失或解析失败/为空时尝试）
3. Spine 顺序降级（前两者都不可用时，直接按阅读顺序把每个 spine 条目当一章）

第 3 级得到的目录只有阅读顺序、没有真正的章节标题层级，常见于制作粗糙或工具直接从 纯文本转出的 EPUB；这种情况下章节名通常就是文件名或“第 N 部分”，属于预期行为，不是 解析出错。

图片

图片必须保留相对资源关系。渲染层使用真正的图片 attachment 或本地 URL，不把 file:///.../EPUBImages/...png 当普通文字插入。应用容器路径变化时应重新解析资源，而不是 长期保存旧绝对路径。

排版

EPUB 原始 CSS 会被转换或限制，最终由用户阅读设置决定字体、字号、行距、颜色和边距。 标题、段落、强调和图片应保留语义；危险脚本和外部活动内容不执行。

性能

解析和图片提取在后台完成。分页缓存按内容和 typography 配置区分，切换字号或窗口尺寸会 触发去抖重排。

回归检查

• 目录顺序和章节数量；
• 封面、插图、SVG fallback；
• CJK/Latin 混排和首行缩进；
• 跨章节文本连续；
• 应用重启后图片仍显示；
• 超大 EPUB 不阻塞主线程；
• 同时验证一本 EPUB3（nav 目录）和一本纯 EPUB2（NCX 目录）来源的书，两条目录解析路径 不会因为只测过其中一种格式而被忽略。