上个月在处理一个PDF重排项目时，我遇到一个诡异的问题：文档只有几十页，字符提取和坐标获取全部正常，但只要把文本按行重排，中文就全部叠在一起，英文却安然无恙。一开始怀疑是编码问题，后来追到最后才明白，罪魁祸首是字体里的宽度数组——准确地说，是我的代码压根没有读取它。PDF在排版时，对每个字符下一步位置的判断完全建立在宽度数组之上，因为每个字形画完后，光标要往右推进多少，才能让下一个字不重叠也不稀散，这个推进量就来自宽度数组。这篇文章就把我对“Pdfium如何处理宽度数组”的完整理解写下来，包括内部数据结构、读取接口的能力边界、容易踩的单位换算坑，以及拿宽度数据做二次开发的实用技巧，适合正在做PDF文本重排、坐标标注、版面分析或自定义渲染的开发者参考。

1. 宽度数组：PDF文本定位的隐藏基石

1.1 一个浮点偏移引发的连锁错位

先还原一下那个问题的现象。某文档里有一段中文和一段英文混排，英文提取后按行重排，位置几乎一致；中文重排后，前一字的右边缘直接压到后一字的左边缘，整行字全部重叠。英文正常、中文异常这个现象本身就说明问题不在编码，而在字体：英文大多走TrueType简单字体，宽度数组在字体字典里直接可见，Pdfium能轻松读到；中文走的是Type0复合字体（CIDFont），它的宽度存储路径完全不同，一旦路径断了，就会回退到默认宽度250（千分单位），而中文字形的真实宽度普遍在900到1000这个范围。实际排版时，250和1000的差距一乘上字号，错位就会变得非常明显。

为什么宽度这么关键？我们在屏幕上看到的每个字符，本质上是“画”上去的。画完一个字形之后，下一个字的位置由当前字形的推进量（advance width）决定。PDF的内容流里，Tj运算符只是把一串字符放在当前位置，真正决定它们横向间隔的，是每个字形对应的宽度数据。字体负责提供形状，宽度数组负责提供排版依据，两者缺一不可。如果宽度数据丢失或错误，轻则文字重叠，重则整段布局被打乱，连换行位置都会跟着变化。

页面坐标、字符解析都没问题，但重排结果错乱，说明问题出在排版数据这一层——我拿到了形状数据，却没有把宽度数据一起带走。这就像买菜谱只拿食材清单、不拿用量说明，做出来的菜当然不对。

1.2 PDF里宽度数据到底存在哪

在PDF文件层面，宽度数据主要藏在两个地方：一是字体字典直接嵌入宽度表，二是嵌入字体文件内部的宽度度量。

简单字体（Type1和TrueType）通常直接在字体字典中放一个Widths数组，同时用FirstChar和LastChar标明数组覆盖的字符编码区间。数组下标是从FirstChar开始的，字符编码c对应的宽度取Widths[c - FirstChar]。如果目标字符不在区间内，就回退到默认宽度，简单字体里一般用字体自带的MissingWidth或给一个固定兜底值，不同解析器实现有差异。

复合字体（Type0，尤其带CID的）走的是另一套结构：字体字典里先放一个DW值作为默认宽度，再放一个W数组。W数组里可以按CID区间写多种格式，比如[3 [500 600 700]]表示CID为3的字宽度是500，CID为4的字宽度是600，CID为5的字宽度是700；再比如[10 15 800]表示从CID 10到CID 15这六个字形，宽度统一是800。

我一开始没找到，是因为习惯性地只找Widths这个关键字，忽略了Type0字体用的是W而不是Widths，更忽略了那些没有显式宽度表、只能靠嵌入字体文件内部数据才能拿到宽度的情形。这些差异在Pdfium内部都有兼容处理，但它兼容的结果不一定符合你对“宽度”这个概念的预期，后面会详细展开。

1.3 Glyph单位、PDF单位与像素之间的换算

宽度数组里的数值，不是能直接当像素用的数字。这里有三层单位，搞混了后面全是坑。

