EPUB转换踩坑记：章节顺序不能靠猜，spine才是唯一真相

开发一个EPUB转Markdown的工具，直觉上应该是一条干净的流水线：解压、解析、遍历文件、输出Markdown。但一位开发者的亲身经历告诉我们，事情远没有这么简单。他最初按照字母顺序遍历manifest，结果输出的章节顺序变成了Chapter 1、Chapter 10、Chapter 2、Chapter 3……读者甚至以为他在故意恶搞。

EPUB不是简单的ZIP：manifest与spine的区别

EPUB本质上是一个ZIP包，里面是一堆XHTML文件外加一个名为content.opf的控制文件。manifest按ID列出所有条目，而spine则按阅读顺序列出这些ID。关键问题在于：字母顺序、manifest顺序甚至ID命名，都不保证与人类实际阅读顺序一致。作者见过ch1.xhtml、chapter_01.xhtml、part1.xhtml、intro.xhtml等各种命名混在一起的情况。

修复方法简单得令人尴尬：解析spine，对每个itemref，将其ID解析到manifest中的条目，然后读取对应文件。如果spine条目指向非XHTML资源，就优雅地跳过。就这么简单。

OPF（Open Packaging Format） 是EPUB规范中的核心元数据文件，通常命名为content.opf，本质上是一个XML文档。它由几个关键部分组成：metadata定义书籍的标题、作者、语言等；manifest列出包内所有资源（XHTML、图片、CSS等），每个条目有唯一的id和对应的href；spine则通过itemref元素引用manifest中的id，并按照线性阅读顺序排列，同时可指定linear="no"表示该资源不属于主线阅读流（如脚注弹窗）。此外，guide元素可提供关键结构位置的引用（如封面、目录）。理解OPF的结构是正确解析EPUB的基础，因为阅读顺序、资源定位都依赖它。

目录文件不等于结构，spine才是权威

读书时感受到的“目录”来自第二个文件（toc.ncx或EPUB3的nav文档），它可能与spine不一致。作者最终放弃了自作聪明的做法，老老实实跟随spine。这个教训具有普适性：文件列表不是阅读顺序，目录也不是结构。 要找到表达意图的清单并遵循它。

toc.ncx 是EPUB2中定义的导航控制文件（NCX代表Navigation Control File for XML），采用XML格式，包含navMap、navPoint等元素，用于构建层级目录。EPUB3则引入了基于HTML5的导航文档（通常命名为nav.xhtml），使用<nav epub:type="toc">元素定义目录结构，更符合Web标准。两者在语义上相似，但格式差异较大。需要注意的是，这些导航文件的主要目的是为阅读系统提供目录界面，其内容可能与spine顺序不完全一致，例如包含非阅读顺序的参考页面或外部链接。因此解析时不能将目录文件等同于书籍的线性结构。

线性提取会毁掉非线性书籍

第二个教训是：线性文本提取会破坏非线性书籍。脚注、侧边栏和引文框是独立的XHTML文件，在正文中被内联引用。初版输出静默丢弃了它们。现在作者将脚注内容内联到引用点，用> [^n]:前缀标记，使Markdown在LLM上下文中保持自包含。侧边栏转为块引用。不完美，但诚实。

非线性内容在EPUB中通常通过linear="no"属性在spine中标记，表示这些资源不属于主线阅读流，但可能通过超链接在正文中被引用。常见的非线性内容包括脚注、尾注、侧边栏、引文框、术语表等。这些内容往往以独立的XHTML文件存在，如果简单地按spine顺序提取文本，就会遗漏它们或将其错误地插入到不相关的位置。正确的处理方式是在解析正文时，识别指向这些资源的链接（如<a href="footnote.xhtml#fn1">），并将目标内容内联到引用点附近，同时保持Markdown的可读性和自包含性。

兼容EPUB2与EPUB3：适配层值得投入

EPUB2和EPUB3使用不同的导航文件。同时支持两者意味着两个解析器加一个适配层（shim）。作者认为这个适配层是值得的——他收到的“损坏”报告中有一半是带有.ncx但没有nav文档的EPUB2书籍。

适配层（shim） 在软件工程中指的是一小段代码，用于在不同接口或数据格式之间进行转换，使上层逻辑无需关心底层差异。在EPUB解析中，适配层的作用是统一EPUB2和EPUB3的导航数据访问方式：对于EPUB2，解析toc.ncx提取目录结构；对于EPUB3，解析nav.xhtml中的<nav>元素；然后转换为统一的内部表示（如章节列表）。这样，核心的提取和转换逻辑可以复用，只需在入口处根据EPUB版本选择对应的解析器。适配层虽然增加了少量代码，但显著提升了工具的兼容性和健壮性，尤其对于混合版本的EPUB文件（如同时包含NCX和nav的EPUB3）也能优雅处理。

输出结构化Markdown，服务RAG管道

最终结果向RAG管道提供干净的、按章节结构组织的Markdown：# Chapter 3: The Thing That Happened作为标题，正文在下方，脚注内联。Agent引用“chapter 3”时，指的就是第3章。

作者将整个工具打包成单次调用API，接受URL或base64字节，返回保留章节结构的Markdown。

启示：找到控制文件中的意图

如果你在构建任何涉及EPUB、内部包文档或任何“电子书格式”的东西，这个教训可以推广：文件列表不是阅读顺序，目录不是结构。 找到表达意图的清单并遵循它。

作者最后抛出一个问题：在你以为已经理解的格式中，遇到过最诡异的“显而易见的东西藏在控制文件里”的bug是什么？