用 pandoc 批量转 HTML5 为 EPUB 最稳,因其正确解析语义标签、自动生成 NCX/OPF、保留 CSS,并需注意编码、标题层级、资源路径、Kindle 兼容性及 epubcheck 验证。

用 pandoc 批量转 HTML5 为 EPUB 最稳
直接用 pandoc 是目前最可靠、兼容性最好、且真正支持批量处理的方式。它能正确解析 HTML5 语义标签(如 、、),自动生成 EPUB 的 NCX 和 OPF 结构,还能保留 CSS 样式(需额外指定)。
常见错误是直接用浏览器“另存为”或拖拽进 Calibre —— 这些方式常丢章节结构、乱码中文标题、忽略 等元信息。
- 确保 HTML 文件有清晰的层级:用
做书名,做章标题,做节标题(pandoc靠这个生成目录) - 运行命令前先统一编码为 UTF-8(无 BOM),否则 EPUB 在 iOS 上可能显示乱码
- 批量转换示例:
for f in *.html; do pandoc "$f" -o "${f%.html}.epub" --metadata title="$(grep -oP '\K[^<]+' "$f")" --toc --toc-depth=2; done
HTML5 中的 和 必须手动映射到 EPUB 章节
EPUB 3 规范不直接识别 HTML5 语义块;pandoc 默认只按标题()切分章节,–
或 即使带 id 也不会自动变成独立 EPUB spine 条目。
如果你的网页靠 组织内容,就得在转换时显式告诉 pandoc:
立即学习“前端免费学习笔记(深入)”;
- 加
--top-level-division=section强制把每个当作一章(前提是它们都含) - 或用
--epub-chapter-level=2指定从开始算章节(比默认的更细) - 若想保留
的语义,建议提前用脚本把每个包裹成独立 HTML 文件,再批量转
图片路径和相对链接在 EPUB 里极易失效
HTML5 页面中写的 或 
,在 EPUB 容器内会找不到资源——因为 EPUB 是 ZIP 包,资源必须按 OCF 规范放在特定子目录,且路径要重写。
-
pandoc默认会把同目录图片自动打包进 EPUB,但深层路径(如../assets/)会被忽略,需加--resource-path=.或明确列出:--extract-media=. - 跨 HTML 文件的链接(如从
chapter1.html链到glossary.html)不会自动转成 EPUB 内部引用,必须先合并或用--self-contained(但会导致体积暴增) - 推荐做法:所有资源(CSS、图片、字体)集中放在
resources/下,用pandoc -r html -w epub --resource-path=resources/
中文 EPUB 在 Kindle 设备上显示异常的三个硬坑
不是编码问题,就是字体和 CSS 渲染逻辑冲突。Kindle 对 EPUB3 支持有限,尤其对 @font-face、Flexbox 和 CSS 变量几乎无视。
- 务必禁用自定义中文字体:删掉 CSS 中所有
@font-face声明,改用font-family: "SimSun", "Noto Serif CJK SC", serif;(Kindle 系统自带) - 避免用
rem或vh/vw做字号/间距,全部换为em或绝对单位(pt),例如:body { font-size: 12pt; } - Kindle 不支持
text-align: justify的两端对齐效果,会强制左对齐,若坚持要用,得预渲染成图片(不推荐)
导出后务必用 epubcheck 验证:epubcheck book.epub,报 WARNING 级别的 OPF-019(metadata 缺失)或 NAV-001(导航文件无效)必须修复,否则部分阅读器打不开。










