AINav

Gotenberg：开箱即用的开源 PDF 转换微服务，告别 PDF 生成的各种坑

2026/8/22·1 views

很多业务系统都有PDF生成需求：导出报表、生成发票、合同、报告文档。传统方案要么在项目中集成Puppeteer、wkhtmltopdf，需要处理浏览器依赖、字体缺失、环境兼容等一堆麻烦；要么选用第三方SaaS服务，会有数据隐私、调用成本、网络依赖等问题。今天给大家介绍一款Docker驱动的开源PDF转换API工具——Gotenberg，把PDF相关能力封装成独立微服务，一次部署，任意语言调用。

什么是Gotenberg

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语言开发，已经被大量企业用于生产环境。

核心优势：

  1. 语言无关：只需要HTTP请求，Java、PHP、Python、NodeJS等任意后端都可以调用，业务代码不需要引入笨重PDF类库。
  2. 容器化部署：所有底层依赖全部打包进镜像，本地、K8s、Docker Compose一键运行，不会出现本地能跑、生产环境缺依赖的窘境。
  3. 能力全面：网页/HTML/Markdown转PDF、Office文档转PDF、PDF后期处理、云存储直读直写一站式搞定。
  4. 无状态架构：可以横向扩容，适合高并发业务场景。

快速上手：两条命令跑通服务

本地验证非常简单，只需要Docker环境：

bash 复制代码 
# 启动gotenberg8服务，监听3000端口
docker run --rm -p "3000:3000" gotenberg/gotenberg:8

一行curl把网页转为PDF：

bash 复制代码 
curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://example.com \
-o output.pdf

执行完成后，本地就会生成output.pdf文件，整个流程不需要安装Chrome、LibreOffice等软件。

四大核心能力详解

1. 基于Chromium高精度网页渲染转PDF

使用无头Chromium引擎，渲染效果和真实浏览器完全一致，完美支持JS、Web字体、现代CSS，特别适合SPA单页应用导出PDF。

  • 支持URL、HTML文件、Markdown三种输入源
  • 可以等待JS执行完成、等待网络空闲、等待指定DOM元素出现之后再导出，解决异步页面渲染不全问题
  • 支持自定义Cookie、请求头，可完成带鉴权页面导出

示例调用，等待页面window.status === 'ready'后再生成PDF，附带鉴权请求头：

bash 复制代码 
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

2. LibreOffice办公文档转换

内置LibreOffice，支持docx、xlsx、pptx等上百种办公格式转为PDF。

  • 支持指定页码范围导出，比如只导出文档1‑5页
  • 支持输出PDF/A归档标准格式，满足档案业务合规要求

示例docx转PDF：

bash 复制代码 
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

3. PDF后期处理引擎

内置QPDF、pdfcpu、ExifTool，无需额外工具，直接完成PDF二次加工：

  • PDF合并、拆分、页面旋转、添加水印、压平表单注释
  • PDF密码加密、设置权限，读写元数据、书签
  • 支持生成Factur‑X电子发票格式

示例：合并两份PDF并设置用户密码：

bash 复制代码 
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

4. 零传输流水线：直连对象存储

这个是非常实用的高级特性，业务服务器不需要中转文件：

  1. Gotenberg直接从S3/MinIO/GCS预签名URL拉取源文件
  2. 转换完成后直接上传PDF到对象存储
  3. 通过Webhook回调通知业务系统成功或者失败

业务服务器只需要下发任务，文件不走应用服务器，节省带宽，适合大文件处理。

bash 复制代码 
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转换、PDF编辑在同一个服务完成
  • 标准化HTTP接口，集成成本低，支持OpenTelemetry监控指标，方便运维观测

不足

  • 需要自行部署维护，没有官方托管SaaS版本
  • Chromium+LibreOffice镜像体积较大，高并发场景CPU、内存消耗较高，需要做好扩容规划
  • 没有可视化模板编辑器，需要自己准备HTML/源文档模板

和其他PDF方案简单对比

方案 部署方式 网页渲染 Office文档转换
Gotenberg Docker微服务 Chromium完整支持 ✅支持
Puppeteer 嵌入业务进程 Chromium完整支持 ❌不支持
wkhtmltopdf 本地命令行 老旧webkit，CSS支持差 ❌不支持
商业PDF SaaS 第三方托管 Chromium 部分支持

如果你的项目同时需要网页转PDF+Office文档转PDF，并且希望数据不出内网，Gotenberg是非常优质的选择。

生产环境小提示

  1. Gotenberg是无状态服务，高并发场景部署多个实例，负载均衡调度；Chromium单实例并发上限约6个请求，注意队列配置。
  2. 如果需要中文，需要自行把中文字体打包进Docker镜像，避免中文乱码。
  3. 大文件优先使用downloadFrom+webhook流水线模式，避免HTTP请求超时。
  4. 开启健康检查、Prometheus指标，监控队列、转换耗时，及时发现服务异常。

写在最后

Gotenberg把PDF相关的复杂底层全部封装起来，把PDF生成这件事变成简单的HTTP调用。很多开发者饱受各种PDF库环境坑，而Gotenberg用容器化微服务的思路，把浏览器、办公套件隔离到独立服务，业务代码只关心业务逻辑。

如果你项目正在被PDF导出问题折磨，不妨试试Gotenberg。
项目官网：https://gotenberg.dev/
GitHub地址：https://github.com/gotenberg/gotenberg

对这篇文章有意见或建议？提交反馈