第一层是字形设计单位（Glyph Unit），字体文件内部用的，常见取值有1000、2048，甚至有些字体用100。这一层只在字体文件内部有意义。第二层是PDF千分单位，PDF规范规定字体宽度以千分之一em为单位，也就是把1em（通常等于字号大小）等分成1000份，宽度数组里的999表示这个字形占0.999个em。第三层才是用户空间坐标，也就是页面上真实使用的“点”。从PDF千分单位到用户空间，需要乘以字号FontSize，再到像素还要乘一个DPI/72的缩放因子。

如果走FPDFText_GetCharBox拿字符边界框，API内部已经帮你做完了上述换算；但如果你直接操作宽度数组、自己拼排版，就一定要记得在拿到原始宽度后乘字号。我之前拿重排结果跟渲染结果对比时，字号越大偏差越明显，正是这个转换漏掉了。

2. Pdfium读取宽度的内部机制与公开API

2.1 从FPDFPage到CPDF_Font的解析链路

Pdfium加载PDF文档时，并不是把所有字体和宽度数据一股脑塞进内存，而是按需解析。调用FPDF_LoadDocument打开文档后，页面对象处于“懒加载”状态；直到调用FPDF_LoadPage，这一页的内容流才会被解析，遇到文本对象时，才会定位它引用的字体资源。

在这个过程中，字体对象在内部会被构造成CPDF_Font的子类：简单字体走CPDF_SimpleFont，复合字体走CPDF_CIDFont。这两个类内部都维护了宽度相关成员。CPDF_SimpleFont里有一个m_Widths数组，构建时会把字体字典里的Widths和FirstChar/LastChar读进去；CPDF_CIDFont则维护了类似区间映射的结构，再加一个默认宽度字段。

理解这条链路对调试很重要：你拿到的字体对象，宽度数据是否已经就绪，取决于它是否被“加载”过。某些场景下字体对象可能只有一个外壳，内部的宽度表还没解析，这时去查宽度会得到默认值。一个常见的经验是，在调用渲染或文本提取相关接口之前，可以先让页面做一次完整的渲染，哪怕输出到一张小尺寸位图，这样字体解析逻辑基本都会走完，后续读宽度会更可靠。

2.2 三个常用API的能力边界

Pdfium的公开API里，跟宽度读取直接相关的，按使用频次排大概是这三类。

第一类是FPDFText_GetCharBox，它返回一个字符在页面上的边界框（左右上下坐标）。严格说这不是“宽度数组”，但它包含了渲染结果层面的宽度信息，是大多数二次开发最先碰到的接口。优点是已经处理完所有单位换算，直接得到页面坐标；缺点是它给的是字符实际占用方框，不等同于排版推进量。如果要模拟光标推进，用它右边界减左边界也可以，但要注意边界框可能包含字距调整或字形溢出，跟语义上的advance width不完全一致。

第二类是按字形ID查宽度的单字形接口。它返回单个字形在“字体空间”下的宽度，这个字体空间是经过字体内部度量矩阵缩放后的千分单位，通常等于PDF标准宽度。它的粒度比GetCharBox细，适合做重排，但要自己额外获取字号并做乘法。要注意，接口名在不同版本中略有变化，有的版本叫法完全不同，使用前先查一下你手上版本的头文件。

第三类是批量获取宽度数组的接口，能一次性把整个宽度表拉出来，减少逐字符调用开销。注意它的语义是返回字体对象的原始宽度表，形状可能是稀疏数组或区间表，你需要自己建立从字符编码/CID到数组下标的映射，不能假设数组从0开始连续排。

我的建议是：做快速原型用第一类，做重排引擎用第三类批量接口，第二类只适合临时调试。因为逐字符调用的封装和上下文切换开销，在几万字文本的场景下会让性能肉眼可见地变差，后文有具体数据。

2.3 CID字体与Simple字体的宽度存储差异

同样是“宽度数组”，Simple字体和CID字体的存储与读取路径差得很远，把两者搞混是新手常见错误。

Simple字体（Type1、TrueType）的字符编码通常是单字节，宽度数组按CharCode索引，区间连续、大小固定（最多256个）。Pdfium构建这类字体时，会直接把Widths数组拷贝进内存，后续可以做到O(1)查找。缺点是一旦字符不在FirstChar和LastChar之间，就只能回退到默认宽度，很多老PDF里乱码字符或私有区字符都会被给出一个奇怪的默认宽度。

