Go语言生成PDF实战教程

本文深入解析了Go语言生成PDF的实战要点与避坑指南，重点推荐轻量稳定的纯Go库gofpdf作为入门首选，详解其无依赖、易交叉编译的优势及中文字体注册、单位设置、内容宽度控制等关键细节；同时客观对比unidoc（支持模板、密码保护但需付费）与已被淘汰的pdfgen/gopdf（存在兼容性差、CGO依赖重、文档错误多等致命缺陷），并强调生成后必须进行文件魔数校验、大小检查和并发隔离，直击“看似生成成功却打不开”这一生产环境高频痛点，助开发者真正落地可靠、可维护的PDF导出能力。

用 gofpdf 生成基础 PDF 最快上手

直接用 gofpdf 是 Go 生态里最稳的选择，不依赖系统库，纯 Go 实现，交叉编译友好。它不支持复杂排版或 HTML 渲染，但生成报表、票据、导出文字/表格这类需求足够轻量又可靠。

常见错误现象：pdf.OutputFileAndClose("out.pdf") 报错 open out.pdf: permission denied —— 很可能是当前目录不可写，或路径含非法字符（比如 Windows 下用了 \ 而没转义）。

• 初始化时别漏掉 gofpdf.New 的单位和格式参数，比如 gofpdf.New("pt", "A4", "en-US")，单位错会导致字体、边距全乱
• 中文必须显式注册字体，pdf.AddUTF8Font("simhei", "", "fonts/simhei.ttf")，且后续所有文本要用 pdf.SetFont("simhei", "", 12)，否则显示方块
• 如果输出内容是动态拼接的字符串，注意 pdf.Cell 或 pdf.MultiCell 对换行和宽度敏感，超宽会截断不报错

unidoc 支持模板和密码保护，但要付费

如果你需要填 PDF 表单、加水印、设置打开密码或权限密码，unidoc 是目前 Go 里唯一能稳定做到的方案。它的免费版只能读取 PDF，生成/编辑功能需商业授权 —— 这点容易被 README 误导，直到调用 creator.CreatePDF 时 panic 才发现。

使用场景：内部系统导出带数字签名的合同、给客户发加密财报、复用已有 PDF 模板填充字段。

• 免费版调用 pdfcpu.CreateEmptyPDF 可以创建空 PDF，但一旦尝试 pdfcpu.AddPage 或写入内容，就会触发 unlicensed use 错误
• 字体嵌入比 gofpdf 简单，直接传 TTF 路径即可，但不支持 OTF；中文字体建议用 Noto Sans CJK，避免某些字形缺失
• 生成速度比 gofpdf 慢约 3–5 倍，大文件（>50 页）建议加 runtime.GC() 防止内存暴涨

别碰 pdfgen 和 gopdf

pdfgen 已三年没更新，Go 1.21 下编译失败，关键函数如 NewPDF 返回类型不兼容；gopdf 虽活跃但底层用 CGO 调 libharu，Windows 上得装 VS Build Tools，Linux 容器里还得 apt install libhpdf-dev，CI 构建极易失败。

错误现象举例：undefined: pdf.New（pdfgen）、cgo: exec gcc: exec: "gcc": executable file not found（gopdf 容器环境）。

• 这两个库的文档都把 SetPageSize 写成 SetPageSizes，实际方法名是单数，抄示例必报错
• gopdf 的 WriteText 不自动换行，也无 MultiText 替代，长文本得自己切分，逻辑容易漏边界
• 它们都不处理 UTF-8 字节序标记（BOM），带 BOM 的中文字符串写进去会多一个乱码字符

生成 PDF 后校验是否可读

很多服务导出 PDF 后直接返回 HTTP 响应，但用户下载打不开——往往不是生成失败，而是 PDF 结构损坏，浏览器静默失败。

简单校验方式：用 pdfcpu.Validate（需引入 pdfcpu/cmd）或更轻量的 file 命令检查魔数：

file -b out.pdf

正常输出应为 PDF document, version 1.4。若返回 data 或 cannot open `out.pdf' (No such file)，说明文件为空或写入失败。

• 生成后务必检查 os.Stat 返回的 Size()，小于 1024 字节基本可判定失败
• 不要用 ioutil.ReadFile 读刚生成的 PDF 做校验，小概率遇到文件未 flush 完就去读，得到截断内容
• 并发生成多个 PDF 时，确保每个 *gofpdf.Fpdf 实例独立，共用实例会导致字体、页码状态错乱

真正麻烦的从来不是“怎么生成”，而是“怎么确保生成的每一份都真能打开”——尤其是带中文字体和动态数据时，少一次 SetFont、多一个 BOM、路径少个斜杠，都可能让最终文件变成二进制垃圾。

今天关于《Go语言生成PDF实战教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！