简介PdfPig 是 C# 环境下可用的 PDF 解析与生成库定位为 PdfBox 的 C# 移植版本面向需要读取 PDF 文本、提取页面内容、执行版面分析或生成带文字与几何图形的简单 PDF 文档的 .NET 开发者。它基于 .NET Standard 设计支持通过 NuGet 包管理器直接安装能够配合 hOCR、ALTO XML、Page XML 等文档分析格式适用于扫描文档 OCR 后处理、版面结构化抽取和文本挖掘等场景。资源提供 zip 压缩包体积约 27.03 MB平台未公布文件级数量与类型明细压缩包内为源码/库项目使用时可直接引入 C# 工程并从 NuGet 还原依赖。当前已有 570 人学习或下载具备一定参考价值。内含文本提取、版面分析、简单 PDF 创建等使用思路并给出从 0.0.x 迁移到 0.1.x 的说明可帮助开发者规避接口变动风险、快速上手新版本 API整体适合中高级 C# 开发者在文档处理类项目中选型参考。 我前前后后大概有七八年都在跟文档解析打交道最头疼的格式就是PDF。它表面上是“电子文档”内部却是一堆图形指令和对象流读起来确实磨人。过去在C#里处理PDF要么用商用库要么绕道调Java工具总归不太顺手。后来遇到PdfPig才感觉在.NET生态里终于有个能安稳做PDF内容提取的开源库。这个库常被叫做PdfBox的端口但它并不是简单把Java代码翻译一遍而是参考了PdfBox的解析思路在C#世界里重新实现了一遍。这篇文章就结合我自己实际用下来的经验把PdfPig怎么读PDF、怎么提取文本和其他内容、又有哪些坑要避开一次说清楚。1. 为什么是PdfPigPDF解析库选型背后的逻辑1.1 PDF格式为什么难解析想明白PdfPig的价值得先知道PDF到底难在哪。PDF不是像Word那样按照“段落、句子、单词”的结构存储文本它的底层是一套页面描述指令告诉解释器在某个坐标位置画一条线、放一个字形。文本内容往往被拆成一个个独立字形甚至按字节拆分再通过字体映射表把字形ID还原成Unicode字符。这就导致一个很尴尬的结果用记事本打开一个PDF看到的往往不是能读的文字而是一堆二进制流和类似BT /F1 12 Tf 100 200 Td (Hello) Tj ET这样的标记。单纯的字符串搜索根本无从下手必须解析PDF的对象模型追踪内容流再用字体编码做逆映射才能拿到真正可用的文本。而PdfPig做的事情就是把这套解析流程封装好让C#开发者直接拿结果不用自己去碰PDF内幕。1.2 PdfPig与PdfBox的真实关系标题里说PdfPig是PdfBox的端口这个说法要准确理解。Apache PdfBox是Java生态里非常出名的PDF处理库功能全面社区活跃。PdfPig在设计上确实大量参考了PdfBox的解析思路和对象模型比如对PDF文档结构的抽象、对内容流的处理方式都能看到PdfBox的影子。但PdfPig不是一个字节一个字节地移植Java代码。它在API设计上更贴合.NET开发者的习惯用了大量IEnumerable、IDisposable这类C#原生接口。比如读取页面时直接返回IReadOnlyListLetter配合LINQ做过滤排序非常顺手。同时PdfPig还吸收了.NET生态对异步、流式处理的偏好在处理大文件时更友好。这点在实际工程里非常重要因为它意味着你不是在“用C#调Java思维写的库”而是在用真正C#的方式解决问题。1.3 对比其他C# PDF库PdfPig的优势在哪选择PdfPig前我把当时主流的几个方案都试过各有利弊。整理一下对比方便你判断库主要定位读取/提取能力许可协议适合场景iTextSharp / iText 7生成、编辑PDF强项文本提取可用但商业许可严格AGPL/商业需要生成复杂PDF愿意承担许可成本PdfSharp生成PDF为主读取能力弱不适合内容提取MIT生成报表、绘图Docnet基于PDFium的封装文本提取可用但API偏底层MIT需要渲染和提取兼顾PdfPig专注读取与内容解析文本、位置、图像、元数据都覆盖MIT文本提取、坐标分析、结构化解析从表格能看出来PdfPig的切入点很精准它不追求“什么都能做”而是把“读”这件事做到极致。对很多自动化项目来说PDF是数据源而不是最终产物我们的核心诉求就是把里面的文本和位置信息准确提出来。PdfPig的MIT协议也意味着不用担心授权风险可以放心用在内部工具和商业系统里。2. 快速上手接入PdfPig并抽取第一段文本2.1 环境准备与NuGet安装在开始前先确认环境。PdfPig对.NET版本要求不高.NET Framework 4.6.1、.NET Core 3.1、.NET 6/7/8这些都能用WinForms、WPF、ASP.NET Core、控制台程序都支持。安装就一条命令dotnet add package UglyToad.PdfPig如果你用的是Visual Studio也可以直接在NuGet包管理器界面搜索UglyToad.PdfPig安装最新稳定版即可。需要注意包名里的UglyToad是作者的项目组织名不是随便一个同名包。安装完成后项目里会引用UglyToad.PdfPig核心程序集。这个库依赖很少不像某些PDF组件会拖进来一堆底层原生库所以跨平台部署很省心在Windows、Linux、macOS的.NET环境里都能跑。2.2 最小可运行示例逐页打印PDF文本最经典的需求就是把PDF里的文字全部捞出来。看代码using UglyToad.PdfPig; using UglyToad.PdfPig.Content; using (PdfDocument document PdfDocument.Open(C:\demo\document.pdf)) { foreach (Page page in document.GetPages()) { string pageText page.Text; int pageNumber page.Number; Console.WriteLine($--- 第 {pageNumber} 页 ---); Console.WriteLine(pageText); } }这段代码做了四件事打开PDF文档、遍历每一页、从页面对象取文本、输出到控制台。PdfDocument实现了IDisposable所以用using包裹确保文件句柄和底层资源能及时释放。这在批量处理几十个PDF文件时尤其重要忘了释放文件流会直接把系统文件句柄打满。Page.Text拿到的是PdfPig已经帮你拼好的整页字符串。它内部会把字母按位置关系重组为单词和行所以不需要你手动做拼接普通文档直接用它就够了。2.3 从页面里拿更细的内容Letters、Words、Blocks但Page.Text毕竟是“整页字符串”适合阅读和搜索缺了位置信息。做发票识别、合同比对、区域提取这些精细化任务时要的是每个字母在页面上的具体坐标。这时要用Page.Letters和Page.GetWords()。using (PdfDocument document PdfDocument.Open(C:\demo\document.pdf)) { Page firstPage document.GetPage(1); // 遍历每个字母拿到坐标和字形信息 foreach (Letter letter in firstPage.Letters) { Console.WriteLine(${letter.Value} at ({letter.StartX:F2}, {letter.StartY:F2}) $size {letter.GlyphRectangle.Width:F2} x {letter.GlyphRectangle.Height:F2}); } // 获取重组后的单词方便按完整词处理 foreach (Word word in firstPage.GetWords()) { Console.WriteLine(${word.Text} - {word.BoundingBox}); } }每页的字母数量通常不多几千到几万个字符跑循环完全没有性能压力。真正要注意的是理解PDF坐标单位PdfPig返回的坐标点是PDF的“用户空间单位”通常一个单位约等于1/72英寸跟DPI不是一回事。后面我会专门讲坐标这块的坑。除了Letters和Words还可以通过page.GetBlocks()拿到分块信息适合做版面分析。不过这个API依赖PDF内部的段落结构对排版复杂的文档表现不稳定我的建议是先用Letters自己按坐标分组反而更可控。3. 核心细节解析PdfPig的坐标体系与内容提取3.1 PDF坐标系统是怎么运作的PDF坐标系统的原点在页面左下角x轴向右增大y轴向上增大单位是点point1点等于1/72英寸。这跟很多桌面开发框架的左上角原点截然不同做坐标映射时一定要先换算。比如在WPF或WinForms里渲染高亮框必须用页面高度 - PDF坐标Y才能转成屏幕坐标。PdfPig的Letter对象里最核心的定位属性是StartX、StartY、EndX、EndY分别对应字母包围盒的左下角和右上角。此外还有一个GlyphRectangle属性返回一个PdfRectangle对象包含更完整的几何信息。Width和Height则可以快速判断字符尺寸是否异常。实际处理场景中我最常做的一件事就是按坐标过滤出目标区域内的字母。比如在很多票据PDF里发票号码固定在右上角区域这时候用坐标框选比搜关键词稳得多因为关键词可能变但位置不会变。3.2 利用坐标提取指定区域文本假设要从一批PDF里抽出“开票日期”这个字段位置固定在页面左上角某个矩形区域。实现思路分三步第一个是从page.Letters里筛出落在目标矩形范围内的字母第二个是把筛选出的字母按y坐标降序、x坐标升序重排第三个是拼成字符串。using UglyToad.PdfPig; using UglyToad.PdfPig.Content; using UglyToad.PdfPig.Geometry; using (PdfDocument document PdfDocument.Open(C:\demo\invoice.pdf)) { Page page document.GetPage(1); // 假设目标区域左下角(460, 680)右上角(580, 710) PdfRectangle region new PdfRectangle(460, 680, 580, 710); var charsInRegion page.Letters .Where(l l.StartX region.Left l.StartX region.Right l.StartY region.Bottom l.StartY region.Top) .OrderByDescending(l l.StartY) .ThenBy(l l.StartX) .Select(l l.Value) .ToList(); string fieldText string.Concat(charsInRegion); Console.WriteLine($抽取结果: {fieldText}); }这里有一个细节值得注意同一个y坐标上的字母如果按ThenBy(l l.StartX)升序排列基本能还原阅读顺序。但如果文字有旋转、斜体或竖排这个简单排序会失效需要额外处理基线与倾斜角。大部分票据类PDF都是规规矩矩的横排文本这套方案足够应付。3.3 不只文本元数据、链接与图像的提取PdfPig的名字看起来是“读文本”实际能提取的内容远不止文本。它可以通过document.Information读取文档级元数据包括标题、作者、创建时间、修改时间等等。在自动化归档场景里这些字段能够省去不少手工录入时间using (PdfDocument document PdfDocument.Open(C:\demo\document.pdf)) { Console.WriteLine($标题: {document.Information.Title}); Console.WriteLine($作者: {document.Information.Author}); Console.WriteLine($创建时间: {document.Information.Created}); Console.WriteLine($修改时间: {document.Information.Modified}); }至于页面里的图片PdfPig也提供了基础的图像对象访问能力。遍历page.GetImages()可以拿到原始图像字节和格式信息之后可以保存成PNG或直接交给OCR引擎。不过要提醒一句PdfPig对图像的定位是“能拿到原始数据”不是做图像渲染引擎所以复杂的色彩空间转换和压缩格式支持不如专用工具遇到异常图像要灵活降级处理。4. 实操过程做一个PDF表单自动读取器4.1 需求拆解与方案设计拿一个我实际做过的项目举例客户需要从大量PDF形式的发票中自动提取发票编号、开票日期和含税总金额然后录入管理系统。如果靠人工一张张看一天下来人累垮不说还容易出错。用PdfPig做自动化核心流程就是“打开PDF - 定位关键字段 - 提取文本 - 结构化输出”。先做了一个简单的字段定位策略优先用关键词定位因为这种票面字段的值都跟固定标签相邻例如“发票号码”后面就是编号。万一关键词匹配失败再用坐标区域兜底。两者都失败就标记为“待人工审核”避免错误数据直接进系统。4.2 实现一个简单字段提取流程下面这段代码处理一个固定版式的PDF用它提取指定字段。为了让思路清晰每一页遍历时先加一个文本层缓存再对目标字段做坐标或关键词匹配using UglyToad.PdfPig; using UglyToad.PdfPig.Content; using System.Text.RegularExpressions; string ExtractField(Page page, string label) { string pageText page.Text; // 方式一按标签文本匹配 int idx pageText.IndexOf(label, StringComparison.Ordinal); if (idx 0) { string segment pageText.Substring(idx label.Length); int newLineIdx segment.IndexOf(\n); if (newLineIdx 0) { segment segment.Substring(0, newLineIdx); } return segment.Trim(); } // 方式二按坐标区域匹配以“发票号码”为例假设区域固定 if (label 发票号码) { var letters page.Letters .Where(l l.StartX 430 l.StartX 560 l.StartY 650 l.StartY 690) .OrderBy(l l.StartX) .Select(l l.Value) .ToList(); return string.Concat(letters).Trim(); } return string.Empty; } using (PdfDocument document PdfDocument.Open(C:\demo\invoice.pdf)) { Page firstPage document.GetPage(1); Console.WriteLine($发票号码: {ExtractField(firstPage, 发票号码)}); Console.WriteLine($开票日期: {ExtractField(firstPage, 开票日期)}); }这个方案在实际中正确率能到85%左右。剩下15%的问题基本都出在两种情况一种是PDF是扫描图片根本没有文本层另一种是字段值跨行导致Index定位错位。前者必须交给OCR后者可以通过把页面文本按空白字符压缩后再匹配来解决。4.3 多页文档与批处理细节真实世界里的PDF很少只有一页发票经常连着好几张所以遍历多页和批量处理是所有自动化项目的必修课。PdfPig对多页的处理很简单document.GetPages()本身就是迭代器天然支持懒加载页面多也不会一次性把全部内容灌进内存。批量处理大量文件时我的一些经验是每个PDF文件单独用using块处理完立刻释放。不要在一个事务里处理几百个文件建议每处理完一批就输出中间结果哪怕挂了也不会全军覆没。用并行要注意PdfPig的对象不是线程安全的如果要做多线程加速应该按文件级别并行而不是在同一个文档的不同页并行。5. 常见问题与排查技巧实录5.1 中文乱码怎么办PDF里最容易出问题的就是中文。原因在字体映射很多中文PDF嵌入了字体子集但没有包含完整的Unicode映射表或者使用了私有编码区。PdfPig只能依靠PDF内部提供的ToUnicode CMap把字形ID映射成Unicode如果PDF生成工具没写这个映射表提取出来就是一堆乱码或空字符串。这个坑真不是PdfPig本身能解决的很多开源库遇到这种情况都会束手无策。我的排查顺序是先拿其他PDF阅读器验证一下同样文件是否正常复制文本。如果Adobe Reader也复制不出正常中文说明问题出在源文件只能靠OCR兜底。如果Adobe能复制而PdfPig不行可以试试最新版PdfPig或者检查字体子集是否完整。最简单粗暴的办法是先用渲染工具把PDF转成图片再走OCR管道。5.2 文本顺序错乱、多列排版怎么处理PDF没有“逻辑阅读顺序”这个概念它的页面内容流是按绘制指令顺序存的同一个段落可能被拆得七零八落。PdfPig默认按内容流顺序返回字母因此在单栏文档里表现很好一到双栏、三栏、新闻稿式的复杂排版提取结果就会东一句西一句。处理这个问题的经典思路就是自己动手排序。以字母的StartY为主键从下到上StartX为次键从左到右。如果版面明显是多栏可以先用聚类算法根据x坐标把页面拆成左右两个区域再分别排序。这里有一个判断标准如果两个字母的StartY差距在半个字高以内它们应该属于同一行这个时候先按照StartX排列否则按照StartY分块。5.3 扫描版PDF是图片PdfPig能提取吗直接回答不能。PdfPig擅长的是“从已有文本内容流里提取字符”如果PDF页面本身就是一张扫描图片内部只有图像对象没有文字层PdfPig能拿到的只有图像字节。需要配合OCR像Tesseract、PaddleOCR都是成熟方案。实操路径是先用PdfPig读取页面上的图像保存为PNG再把PNG传给OCR引擎。这种方式有一个好处OCR识别出的每个框还能从PDF坐标反推回纸张位置方便后续做高亮、标注或区域比对。如果扫描PDF连图像对象都很乱也可能是连续扫描件需要考虑用渲染库把PDF转成位图之后再走OCR这条路更稳。5.4 性能问题与大文件优化PDF动辄几百MB的情况并不少见特别是带大量扫描图片的文档。PdfPig本身做了流式设计但如果你在应用层不小心依然会把内存打爆。性能优化做好几件事就够了尽量用GetPage(int pageNumber)按需读取而不是遍历所有页面。如果只需要文档某一页可以直接打开后请求那一页然后立刻关闭。大批量任务要做限流休眠或分批避免IO尖峰。对页面数量特别大的文档可以先获取document.NumberOfPages然后按页码分段处理。在实际项目里我就靠这几条把一个批量解析任务从刚开始跑一分钟OOM优化成稳定处理百页文档。做技术选型时功能再强稳定性跟不上也白搭。写在最后的一点经验我在实际项目里用了PdfPig差不多一年最大的感受是它把“读PDF”这件脏活累活包装得很像现代C#该有的样子。不过也提醒后来者一句PDF格式最大的特点就是“谁生成谁有理”同一个字段在不同来源的PDF里坐标、字体、映射表都可能千差万别。做提取工具时别把方案写太死正则、坐标、关键词、页面布局多套策略互相补充再留一个“人工复核”的兜底出口才是稳定落地的关键。最后给你一个小技巧调试PdfPig时把letter.GlyphRectangle和文本值一起打印出来肉眼核对一遍坐标和内容的关系比盲改代码高效得多。这个库的GitHub仓库里还有大量examples有空翻一翻很多边界情况都有现成答案。本文还有配套的精品资源点击获取