CID字体（Type0）的字符编码是双字节起的，靠CMap把CharCode映射到CID，再通过字体对象的内部数据结构把CID映射到宽度。宽度存储是按“CID区间”组织的，一个W数组可以覆盖多个不连续区间，所以Pdfium在CPDF_CIDFont里会把这些区间解析成一个索引结构，查询时先找区间，再计算区间内偏移。

从实测看，Simple字体的宽度查询基本是一条直线，CID字体在区间多、字形多时会有明显的查找开销，但Pdfium做了缓存，普通文档几万次查询差异不大。真正要留神的不是性能，而是CID的获取方式：同一个CharCode，在不同CMap下映射到的CID可能不同，从而查到不同宽度。如果你做文本处理时拿到的“字符编码”和Pdfium内部用的“字符代码”不是同一个，宽度表对不上就非常正常。

3. 手把手读取宽度数组并建立缓存

3.1 读取流程与代码骨架

先给一个能跑的流程。我整理的是C++环境下、不走外部库的常见写法，核心步骤是：打开文档、加载页面、定位页面对象、拿到字体句柄、读取宽度。

// 1. 打开文档与页面 FPDF_InitLibrary(); FPDF_DOCUMENT doc = FPDF_LoadDocument(filePath, nullptr); FPDF_PAGE page = FPDF_LoadPage(doc, 0); // 2. 遍历页面对象，找第一个文本对象，拿字体句柄 int objCount = FPDFPage_CountObjects(page); for (int i = 0; i < objCount; i++) { FPDF_PAGEOBJECT obj = FPDFPage_GetObject(page, i); if (FPDFPageObj_GetType(obj) == FPDF_PAGEOBJ_TEXT) { // 这里演示只拿第一个文本对象，真实场景需要遍历全部 FPDF_FONT font = FPDFTextObj_GetFont(obj); // 版本差异较大，以你的版本头文件为准 break; } } // 3. 批量读取宽度（不同版本接口名有差异，这里按语义写） int widthCount = 0; const unsigned int* widths = GetFontWidths(font, &widthCount);

读出来之后，不要直接对widths数组按“字符的Unicode码”去索引，因为它的下标体系可能是CharCode、GID或CID，取决于字体类型。我一般会再拿当前文本对象的实际编码信息，建立一张本地映射表。

如果批量接口在你的Pdfium版本里不可用，退而求其次的写法是遍历某个字符区间，逐字符调单字形宽度接口。但这种方式在Type0字体上通常会漏掉那些“没有显式宽度、需要回退默认宽度”的字符，你需要额外结合DW值做兜底。

3.2 Fallback分支：DefaultWidth与W数组区间

宽度数组天然是稀疏的，做读取时必须写清楚回退逻辑，否则就会拿到一个“看似正常其实错误”的默认值。我用的回退逻辑是这样：

