Gotenberg：Docker化文档转PDF的一站式API

Gotenberg 是一个基于 Docker 的开发者友好型 API，可把 HTML、URL、Markdown、Word、Excel 等 100+ 文档格式一键转换为高质量 PDF，同时支持合并、拆分、水印、加密、截图等操作。无需自行维护 Chromium 或 LibreOffice，一条 docker run 命令即可在生产环境上线，已被数千家公司信赖。

适用人群：后端开发者：需要在服务端集成文档转 PDF 的 Go、Python、Node.js 等开发者；DevOps 工程师：想用容器化方案简化部署和扩缩容的运维人员；中小企业与开源项目：对成本敏感又需要稳定 PDF 转换能力的团队

适用场景：企业内部文档转换平台：员工上传 Word、Excel、HTML，系统即时返回 PDF；Web 应用中的“导出 PDF”按钮：在线报表、发票、合同等一键生成 PDF；批量文档处理与归档：定时任务将海量 HTML 或 Markdown 归档为 PDF/A、PDF/UA 合规文件

推荐理由：如果你正为文档转 PDF 而头痛，不想在服务器上手动折腾 Chromium、LibreOffice 和字体，Gotenberg 值得一试。它把复杂的底层引擎封装成简洁的 HTTP API，用 Docker 轻松部署，功能全面且开源免费，是替代商业 PDF 服务的绝佳选择。

项目定位与背景

Gotenberg 定位为开发者友好的文档转换 API，核心目标是让“把各种文档变成 PDF”这件事变得简单。它把 Chromium、LibreOffice 等复杂的底层引擎打包进 Docker 镜像，通过一个统一的 HTTP API 对外服务。开发者只需发送 multipart/form-data 请求，就能拿到转换好的 PDF，完全不用关心引擎安装、字体缺失、版本兼容等琐事。项目基于 Go 编写，性能出色，已获得超过 13000 个 Star，被数千家公司用于生产环境，并被多个知名开源项目采纳。

核心功能与技术架构

Gotenberg 的功能覆盖面非常广。HTML、URL、Markdown 转 PDF 借助 Headless Chromium 完成，能忠实还原网页样式，支持 CSS 打印媒体查询。Word、Excel、PPT 等 100 多种 Office 格式则通过 LibreOffice 转换，保证文档保真度。此外，它还支持 PDF 的合并、拆分、旋转、扁平化，添加水印、戳记、加密，以及 PDF/A 和 PDF/UA 合规处理。你甚至可以对 URL 或 HTML 进行截图，读取和写入 PDF 元数据与书签。

架构上，Gotenberg 是一个无状态的 HTTP 服务，所有转换任务都在容器内隔离执行。它通过调用外部命令（如 chromium-browser、libreoffice、qpdf、pdftk、exiftool）完成具体操作，Go 程序负责调度、参数解析和结果返回。这种设计让维护者可以方便地升级底层引擎，而不会破坏 API 稳定性。

创新点与亮点

Gotenberg 最大的创新在于将多个重量级的文档转换工具整合成一个开箱即用的 API，并通过 Docker 彻底解决了环境依赖问题。你不需要在宿主机上安装 Chromium、LibreOffice 或配置中文字体，只需一条 docker run 命令就能启动完整服务。它的 API 设计非常直观：POST 请求，带上表单字段，直接返回 PDF 文件流。这种极简交互极大降低了集成成本。

另一个亮点是功能丰富且专业。除了基础转换，它还内置了 PDF 合并、拆分、加密、水印、元数据操作，甚至支持 PDF/A 和 PDF/UA 合规，这对需要归档或满足无障碍标准的企业来说非常实用。而且所有功能都通过同一个 API 暴露，你不需要分别集成多个库。

与同类项目对比

市场上有不少文档转 PDF 方案。wkhtmltopdf 虽然轻量，但项目已停止维护，对现代 CSS 支持不足。Puppeteer 或 Playwright 能处理 HTML 转 PDF，但需要自己管理 Node.js 和 Chromium，且对 Office 文档无能为力。unoconv 基于 LibreOffice，但命令行工具对开发者不够友好，缺乏统一的 API。Gotenberg 的优势在于：统一的 API 接口、Docker 容器化部署、同时支持 Chromium 和 LibreOffice、功能涵盖转换与 PDF 操作，且完全开源免费。缺点是镜像体积较大（因为内置了多种引擎），且转换速度在批量大文件时不如一些原生库快，但稳定性和便利性足以弥补。

上手指南或快速开始

开始使用 Gotenberg 非常简单。确保你的机器已安装 Docker，然后执行：

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

服务启动后，默认监听 3000 端口。接着你可以直接用 curl 测试转换一个 URL 到 PDF：

curl --request POST http://localhost:3000/forms/chromium/convert/url --form url=https://sparksuite.github.io/simple-html-invoice-template/ -o invoice.pdf

返回的 invoice.pdf 就是转换好的文件。你也可以用 --form 参数上传本地 HTML 文件或指定其他选项，比如页边距、纸张大小等。完整文档请参考官方文档站点。

总结与展望

Gotenberg 是一个成熟、可靠且文档完善的开源项目，非常适合需要快速集成文档转 PDF 能力的团队。它通过容器化和统一 API 解决了传统方案的痛点，功能覆盖全面，社区活跃。未来，随着云原生和 Serverless 的普及，这种无状态、可水平扩展的转换服务会越来越受欢迎。如果你正在寻找一个生产级的 PDF 转换中间件，不妨试试 Gotenberg，它可能就是你一直在找的那把瑞士军刀。

查看 GitHub 项目