从零创建Epub遇阻：Calibre无法完整编译儿童互动绘本

我正在制作一款类似「Choose Your Own Adventure」的带页面链接互动儿童插画书，已创建名为「Book Title」的文件夹，目录结构如下：

folder/
    META-INF/
        container.xml
    mimetype
    OEBPS/
        content.opf
        images
        text
        music
        css

尝试用Calibre的「添加书籍」功能将内容打包为EPUB，但Calibre仅识别到image47和Page 47.html，无法正常编译，已确认所有HTML文件本身无错误。

我的content.opf代码如下：

<?xml version="1.0" encoding="UTF-8"?>
<package version="3.0" unique-identifier="bookid" xmlns="http://www.idpf.org/2007/opf">
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:title>The Rainbow Stone</dc:title>
    <dc:creator>My Name</dc:creator>
    <dc:publisher>Constellation Publishing</dc:publisher>
    <dc:language>en-US</dc:language>
    <dc:description>A magical story about a rainbow stone</dc:description>
    <dc:identifier id="bookid">urn:uuid:550e8400-e29b-41d4-a716-446655440000</dc:identifier>
  </metadata>
  <manifest>
    <item id="css1" href="Making Smaller Images.css" media-type="text/css"/>
    <item id="css2" href="Size for Images.css" media-type="text/css"/>
    <item id="audio1" href="Rainbow Stone Music.mp3" media-type="audio/mpeg"/>
    <item id="cover" href="Page 1.html" media-type="application/xhtml+xml"/>
    <item id="page2" href="Page 2.html" media-type="application/xhtml+xml"/>
    <!-- add more pages here -->(these went up to page 66)
    <item id="image1" href="image1.jpg" media-type="image/jpeg"/>
    <item id="image2" href="image2.jpg" media-type="image/jpeg"/>
    <!-- add more images here -->(these went up to image 66)
  </manifest>
  <spine>
    <itemref idref="cover"/>
    <itemref idref="page1"/>
    <itemref idref="page2"/>
    <!-- add more pages here -->(these went up to page 66)
  </spine>
</package>

META-INF/container.xml代码如下：

<?xml version="1.0" encoding="UTF-8"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
  <rootfiles>
    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
  </rootfiles>
</container>

排查与解决建议 #

• 修正资源路径匹配：content.opf中所有资源的href路径必须和实际文件夹结构对应。比如HTML文件在OEBPS/text/下，所以Page 1.html的路径应该写成text/Page 1.html；图片在images/下，要写成images/image1.jpg；CSS在css/下，写成css/Making Smaller Images.css；音频在music/下，写成music/Rainbow Stone Music.mp3。路径不匹配是Calibre找不到大部分文件的核心原因。
• 修复spine中的无效ID：spine里引用了idref="page1"，但manifest中没有id为page1的条目，要么在manifest中添加对应页面的item，要么把spine中的page1改为已存在的ID（比如cover）。
• 清理XML注释错误：manifest和spine中的(these went up to page 66)不属于标准XML注释格式，会破坏文件结构，应该把这类内容移到<!-- -->内部，比如改成<!-- 后续页面已添加至page66 -->。
• 手动打包验证结构：跳过Calibre，手动用zip工具打包测试：
  1. 确保mimetype是zip包的第一个文件，且不能被压缩（部分zip工具需手动设置不压缩该文件）
  2. 依次添加META-INF和OEBPS文件夹到zip包中
  3. 将zip后缀改为epub，用EPUB验证工具（如Sigil内置验证）检查结构是否合规
• 换用Sigil工具构建：Sigil是专门的EPUB编辑工具，导入你的文件夹后会自动检测路径错误、XML语法问题，还能可视化管理互动链接，比Calibre更适合手动构建复杂EPUB。
• 优化文件名格式：虽然EPUB支持带空格的文件名，但部分解析工具可能出现兼容问题，建议将文件名改为无空格格式，比如Page_1.html、Making_Smaller_Images.css，避免空格导致的路径识别异常。

内容的提问来源于stack exchange，提问作者finks213