如何用 npm run book:epub 构建 easy-vibe 开放教材 EPUB 电子书【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibeeasy-vibe 课程以 VitePress 站点形式存放在docs/目录下。如果需要一份可以离线阅读、用于课堂或教材发放的电子书仓库提供了book:epub脚本把各语言课程 stage-1 / stage-2 / stage-3 的正文页面按目录结构编译成 EPUB 3.0 电子书输出到docs/.vitepress/dist/目录。构建入口定义在 package.json 的scripts.book:epub实际执行的是node scripts/build-epub.mjs。构建过程做了什么scripts/build-epub.mjs 的工作流程在源码中可以核对理解它对判断构建结果有帮助读取 VitePress 配置docs/.vitepress/config.mjs路径常量定义在 scripts/book-shared.mjs 的configPath取出对应 locale 的 stage-1 / stage-2 / stage-3 sidebar按分组展开成书籍的 Part阶段→ 章分组→ 页页面三级结构附录appendix页面默认被排除只保留各 stage 的正文逐页读取 Markdown 源码剥离 frontmatter 与script/style块把课程中的 Vue 组件块如ChapterIntroduction、StepBar改写为可渲染的 Markdown提示容器、脚注、KaTeX 公式、mermaid 图渲染为 PNG都会被转换文档内链被重写为书内chXXX.xhtml页面引用图片按“格式转换 → 降采样 → 大图转 JPEG”流程优化后打包进OEBPS/images/用archiver生成符合 EPUB 3.0 结构的 zip 包mimetype、META-INF/container.xml、OEBPS/content.opf、nav.xhtml、封面、简介、版本说明等前置页封面 logo 取自docs/public/logo.png。书籍元数据书名、副标题、阶段标题等按 locale 内置在 scripts/book-shared.mjs 的LOCALE_TITLE/LOCALE_SUBTITLE中例如zh-cn对应书名「Easy-Vibe 教程」、副标题「从零到一学习 Vibe Coding」。准备条件Node.js 版本满足 package.json 中engines.node声明的18.0.0在仓库根目录执行npm install安装依赖EPUB 构建用到的markdown-it、markdown-it-container、markdown-it-footnote、katex、archiver均在devDependencies/dependencies中构建过程只读取docs/下的课程文档写入docs/.vitepress/dist/和系统临时目录临时目录在结束时自动清理不会修改课程源码。注意一个实际约束构建会把 WebP、GIF 图片先转成 PNG转换按顺序尝试magick、convertImageMagick、ffmpeg、sips四个工具逻辑在 scripts/epub-image-conversion.mjs。docs/zh-cn等语言目录下存在.webp图片因此如果上述工具一个都没有安装遇到这类图片时构建会抛出Unable to convert image to PNG: 路径错误。构建前可确认本机至少有一个可用magick -version || convert -version || ffmpeg -version || sips --version运行构建在仓库根目录执行npm run book:epub等价于node scripts/build-epub.mjs。不设置任何环境变量时构建语言为zh-cn脚本内EPUB_LOCALE的默认值输出文件为docs/.vitepress/dist/easy-vibe-open-textbook-zh-cn-v1.0.0.epub其中版本号取自package.json的version字段1.0.0。构建是单进程串行完成页数较多的语言如zh-cn含大量页面和图片耗时会更长属于正常现象。构建其他语言时通过EPUB_LOCALE环境变量指定支持的全部 locale 及对应语言标签定义在 scripts/book-shared.mjs 的LOCALES列表zh-cn、en、zh-tw、ja-jp、ko-kr、es-es、fr-fr、de-de、ar-sa、vi-vn。例如构建英文版EPUB_LOCALEen npm run book:epub可选的构建参数脚本从环境变量读取以下配置均为可选不设置时使用表中默认行为环境变量用途默认值EPUB_LOCALE构建语言必须是LOCALES列表中的键zh-cnEPUB_BOOK_TITLE覆盖书名按 locale 的LOCALE_TITLEEPUB_TAGLINE覆盖书籍描述写入content.opf的dc:description书名 · 副标题EPUB_FILE_NAME覆盖输出文件名easy-vibe-open-textbook-locale-v版本.epubEPUB_VERSION指定版本号需匹配数字.数字.数字格式否则依次回退到GITHUB_REF_NAME、git tag、package.json的version1.0.0EPUB_ONLINE_URL版本说明页中“在线版本”链接的地址https://datawhalechina.github.io/easy-vibe/locale/PDF_BUILD_DATE版本说明页中展示的构建日期构建当天Asia/Shanghai时区长日期格式BOOK_IMAGE_MAX_DIM栅格图最大边降采样上限像素1600BOOK_JPEG_THRESHOLD_KB超过该大小的 PNG 尝试转 JPEG300BOOK_JPEG_QUALITY转 JPEG 的质量参数82图片相关参数只影响体积控制策略不影响内容完整性本机没有magick/convert/sips时降采样与 JPEG 转换会被跳过图片以原样或 PNG 转换后的结果打包。带透明通道的 PNG 不会转 JPEG。验证构建结果构建结束时脚本会在控制台打印三类信息数字随实际内容变化不是固定预期值Found N pages in stages 1-3 (excl. appendices) Rendered N chapters, collected N images, mapped N internal links Wrote docs/.vitepress/dist/easy-vibe-open-textbook-zh-cn-v1.0.0.epub (N.N MB)核对要点Wrote ...一行给出产物完整路径与体积确认该.epub文件已出现在docs/.vitepress/dist/下即可认为构建成功Rendered行的页数应与Found行一致若明显偏少检查是否出现下方“已知限制”中的警告把产物导入任意 EPUB 阅读器如 Calibre、Apple Books打开应能看到封面、目录含三个阶段的分组导航、本书简介、版本说明页以及各章正文和书内跳转链接。已知限制与常见报错locale 不受支持EPUB_LOCALE不在LOCALES列表时脚本直接报错Unsupported EPUB_LOCALE值. Supported: ...并以非零码退出。对照 scripts/book-shared.mjs 中的列表核对拼写即可页面缺失警告sidebar 中配置了链接但对应.md文件不存在时输出Warning: N pages not found: ...缺失页面不会进入书籍。这类警告指向docs/.vitepress/config.mjs中 sidebar 与docs/locale/实际文件不一致需要按警告列出的链接补齐页面或修正配置图片转换失败出现Unable to convert image to PNG: 路径时说明 WebP/GIF 图片没有任何可用的转换工具magick/convert/ffmpeg/sips按“准备条件”一节安装其一后重试无效图片跳过打包阶段遇到不存在或小于 100 字节的图片会打印Warning: Skipped N invalid/empty images这些图片不会出现在电子书中mermaid 图渲染mermaid 代码块通过 scripts/render-book-asset.mjs 渲染为 PNG渲染失败时脚本内置 3 次重试降级为带源码的占位框构建不会中断。下一步如果还需要同一语言的其他书型package.json中的book:pdfLaTeX PDF与book:all可组合使用只想批量构建 EPUB 时npm run book:all:epub即BOOK_EPUB_ONLY1 node scripts/build-books.mjs会为全部 locale 依次生成 EPUB单个语言可用npm run book:zh、npm run book:en触发但注意这两个脚本默认同时构建 PDF 和 EPUB需要排除 PDF 时配合BOOK_EPUB_ONLY1使用。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
