EPUB 文件必须严格遵循规范：需 content.opf 描述元数据与资源、nav.xhtml 提供目录、主 HTML 为合法 XHTML；图片路径须相对，资源须在 ZIP 内并声明于 manifest；pandoc 转换须指定 --epub-version=3、--toc 等参数；Calibre 导入需手动补全元数据与 nav.xhtml；手工 ZIP 必须首行为 application/epub+zip 且含正确 container.xml。
HTML 文件结构必须符合 EPUB 内容文档规范
EPUB 不是把任意 HTML 压缩打包就能读，它要求 content.opf 描述元数据和文件关系，toc.ncx 或 nav.xhtml 提供目录，且主 HTML 必须用 XHTML 语法（闭合标签、小写、引号包裹属性）。常见错误是直接丢一个 index.html 进去，结果 Calibre 打开报错 OPF parse error 或阅读器提示“无法加载内容”。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 用
xmllint --valid --noout yourfile.html检查是否为合法 XHTML；不通过就补全</p>、<br />、<img src="..." alt="" /> - 避免内联
style和script：EPUB 3 允许，但多数阅读器（如 Kindle）会忽略或报安全警告；优先用外部stylesheet.css - 图片路径必须相对且可解析：不要用
file:///或绝对路径，所有资源（CSS、图片、字体）需放在同一 ZIP 包内，并在content.opf的<manifest>中逐条声明
用 pandoc 一键生成 EPUB 最省事，但得调对参数
pandoc 是目前最稳的 HTML → EPUB 转换工具，但它默认输出的是 EPUB 2，而新版阅读器（尤其是 Apple Books、Kobo）更认 EPUB 3。不加参数容易导出后目录不显示、中文乱码、封面不生效。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 基础命令必须带
--epub-version=3和--toc：pandoc input.html -o output.epub --epub-version=3 --toc --toc-depth=2 - 指定封面要用
--epub-cover-image=cover.jpg，且cover.jpg必须是 JPEG/PNG，尺寸建议 1200×1600 像素，否则某些阅读器裁切异常 - 中文字体要显式嵌入：加
--epub-embed-font=fonts/NotoSansCJKsc-Regular.otf，否则 iOS 上显示方块 - 如果 HTML 含 MathML 或 SVG，加
--mathml或--standalone，否则公式渲染失败
Calibre GUI 导入 HTML 后，封面/目录/元数据经常丢失
Calibre 界面操作看似简单，但点击“添加书籍”后直接拖 HTML 文件进去，它会自动生成 OPF，但常漏掉 nav.xhtml、封面绑定错误、作者字段为空——导致 Kobo 显示“未知作者”，Apple Books 不生成侧边目录。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 导入前先右键 HTML 文件 → “编辑元数据单独”：填好
Title、Author、Language（设为zh-CN），再拖入库 - 导入后双击书籍 → “编辑电子书” → 左侧文件列表检查是否存在
nav.xhtml；没有就点“工具”→“生成目录”，选“基于标题”并勾选“插入到文件开头” - 封面必须是独立图片文件（非 HTML 里的
<img>），且在“元数据”页点击“从文件设置封面”按钮重新指定 - 导出前务必点“首选项”→“通用”→勾选“EPUB 输出”下的
Write EPUB3和Embed fonts
手动生成 ZIP 包时，MIME 类型和容器结构不能错
EPUB 本质是 ZIP，但不是普通 ZIP：第一行必须是纯文本 application/epub+zip（无空格无换行），且该行必须是 ZIP 文件的首 30 字节内；同时根目录下必须有 META-INF/container.xml 指向 OPF 文件。手工压缩时用系统自带 ZIP 工具，99% 会破坏这个结构。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 用
zip命令行强制写 MIME：printf 'application/epub+zip' > mimetype && zip -0Xq book.epub mimetype - 再追加其他文件时，禁用压缩（
-0）、禁用 UTF-8（-X）、跳过目录（-r要慎用）：zip -0Xq book.epub META-INF/ OEBPS/ - 验证结构是否合规：
unzip -l book.epub | head -10看第一行是不是mimetype，且位置在最顶；再unzip -p book.epub META-INF/container.xml确认full-path指向正确的 OPF
真正卡住人的地方，往往不是转换本身，而是 EPUB 规范里那些“看不见的契约”：比如 container.xml 里路径必须用正斜杠、OPF 中 id 值不能重复、nav.xhtml 的 ol 必须严格嵌套。这些细节一错，阅读器就静默失败，连错误提示都不给。
