EPUB Book Generator

EPUB Book Generator 是一款强大的工具（以 Claude Code Skill 形式提供），旨在帮助创作者、开发者和研究者将散落的 Markdown 文章、技术笔记或博客内容，快速打包成格式精美、兼容性极佳的 EPUB 电子书。

它解决了手动转换格式繁琐、图片丢失、代码块渲染错位等痛点，自动处理远程图片下载、SVG 转 PNG、封面生成等复杂任务，生成的电子书完美兼容 微信读书、Apple Books 和 **Calibre。

核心价值

• 一键转换：只需指定 Markdown 文件夹，即可生成完整的 EPUB 文件。
• 智能媒体处理：
  • 自动下载远程图片：支持 http/https URL，自动嵌入本地。
  • SVG 转 PNG：利用 Playwright 完美渲染网页中的 SVG 图表和公式，转为高清 PNG。
  • 智能压缩：自动将 PNG 转换为 JPEG 并压缩，平衡画质与文件大小。
• 完美代码渲染：完整保留代码块、表格、列表的格式，修复特殊字符导致的渲染错误。
• 专业封面生成：
  • 支持自定义图片封面。
  • 支持自动生成 SVG/HTML 封面，提供 Tech, Business, Design 等 6 种主题风格。
  • 符合 KDP 标准尺寸 (1600×2560)。
• 广泛兼容：经过微信读书、Apple Books 真机测试，排版不乱码、不错位。

安装与前置条件

方式 1：通过 npx 安装 Skill（推荐）

如果你使用 Claude Code，这是最快捷的方式：

npx skills add joeseesun/qiaomu-epub-book-generator

方式 2：Git 克隆

git clone https://github.com/joeseesun/qiaomu-epub-book-generator.git ~/.claude/skills/qiaomu-epub-book-generator

前置依赖

确保你的系统已安装以下环境：

1. Python 3.8+
2. pip
3. Playwright (用于 SVG 渲染和封面生成)

安装 Python 依赖：

pip install ebooklib markdown Pillow playwright beautifulsoup4
playwright install chromium

验证安装：

python3 -c "import ebooklib; print('OK')"

快速开始

第 1 步：准备内容

将所有 .md 文件放入一个目录，例如 ~/my-articles/。

第 2 步：生成 EPUB

方法 A：使用 Claude Code (自然语言)

直接对 Claude 说：

“从 ~/my-articles/ 生成 EPUB，书名《我的技术博客》，作者张三”

方法 B：使用命令行脚本

cd ~/.claude/skills/qiaomu-epub-book-generator/scripts

python3 gen_epub_enhanced.py ~/my-articles ~/output.epub \
  --title "我的技术博客" \
  --author "张三" \
  --cover-svg \
  --cover-theme tech

第 3 步：验证

检查输出文件：

ls -lh ~/output.epub

将文件发送到手机，用微信读书或 Apple Books 打开查看效果。

高级用法与参数

1. 自定义封面

• 自动生成 SVG 封面：

  --cover-svg --cover-theme business --cover-layout modern
  

• 使用自定义图片：

  --cover ~/my-cover.jpg
  

2. 优化文件大小

如果电子书过大，可以降低图片质量或宽度：

--image-quality 75 --image-width 800

3. 多作者与元数据

--author "张三 / 李四" --language zh --subtitle "2026年度精选"

封面主题预览

真实案例：Tw93 技术文集

将 4 篇高质量技术文章（含 53 张图片，其中 33 张为 SVG）转换为 EPUB：

python3 gen_epub_enhanced.py /tmp/tw93_articles ~/Tw93技术文集.epub \
  --title "Tw93技术文集" \
  --subtitle "Claude、Agent、LLM 与学习方法论" \
  --author "Tw93" \
  --cover-theme tech \
  --image-quality 88

结果：生成 2.9 MB 的 EPUB 文件，图片清晰，代码高亮正常，在微信读书中阅读体验极佳。

常见问题 (FAQ)

• Q: 报错 ModuleNotFoundError: No module named 'ebooklib'?
  • A: 请运行 pip install ebooklib markdown Pillow playwright beautifulsoup4。
• Q: 报错 Executable doesn't exist?
  • A: 请运行 playwright install chromium 安装浏览器内核。
• Q: 代码块出现红框或乱码?
  • A: v2.0+ 版本已修复 Pygments 正则导致的边框问题，请确保使用最新版本。
• Q: 图片未显示?
  • A: 检查 Markdown 中的图片链接是否为有效的 http/https 地址或正确的相对路径。
• Q: 文件太大?
  • A: 尝试降低 --image-quality 至 75 或 --image-width 至 800。