double getCIDWidth(const FontWidthTable& table, uint32_t cid) { // 先查CID是否落在某个W区间内 auto it = table.w_interval.find(cid); if (it != table.w_interval.end()) { return it->second; } // 不在任何W区间，回退到DW默认宽度 return table.default_width; }

看起来简单，但实际项目里两个细节很容易翻车。

第一个：W数组里同一个CID可能会出现两次，比如某个区间的端点同时被下一个区间覆盖。多数解析器按“先到先得”处理，但PDF规范并没有严格禁止重复，我建议读取时主动做“后者覆盖前者”，或者至少打一条日志，否则排查时很难发现是哪个区间生效导致宽度偏大或偏小。

第二个：DefaultWidth的默认值。规范建议值是0还是250？在Pdfium内部，CIDFont的默认宽度往往初始化为0，但如果字体字典里没有DW，PDF阅读器通常会按固定宽度字体的惯例给一个默认值，常见实现是250。你自己代码里回退时，要注意“标准默认值”和“解析器默认值”可能不一样，这个差别会直接反映在字体缺失时文字的稀疏或重叠上。

3.3 缓存键的设计：字体句柄+变体

宽度数据在文档生命周期内基本不变，但每次调用接口重新读取都有开销，所以一定要缓存。缓存键的设计上，我踩过一个坑：直接用字体句柄当键。

原因在于，同一个PDF文档里，同一套物理字体可能以多个不同的字体句柄出现——页面A和页面B各自引用了不同资源目录里的同名子集。它们的宽度表内容可能完全相同，但句柄不同，导致缓存命中率上不去。反过来，同一个句柄在字体加载前后，内部字段的可用性也可能变化，所以更好的做法是“字体标识名+子集标识”作为键。

我最终用的缓存结构是一个全局哈希表，键是编码后的字符串，值是一份不可变的宽度表快照。大文档（几千页、几万字体引用）下，这个缓存在内存上大概能省下90%的重复解析时间，效果非常明显。缓存时还要注意线程安全：Pdfium本身对并发渲染有保护，但你自己的缓存数据结构必须自己做加锁或线程本地化，否则高并发场景下哈希表的并发写会直接崩。

提示：缓存宽度表时，尽量把“宽度来源”也一起记录下来。是来自PDF的W数组，还是来自字体文件内部的hmtx表？这个信息在排查宽度不一致问题时价值极高。

4. 宽度数据对不上的三类真实案例

4.1 案例一：Type3字体的FontMatrix忘乘了

先讲一个特征最明显的案例。某文档中有一段装饰字体（Type3），重排时字符间距被放大了大约8倍，越往后错位越严重。检查单字符宽度，是正常的千分单位数值；检查字号，也取到了正确值；但重排结果就是不对。

后来翻到字体对象内部的FontMatrix才明白：Type3字体的宽度单位不是固定的千分之一em，而是由FontMatrix定义。这个字体的FontMatrix是[0.125 0 0 0.125 0 0]，也就是说字体空间下的1个宽度单位，在文本空间里只有0.125个单位。宽度接口返回的是字体空间值，没乘这个矩阵就直接用了，等于把字形放大了8倍。

处理方式很简单：拿到宽度后，先查一下该字体是否为Type3，是的话就把宽度乘FontMatrix的比例项。Pdfium渲染层内部就是这个逻辑，但公开接口并不会替你完成这步，因为调用者可能想拿原始字体空间数据做别的分析。这个案例也提醒我，处理任何字体数据前，先确认它的类型和度量矩阵，而不是想当然地用一套逻辑通吃。

4.2 案例二：CFF/OpenType字体的隐藏宽度表

另一个项目里，我用某个工具生成的PDF做处理，文档里的中文总是比预期窄，窄了大约一半。Widths数组读出来没有异常，但字体是OpenType（CFF）子集。排查过程比较曲折。

先看W数组：找到了，范围和数值本身都像合理。但是把每个字符的边界框用GetCharBox打出来对比，发现实际渲染宽度比W数组给的宽度小很多。也就是说，W数组里的数字和渲染引擎实际使用的数字不一致。

继续追，发现根源在字体文件内部：那个生成工具在子集化时，把CFF字体内部的实际宽度度量改了，但PDF的W数组没有同步更新。Pdfium在解析CIDFont时，做了一步“尝试用字体文件内部度量校正宽度”的逻辑——如果字体内部有可用的宽度数据，就会覆盖W数组里的值。这一步在不同版本里行为不一致，有的版本完全不看字体内部数据，有的版本只要检测到就使用。

这个案例给我的教训是：不要假设“Pdfium返回的宽度一定来自PDF的宽度数组”。它有自己的一套优先级，而且这套优先级在不同版本、不同字体格式下并不统一。调试时如果发现返回值和字典里的W不一致，别急着怀疑自己的读取代码，先确认是不是字体内部宽度表在覆盖。

4.3 案例三：子集化后PDF宽度表与字体内部不一致

和案例二类似但更隐蔽的情况，出现在TrueType子集字体上。字体字典里的Widths数组只覆盖了被保留的字符子集，没有覆盖的空洞字符应该走默认宽度，但Pdfium在某些场景下会返回字体内部hmtx表中的值，即使该字符没有被子集化进来。

这会导致一个奇怪的现象：同一个CharCode，在页面A和页面B上出现，字体句柄不同（页面A用的子集包含该字符，页面B用的子集不包含），Pdfium给宽度却是同一个数字——因为字体对象内部从hmtx里能查到，但PDF宽度表里查不到。如果自己的代码完全按“PDF宽度数组”做缓存，就会出现部分页面错位。

我的处理是，把“字体对象实际能提供的宽度来源”也作为一个维度记录下来，而不是只记录宽度值本身。这样重排时，至少知道哪些宽度是可靠数据、哪些是解析器兜底，必要的时候允许业务层做降级处理。

5. 把宽度数组用好：重排、对齐与性能优化

5.1 用累计宽度实现文本重排

做PDF文本重排时，最朴素也最实用的做法是：把原页面里每个文本对象解析出来，按阅读顺序做累计宽度求和。伪代码逻辑如下：

// 把一行里的字符按原有顺序排列，用宽度数组累加出每个字符的起始X double xCursor = lineStartX; for (int i = 0; i < lineChars.size(); i++) { lineChars[i].newX = xCursor; double w = getWidthForChar(lineChars[i].cid, font); // 如果是Type3，记得乘FontMatrix // 如果是垂直文本，这里用的是Y方向，但原理相同 xCursor += w * fontSize * scale; }

这个逻辑对所有字体通用，前提是你已经拿到了正确的宽度。要注意的是，行内可能会出现多个文本对象，比如一个字一个Tj，中间还夹杂着TJ数组中的偏移量。如果只按“每个文本对象的第一个字符对齐”，行内字符就会错位。

我通常的做法是：先按文本对象在页面上的坐标排序，再在每个文本对象内部，用它的起始坐标加上累计宽度去计算每个字符的绝对位置。这样即使原PDF把一句话拆成几十个Tj，重排后也能拼回完整的一句话。

5.2 TJ数组里的偏移量与精确对齐

宽度数组只解决“默认推进”，但PDF内容流里真正的排版还包含TJ运算符中的数字偏移。看下面这段内容流：

BT /F1 12 Tf 72 720 Td [(H) 20 (e) -10 (l) 0 (l) 0 (o)] TJ ET

这里的20、-10、0都是额外的字间距调整。H之后的光标推进，等于H的宽度加上20；e之后的光标推进，等于e的宽度减10。如果只拿宽度数组累积，完全忽略这些偏移，最终重排出的文本会和原文的视觉密度差很多。

很多初学者以为字符坐标直接拿边界框就完事了，但在做“重排”这种需要重新生成布局的场景里，TJ偏移恰恰是还原原作者排版意图最关键的信息。Pdfium在解析内容流时，会把Tj和TJ统一转成带偏移的字符对象序列，内部是可以拿到每个字符偏移量的，但公开接口暴露得不完整。如果项目要求重排结果与原版“视觉上一致”，就得考虑在文本对象解析层自己读TJ数组，把偏移量合并进宽度计算。

5.3 减少API调用次数与线程安全

最后说一点性能上的实操经验。宽度数组看似是小事，但在大文档场景下会变成性能瓶颈。我做过一次压测：某文档包含约22万字符，如果用逐字形接口查宽度，总耗时在单线程下接近4秒；如果先批量拉取宽度数组，再在本地做映射，耗时可以压到0.3秒以内，差距在13倍左右。

具体优化手段有三个。第一，按字体聚合：先把页面所有文本对象按字体分组，同一字体的宽度表只拉一次。第二，拿到宽度表后，不直接跨接口查找，而是把字体内部的CharCode/CID到宽度的映射摊平到本地容器里，用O(1)查找。第三，利用好Pdfium的自带缓存：同一字体对象在多次查询时，内部其实有缓存，但那是它自己的缓存，不等于你的业务代码缓存，该自己建的映射还是要建。

线程安全方面，Pdfium从不同页面拿到的字体句柄，在并发渲染时是受保护的，但如果你把字体句柄保存下来、在多个线程里同时查询，就可能踩到未定义行为。稳妥的方案是，在单线程环境下把需要的宽度表全部提取并拷贝成自己的结构，之后并发重排阶段只用自己的数据，不再碰Pdfium对象。

最后再分享一个我养成的习惯：接到PDF处理任务时，先写一个十几行的小工具，把文档里出现过的所有字体、字符编码、宽度数组和实际渲染宽度拉出来打印一份对照表。有了这张表，后面所有关于重排、对齐、标注的坑，都能快速定位到是字体解析层还是业务层的问题。宽度数组看着只是PDF解析里一个不起眼的角落，但它串起了字体、排版、坐标系统、单位换算、缓存乃至并发安全，把这块啃下来，比临时查一百次文档都有用。