盘点 Go 生态的 PDF 库:为什么＂提取文本＂这么难?

导语：做 Go 的同学想从 PDF 里提取文字，大概率踩过这样的坑：pdfcpu 名气很大，但根本没有文本提取功能；go-fitz 能提，但它是 CGo 封装 MuPDF，而且只给整页纯文本，不给坐标；想带坐标提取，只能投奔商业库。Go 生态的 PDF 库，到底能不能打？这篇文章先盘一遍主流选择，再介绍一个纯 Go 的破局者。

柔晶美软件

一、先盘一圈：Go 生态的主流 PDF 库

数据截至 2026 年年中，按 GitHub 星标和社区活跃度，Go 生态里和 PDF 相关的库大致分四类。

生成类：只会写，不会读

gofpdf（jung-kurt/gofpdf，约 4.5k star，MIT）和它的官方续作 go-pdf/fpdf，加上signintech/gopdf（约 2.9k star，MIT），是 Go 里最常用的 PDF 生成方案，画文本、画线、插图片、做报表都没问题。但它们是单向的：只写不读，没有任何解析能力，和"提取"这个主题无关。而且 jung-kurt/gofpdf 已在 2021 年归档，go-pdf/fpdf 也处于归档状态，维护基本停滞。

处理类：操作 PDF，但读不出文本

pdfcpu（github.com/pdfcpu/pdfcpu，约 7.7k star，Apache-2.0）是 Go 生态最活跃的 PDF 处理项目，纯 Go、支持到 PDF 2.0，合并、拆分、加密、签名、水印、表单、优化都能干。但它的 extract 命令只支持 image、font、content、page、meta 五种模式，其中 content 导出的是原始内容流（PDF 语法），不是可读文本。也就是说，pdfcpu 没有文本提取功能，网上有些文章说它能提取文本，那是对官方文档的误传。

CGo 封装类：能力强，代价也大

go-fitz（github.com/gen2brain/go-fitz，约 0.6k star，AGPL-3.0）是 MuPDF 的 Go 封装，能把 PDF/EPUB/DOCX/XLSX/PPTX 提取成图片、文本、HTML、SVG，渲染能力一流。但要注意三点：其一，它是 AGPL 协议，商用闭源项目引入即触发开源义务，这对很多团队是硬伤；其二，编译依赖 CGo，自带库还不含 CJK 字体，要中文字体得换外部库，交叉编译麻烦；其三，它的文本提取只有整页纯文本Text()，没有带坐标的 word/span 级 API，也没有表格提取。想按坐标定位字段，它给不了。

go-pdfium（github.com/klippa-app/go-pdfium，约 0.4k star，MIT 绑定 + PDFium Apache-2.0）封装 Google 的 PDFium 引擎，有结构化文本接口（带角度、位置、字号、字体信息），但同样是 CGo 封装，编译期和运行期都要 pdfium 库，API 直接镜像 C 接口（FPDF_xxx 前缀），体感笨重，也没有表格提取。

纯 Go 解析类：文本能提，但各有短板

rsc.io/pdf（约 0.5k star，BSD-3-Clause）是 Rob Pike 的元祖级解析器，输出带坐标的字符级 run，但仓库已归档、功能极简，没有行/块/表格结构，阅读顺序、去重、聚类全靠自己写。

ledongthuc/pdf（约 0.6k star，BSD-3-Clause）是 rsc/pdf 的增强 fork，Go 里最常用的轻量文本提取选择，能按行返回带坐标的词。但维护松散（长期低提交、几十个 open issue），且有三个硬伤：Form XObject 内的文本直接丢失、%%EOF 后附加内容直接打不开、CID 中文字体在 CMap 缺失时乱码。

benoitkugler/pdf（约 30 star，MIT）以静态类型建模 PDF 规范，定位是给其他库做底层，没有开箱即用的文本提取 API，社区也近乎为零。

商业类：功能全，但收费

