GitBook 本地使用避坑指南，轻松导出 PDF 版本的实战经验分享

导读：本文将带你深入了解 GitBook 在本地使用的常见问题，并手把手教你如何成功导出一个格式美观、内容完整的 PDF 文档。如果你也曾经在使用 GitBook 导出 PDF 的过程中踩过坑，那么这篇文章或许能帮你少走弯路。

为什么选择 GitBook？

作为一名技术博主，我一直在寻找一种既能方便写作，又能兼顾文档结构和输出格式的工具。GitBook 凭借其简洁的 Markdown 编辑界面和强大的目录管理能力，一度成为我的首选。

然而，在实际使用中我发现，虽然 GitBook 提供了云端服务，但很多人更倾向于在本地搭建环境，尤其是对于一些敏感内容或离线需求较高的项目。

本地部署 GitBook 遇到的那些坑

刚开始尝试在本地运行 GitBook 的时候，我以为只要安装好 Node.js 和 GitBook CLI 就万事大吉了。结果运行 gitbook serve 后，页面确实跑起来了，但在导出 PDF 的时候却频频报错。

遇到的第一个问题是：导出 PDF 时提示找不到 ebook-convert 命令。

后来才知道，这是由于没有正确安装 Calibre 所致。Calibre 是 GitBook 用来转换电子书格式的一个依赖工具。我按照官方文档下载安装后，又遇到了路径配置的问题。

解决方法：

• 前往官网下载并安装 Calibre（https://calibre-ebook.com/download）
• 将 Calibre 的安装路径添加到系统环境变量中
• 验证命令行是否识别：ebook-convert --version

导出 PDF 时的样式丢失问题

解决了基本依赖之后，我尝试用 gitbook pdf . output.pdf 命令生成 PDF 文件。结果打开一看，排版乱得一塌糊涂，图片不显示，代码块缩进也全乱了。

后来查资料发现，GitBook 默认的 CSS 样式并不适用于 PDF 输出。

于是我开始手动修改主题中的 CSS 文件，特别是针对 PDF 输出的部分做了专门调整。比如设置字体大小、调整段落间距、修复图片居中等问题。

关键技巧：

• 创建一个自定义的 styles/website.css 和 styles/pdf.css 文件夹
• 在 book.json 中指定不同输出方式的样式文件
• 使用 @media print 来优化打印样式

最终成功导出可用 PDF 的步骤总结

经过反复调试，我整理了一套相对稳定的流程，供大家参考：

1. 安装 Node.js 和 npm
2. 全局安装 GitBook：npm install -g gitbook-cli
3. 安装 Calibre 并配置环境变量
4. 初始化项目：gitbook init
5. 编写内容并测试网页端效果
6. 配置 book.json 中的主题和样式路径
7. 执行导出：gitbook pdf . mybook.pdf

写在最后的一点小建议

说实话，GitBook 虽然功能强大，但它的本地支持并不是特别友好。尤其在中文环境下，很多资料都是英文文档，需要自己慢慢摸索。

如果你只是想做一个简单的电子书，可能可以考虑其他替代方案，比如 Typora + Pandoc 或者 Docsify，它们在某些场景下会更轻量便捷。

不过，如果你追求的是结构清晰、章节分明、可扩展性强的内容管理系统，GitBook 依然是一个非常值得投入时间去研究的工具。