搜索博客文章
很多业务系统都有PDF生成需求:导出报表、生成发票、合同、报告文档。传统方案要么在项目中集成Puppeteer、wkhtmltopdf,需要处理浏览器依赖、字体缺失、环境兼容等一堆麻烦;要么选用第三方SaaS服务,会有数据隐私、调用成本、网络依赖等问题。今天给大家介绍一款Docker驱动的开源PDF转换API工具——Gotenberg,把PDF相关能力封装成独立微服务,一次部署,任意语言调用。
Gotenberg是基于Docker构建的无状态文档转换API服务,底层整合了Chromium、LibreOffice、QPDF、pdfcpu等工具,只需要发送HTTP multipart/form‑data请求,传入网页地址、HTML、Markdown或者Office文件,就可以直接拿到PDF文件。
项目数据:GitHub 12k+ Star,Docker镜像拉取量超8200万,MIT开源协议,支持amd64、arm64、armhf等多CPU架构,Go语言开发,已经被大量企业用于生产环境。
核心优势:
本地验证非常简单,只需要Docker环境:
# 启动gotenberg8服务,监听3000端口
docker run --rm -p "3000:3000" gotenberg/gotenberg:8
一行curl把网页转为PDF:
curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://example.com \
-o output.pdf
执行完成后,本地就会生成output.pdf文件,整个流程不需要安装Chrome、LibreOffice等软件。
使用无头Chromium引擎,渲染效果和真实浏览器完全一致,完美支持JS、Web字体、现代CSS,特别适合SPA单页应用导出PDF。
示例调用,等待页面window.status === 'ready'后再生成PDF,附带鉴权请求头:
curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://my.url \
--form 'waitForExpression=window.status === 'ready'' \
--form 'extraHttpHeaders={"Authorization": "Bearer 123"}' \
-o my.pdf
内置LibreOffice,支持docx、xlsx、pptx等上百种办公格式转为PDF。
示例docx转PDF:
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@my.docx \
--form nativePageRanges=1-5 \
--form pdfa=PDF/A-1b \
-o my.pdf
内置QPDF、pdfcpu、ExifTool,无需额外工具,直接完成PDF二次加工:
示例:合并两份PDF并设置用户密码:
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@doc1.pdf \
--form files=@doc2.pdf \
--form userPassword=user_secret \
--form ownerPassword=owner_secret \
-o merged_and_secured.pdf
这个是非常实用的高级特性,业务服务器不需要中转文件:
业务服务器只需要下发任务,文件不走应用服务器,节省带宽,适合大文件处理。
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form 'downloadFrom=[{"url": "https://my-bucket.s3.amazonaws.com/file.docx"}]' \
--header 'Gotenberg-Webhook-Url: https://my-bucket.s3.amazonaws.com/out.pdf' \
--header 'Gotenberg-Webhook-Method: PUT' \
--header 'Gotenberg-Webhook-Events-Url: https://my-api.com/events'
✅ SaaS系统导出发票、报表、合同PDF
✅ 后台系统Word/Excel文档批量转PDF归档
✅ SPA前端页面导出PDF报告
✅ 需要PDF/A合规档案文档输出
✅ 多语言技术栈项目,不想每个服务维护PDF依赖
优点
不足
| 方案 | 部署方式 | 网页渲染 | Office文档转换 |
|---|---|---|---|
| Gotenberg | Docker微服务 | Chromium完整支持 | ✅支持 |
| Puppeteer | 嵌入业务进程 | Chromium完整支持 | ❌不支持 |
| wkhtmltopdf | 本地命令行 | 老旧webkit,CSS支持差 | ❌不支持 |
| 商业PDF SaaS | 第三方托管 | Chromium | 部分支持 |
如果你的项目同时需要网页转PDF+Office文档转PDF,并且希望数据不出内网,Gotenberg是非常优质的选择。
Gotenberg把PDF相关的复杂底层全部封装起来,把PDF生成这件事变成简单的HTTP调用。很多开发者饱受各种PDF库环境坑,而Gotenberg用容器化微服务的思路,把浏览器、办公套件隔离到独立服务,业务代码只关心业务逻辑。
如果你项目正在被PDF导出问题折磨,不妨试试Gotenberg。
项目官网:https://gotenberg.dev/
GitHub地址:https://github.com/gotenberg/gotenberg