unidoc/unipdf（约 3.1k star）是商业级全能库，纯 Go，有词/行级坐标和表格提取（官方示例 PDF→CSV），但它需要 license key 才能运行，闭源商用要付费，包体和 API 面也大。

二、盘点结论：Go 生态做文本提取，缺什么

把上面这些库放一张表里看更清楚：

结论很直白：

• 纯开源库没有现成的表格提取，只能靠"带坐标文本 + 行/列聚类"自己拼
• 带坐标的文本提取，轻量路线（rsc/ledongthuc）功能弱且年久失修，完整路线（unipdf）要付费
• CGo 方案（go-fitz 的 AGPL、go-pdfium 的部署成本）对很多项目是硬约束

所以 Go 生态的现状是：能读文本的库不少，能带坐标读、能处理中文、能处理嵌套结构、还免费开源的，几乎没有。这就是 kzhpdf 出现的理由。

三、kzhpdf：以 ledongthuc/pdf 为底座，补齐四大短板

kzhpdf 的路线很务实：不重复造解析引擎，而是以 ledongthuc/pdf 为底层，把这个库的四大硬伤逐个补掉，目标是对标 Python 的 PyMuPDF / pdfminer.six。

前三个解决"能不能提取出来"，第四个解决"提取出来能不能直接用"。

相比生态里的其他库，kzhpdf 的优势

• 纯 Go、零 CGo、零 Python 依赖：不用像 go-fitz 那样拖着 C 代码和 AGPL 协议，不用像 go-pdfium 那样部署期还要装库，交叉编译轻松，二进制体积可控
• 文本提取对标 PyMuPDF：纯文本逐行比对一致率 98%（100 个真实 PDF），而不是像 pdfcpu 那样干脆没有文本提取
• 带坐标的完整结构：纯文本、带坐标单词（对标 get_text("words")）、字符→行→块布局、表格检测都有，弥补了 ledongthuc/pdf 只有词坐标、go-fitz 只有整页文本的缺口
• 中文不乱码：独立的 CMap 解析器处理 CID/Type0 字体，PLT/TF 系列报关单 PDF 的自定义字体也能正确解码
• 免费开源：MIT 协议，对比 unipdf 的商业授权，开箱即用

四、版本进化：从"能提取"到"提取得准"

v0.3.0：字体解码的重大优化

针对 PLT/TF 系列报关单 PDF 的乱码问题，v0.3.0 做了三件事：始终使用增强编码器（三级回退：原库 → CMap → 原始字节）；根据文本矩阵坐标变化在 Tj 操作符之间重建空格和换行；通过乱码检测自动切换解码策略。

v0.4.0：文本布局算法全面对标 MuPDF

v0.3.0 解决"乱码"，v0.4.0 解决"位置"。这一版把 ExtractPlainText 从"Tj 级别的粗略重建"重写为"逐字符精确跟踪"，完整复刻 MuPDF stext-device.c 的算法，修复了一批实际问题：

• 90° 旋转文本：从渲染矩阵提取方向向量，用点积投影计算间距，旋转页不再"每字一行"
• fake bold 描边重绘：2 Tr 描边模式导致每个字符出现两次，检测到同位置重复字符直接跳过
• 控制字符干扰换行：对标 MuPDF glyph==-1 语义，无字形字符推进矩阵但不更新笔尖
• 路径绘制中断：f/S 等路径操作对标 fill_path 打断文本流，修复表格列误合并
• 设备空间字符宽度：用 CTM 缩放后的字号计算推进，配合 PDF Widths 数组，坐标精度大幅提升

v0.5.0：单词级提取与图形状态修复

新增 GetWords（对标 PyMuPDF get_text("words")），输出 (x0, y0, x1, y1, text) 五元组，Y-down 坐标系与 PyMuPDF 完全一致，word 分割规则（空格、间距 > 0.15×字号、方向突变）也逐条对齐。同时修复了一个隐蔽的 gstack 底层数组共享 bug——XObject 内部的 q push 覆盖外层栈元素，导致坐标随内容流逐词累积（实测可膨胀到 x=84374），这也是之前坐标型提取偶发错乱的根本原因。

