Golang开发PDF文本提取工具实战

本文深入探讨了在Go语言生态中开发轻量级PDF文本提取工具的实战要点，重点解决了pdfcpu处理中文乱码的核心痛点——必须通过绝对路径指定fontmap.yml映射中文字体，且嵌入字体场景下该配置失效；同时对比了unidoc等替代方案在许可、体积与可靠性上的明显短板，并厘清了PDF加密对文本提取的真实影响边界（仅owner密码构成硬性阻断）；最终指出：pdfcpu凭借其可控的字体映射、严格的权限识别和极简的内存模型，成为当前Go生态中平衡功能、性能与合规性的最优选择，而对嵌入字体PDF的真正支持，则需转向OCR层面的文档理解方案。

pdfcpu 提取文本时中文乱码怎么办

默认不支持中文，因为 pdfcpu 内置字体映射没覆盖常见中文字体（如 Adobe-GB1、GBK），直接调用 pdfcpu extract text 会把中文转成空格或方块。

• 必须显式指定字体映射配置文件：用 -f 参数传入自定义 fontmap.yml
• fontmap.yml 至少要包含一条匹配规则，例如 Adobe-GB1: /System/Library/Fonts/PingFang.ttc（macOS）或 SimSun: C:\Windows\Fonts\simsun.ttc（Windows）
• 路径必须是绝对路径，相对路径在 pdfcpu 中会被忽略
• 如果 PDF 使用了嵌入字体（Embedded Font），fontmap.yml 无效，得先用 pdfcpu validate 检查是否含嵌入字体；有则需换库（如 unidoc）或预处理剥离字体

用 golang 调用 pdfcpu 提取文本的最小可行代码

别直接 exec.Command 包一层就完事——pdfcpu 的 Go API 是纯函数式设计，不暴露底层 reader，但支持从 io.Reader 加载 PDF，更可控也更省内存。

• 导入 github.com/pdfcpu/pdfcpu/pkg/api 和 github.com/pdfcpu/pdfcpu/pkg/pdfcpu
• 用 api.ExtractText，传入 *pdfcpu.Configuration（关键：设置 Conf.FontMapFile = "/path/to/fontmap.yml"）
• 输入必须是 bytes.Reader 或 os.File，不能是网络流（http.Response.Body 需先 io.ReadAll）
• 返回的 string 是按页拼接的，每页之间用 "\f" 分隔，不是 "\n"，注意切分逻辑

cfg := pdfcpu.NewDefaultConfiguration()
cfg.FontMapFile = "/etc/fontmap.yml"
text, err := api.ExtractText(bytes.NewReader(pdfData), nil, cfg)

为什么 github.com/unidoc/unipdf 不适合轻量 CLI 工具

unidoc 的 Go SDK 功能全，但对简单文本提取来说太重：许可证限制、编译慢、二进制体积大、运行时依赖多。

• 免费版只支持 200 页/天，超限后 pdf.Reader.Read 会静默返回空文本，无明确错误提示
• 必须调用 license.SetLicenseKey，否则部分 PDF（尤其带加密或非标准结构）会 panic 报 "invalid object number"
• 编译出的二进制含大量未使用的渲染/图像模块，Linux amd64 下轻松破 40MB，而 pdfcpu + fontmap 可控在 8MB 内
• 它默认把换行符标准化为 "\n"，看似友好，但实际会合并原文档中因排版产生的“假换行”，导致段落粘连

PDF 加密时 extract text 失败的快速判断和绕过

不是所有加密都阻止文本提取。pdfcpu 会区分 owner password 和 user password，只有 owner password 才真正限制内容操作。

• 用 pdfcpu validate -v input.pdf 查看输出里是否有 Encrypted: true 和 Permissions: ... text extraction denied
• 如果只是 user password（打开密码），传入 -pw yourpass 即可继续提取，无需解密 PDF 文件本身
• 如果 owner password 锁死了文本权限，且你没有密码，基本无解——Go 生态里没有开源库能绕过 AES-256 权限位
• 别试 qpdf --decrypt 后再喂给 pdfcpu：qpdf 会重写对象流，某些 PDF 经此处理后反而触发 pdfcpu 的 strict mode 报错 "invalid xref"

到这里，我们也就讲完了《Golang开发PDF文本提取工具实战》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！