五、实测：109 个真实 PDF 全面对比 PyMuPDF

用 kzhpdf 和 PyMuPDF 各跑一遍 109 个真实报关单 PDF（含 62 个预放委难解析文件），逐字段比对：

文件总数:     109 (报关单 TF 系列 + 预录单 26BC 系列 + 放行单 PLT 系列 + 预放委 + 电子发票)解析成功:     109/109 (python 与 go 均 100%)字段总数:     python 2619, go 2654 (go 反超 35 个)字段值差异:   35 处 (全部为 PLT 系列”申报单位”, python 漏提, go 正确提取)一致文件数:   74 (字段数与 python 完全一致)python 占优:  0  (go 在全部文件上达到或超过 PyMuPDF 水平)

此前 v0.4.0 的 100 个 PDF 纯文本逐行比对，一致率 98%（81 个完全一致 + 17 个仅控制字符差异，kzhpdf 主动过滤不可见字符，输出更干净；2 个差异是电子发票印章弧线文字的装饰性分组，不影响业务提取）。

六、快速上手

安装：

go get gitee.com/kzhpdf/kzhpdf

package mainimport (	”fmt”	”gitee.com/kzhpdf/kzhpdf”)funcmain() {// 1. 打开 PDF (自动容错, 处理附加内容/损坏EOF)	doc, err := kzhpdf.Open(”example.pdf”)if err != nil {panic(err)	}defer doc.Close()// 2. 提取纯文本	text, _ := doc.Text()	fmt.Println(text)// 3. 提取布局结构 (字符 → 行 → 块)	pages, _ := doc.ExtractPages()for _, page := range pages {		fmt.Printf(”第%d页: %d字符, %d行, %d块\n”,			page.PageNum, len(page.Chars), len(page.Lines), len(page.Blocks))for _, block := range page.Blocks {			fmt.Println(block.Text())		}	}// 4. 提取表格	tables, _ := doc.ExtractAllTables()for pageNum, pageTables := range tables {for _, t := range pageTables {			fmt.Printf(”第%d页: %d行 x %d列, 表头: %v\n”, pageNum, t.Rows, t.Cols, t.Header)		}	}}

单词级提取需要从底层读取器拿页面对象（与 ledongthuc/pdf 兼容）：

// 5. 单词级提取 (对标 PyMuPDF get_text(”words”), 含坐标)closer, reader, _ := kzhpdf.OpenReader(”example.pdf”)defer closer.Close()page := reader.Page(1)words := kzhpdf.GetWords(page)for _, w := range words {	fmt.Printf(”(%0.1f, %0.1f, %0.1f, %0.1f) %s\n”, w.X0, w.Y0, w.X1, w.Y1, w.Text)}

从 ledongthuc/pdf 迁移

如果你已经在用原库，迁移成本几乎为零：

// 原库代码reader, err := pdf.NewReader(file, size)text, _ := reader.Page(1).GetPlainText(nil)// kzhpdf 代码 (一行替换)doc, err := kzhpdf.Open(”file.pdf”)text, _ := doc.PageText(1)// 或保持原库风格, 直接替换函数text := kzhpdf.GetPlainText(page)   // 兼容函数, 增加 XObject 支持content := kzhpdf.GetContent(page)  // 兼容函数, 增加 XObject 支持

七、适合什么场景

• 业务文档解析：报关单、发票、回执等结构化表单，通常嵌套 XObject、使用 CID 字体、附带各种"怪"编码
• 部署环境受限：纯 Go 编译，无 CGo 依赖，交叉编译轻松，二进制体积可控
• 离线/内网环境：不需要安装 Python 运行时，不需要打包解释器
• 不想引入商业库：MIT 协议，对比 unipdf 的 license key，开箱即用

如果你在 Go 项目里被 PDF 中文乱码、XObject 丢文本、%%EOF 校验失败、没有坐标 API 这些问题折磨过，不妨试试 kzhpdf。