简介：这是一份已经编译完成的PDFium静态库分发包，面向需要在C++项目中集成PDF加载、渲染、打印与文本提取能力的开发者，尤其适合希望跳过源码编译、直接验证PDF处理流程的中高级技术人员。压缩包共45个文件，约2.92MB，以24个C/C++头文件、12个txt许可与说明文档、静态库及配套动态库文件为主，并包含CMake配置、版本与许可信息，便于快速接入现有工程。头文件覆盖文档解析、页面渲染、表单、注释、文本搜索、保存、签名、缩略图等常用接口，开发者可按需调用API实现具体功能。已有298人学习或下载，可作为搭建PDF查看器、文档管理工具或打印模块的起点；使用前仍需留意版本兼容性与不同平台下的链接适配。

1. 拿来就能链的 pdfium 静态库：跳过十几 G 的编译链，先把首页渲染出来

手头有个桌面端项目要加 PDF 预览，产品经理要的是"能翻页、能选中文字、能把批注画出来"，不是"能打开就行"。真去从源码编 pdfium，得先拉一套构建工具链，再下几个 G 的第三方依赖，编译机风扇转半小时起步，中间任何一步网络抖动都得重来。这份已经编译好的 pdfium 静态库解决的就是这一段：头文件加.lib/.a，直接进工程链接，把时间花在业务上。

它适合三类人：需要在 C/C++ 工程里嵌 PDF 渲染但不想维护构建链的；要在服务端批量出图、抽文字、填表单的；以及被"动态库版本对不上"折腾过、想用静态库把依赖一次性钉死在可执行文件里的。不适合指望开箱即用的人——预编译库最大的风险不是能不能链上，而是你不知道它是用什么参数编出来的，后面几章基本都在解决这件事。

2. 验库：符号表能告诉你这份静态库带没带 V8 和 XFA

预编译库最容易翻车的地方，是它在你的机器上"看起来能用"。链接通过、程序能跑、随便打开一个 PDF 也正常，于是你以为万事大吉，直到某天用户丢来一份带表单计算或者 XFA 结构的文件，页面一片空白，日志里什么都没有。这类问题在编译期就能提前判掉，靠的是符号表。

2.1 三平台库文件形态与工具链对齐

先搞清楚手里的文件到底是什么。同样叫pdfium.lib，可能是静态归档，也可能只是个导入库——后者必须配一个 DLL 才能跑，你把 DLL 漏在发布包里，用户机器上就是"缺少 xxx.dll"的启动失败。各平台常见形态如下：

我一般会先跑这三条命令，一分钟内把"这是不是真的静态库""架构对不对"两个问题按死：

# 1) 确认是静态归档而不是改名后的导入库 file libpdfium.a ar t libpdfium.a | head -n 5 ar t libpdfium.a | wc -l # 目标文件数量，通常几十到上百个 # 2) 看架构，多架构合并的库会列出多行 lipo -info libpdfium.a # macOS objdump -f libpdfium.a | head -n 20 # 3) 数一下导出的 FPDF_ 接口符号有多少 nm -g --defined-only libpdfium.a 2>/dev/null | grep -c " T FPDF_"

第一条命令是在排除"文件后缀骗人"的情况；ar t的条目数量太少（比如只有个位数）就要警惕，正常的静态归档会包含大量以.o结尾的目标文件。第三条统计的是T（已定义文本段）符号，正常情况下应该有几百个FPDF_*，如果只有几十个且前缀是__imp_，那就是导入库。

Windows 下的等价检查：

dumpbin /headers pdfium.lib | findstr /C:"machine" dumpbin /symbols pdfium.lib | findstr /C:"FPDF_InitLibrary" dumpbin /symbols pdfium.lib | findstr /C:"__imp_FPDF_InitLibrary"

machine那行会打印x64或ARM64，和你的目标平台不一致就直接换一份库，别试图用/MACHINE硬凑，运行时会在第一条指令崩。如果FPDF_InitLibrary只在__imp_形式下出现，说明你手里是导入库，发布时必须带上 DLL。

提示：.xcframework目录里每个切片都要单独用lipo -info看一遍，只验外层目录名等于没验。

2.2 用符号探测判断 V8 与 XFA 有没有编进去

预编译库通常有几个变体：带不带 JavaScript 引擎、带不带 XFA 支持、是完整版还是裁剪版。分发方给的说明经常只有一句"已开启全部特性"，信它不如信符号表。

# JavaScript 支持：存在 FXJS_ 系列符号说明 V8 编进去了 nm -g --defined-only libpdfium.a 2>/dev/null | grep -c "FXJS_" # XFA 支持：CXFA_ 系列符号是 XFA 解析器的实现 nm -g --defined-only libpdfium.a 2>/dev/null | grep -c "CXFA_" # 表单模块：FPDF_FFLDraw / FORM_ 系列是 AcroForm 与注释的绘制入口 nm -g --defined-only libpdfium.a 2>/dev/null | grep -c "FPDF_FFLDraw"

判读方式很直接：FXJS_计数为 0，说明这份库跑不了 AcroForm 里的 JS 计算和校验脚本，遇到带自动求和、自动填日期的表单，字段值永远不会更新；CXFA_计数为 0，说明 XFA 表单不支持，用户看到的是空白页而不是表单——这在保险、银行的申报类文档里非常常见。FPDF_FFLDraw缺失更隐蔽：页面能渲染，但所有可填字段和批注都不显示，看起来像"这份 PDF 就是空的"。

Windows 上把nm换成dumpbin：

dumpbin /symbols pdfium.lib | findstr /C:"FXJS_" | find /c /v "" dumpbin /symbols pdfium.lib | findstr /C:"CXFA_" | find /c /v ""

这一步的结论要写进项目文档，不能只存在脑子里。后面产品提"为什么这个表单不计算"，你翻文档就知道是库的能力边界，而不是代码写错了。

2.3 二十行代码跑通首页渲染

符号对得上不等于能用。字体、图片解码、坐标系统这些依赖都在运行时才暴露，最快的验证是把第一页渲染成一张图，肉眼看一下。

#include <stdio.h> #include <string.h> #include "fpdfview.h" int main(int argc, char** argv) { if (argc < 3) return 1; FPDF_LIBRARY_CONFIG cfg; memset(&cfg, 0, sizeof(cfg)); cfg.version = 2; /* 结构体版本必须显式给，否则按老布局解读会读飞 */ FPDF_InitLibraryWithConfig(&cfg); /* 路径按 UTF-8 传，Windows 下不要直接塞 GBK 窄字符串 */ FPDF_DOCUMENT doc = FPDF_LoadDocument(argv[1], NULL); if (!doc) { fprintf(stderr, "load failed, err=%lu\n", FPDF_GetLastError()); FPDF_DestroyLibrary(); return 2; } FPDF_PAGE page = FPDF_LoadPage(doc, 0); int w = (int)(FPDF_GetPageWidthF(page) * 2.0); /* 2 倍缩放，约 144 DPI */ int h = (int)(FPDF_GetPageHeightF(page) * 2.0); FPDF_BITMAP bmp = FPDFBitmap_Create(w, h, 0); /* 第三参数 0 = 不带 alpha */ FPDFBitmap_FillRect(bmp, 0, 0, w, h, 0xFFFFFFFF); /* 先铺白底，透明 PDF 不会出黑块 */ FPDF_RenderPageBitmap(bmp, page, 0, 0, w, h, 0, FPDF_ANNOT | FPDF_LCD_TEXT); const unsigned char* buf = (const unsigned char*)FPDFBitmap_GetBuffer(bmp); int stride = FPDFBitmap_GetStride(bmp); FILE* fp = fopen(argv[2], "wb"); fprintf(fp, "P6\n%d %d\n255\n", w, h); for (int y = 0; y < h; ++y) { for (int x = 0; x < w; ++x) { const unsigned char* p = buf + (size_t)y * stride + (size_t)x * 4; fputc(p[2], fp); fputc(p[1], fp); fputc(p[0], fp); /* BGRx -> RGB */ } } fclose(fp); FPDFBitmap_Destroy(bmp); FPDF_ClosePage(page); FPDF_CloseDocument(doc); FPDF_DestroyLibrary(); return 0; }

编译时注意一点：静态库内部是 C++ 实现，用gcc链接会缺一堆__cxa_*符号，直接上g++最省事。

g++ -std=c++17 render.c -I./include -L./lib -lpdfium -lpthread -ldl -lm -o render ./render sample.pdf out.ppm python3 -c " d=open('out.ppm','rb').read() print('bytes:', len(d), 'nonwhite:', sum(1 for b in d[15:] if b < 250))"

参数含义：FPDFBitmap_Create的第三参数决定通道数，0 是 BGRx 三通道加填充字节，1 才带 alpha；FPDF_RenderPageBitmap的start_x/start_y/size_x/size_y是目标位图上的绘制区域，不是页面裁剪框，想裁切得先把位图开小再算偏移；最后一个rotate参数只接受 0/90/180/270，传别的值行为未定义。

验证标准很简单：输出文件不是全白、体积正常（A4 正文页通常几十 KB 往上）、再拿一份带图片和一份带中文的 PDF 各跑一遍。中文那份如果全是方块，问题在字体回退，不在你代码——记下来，后面第 5 章会用到。

3. 接进工程：CMake 导入目标与运行库匹配的两处硬约束

验完库只是"能用"，接到工程里还要过两关：链接期和配置期。这两关不过，代码写得再对都是LNK2019和LNK2038。

3.1 用 IMPORTED 目标把 .lib/.a 挂进去

直接把库路径塞进target_link_libraries也能编过，但工程一大就会乱：头文件路径散在三个地方、Debug/Release 换了库忘了改、别的子模块又链一遍。规范做法是定义一个IMPORTED目标，把路径、头文件、系统依赖一次性封装。

# libpdfium.a 形态（Linux / macOS） add_library(pdfium::pdfium STATIC IMPORTED) set_target_properties(pdfium::pdfium PROPERTIES IMPORTED_LOCATION "${PDFIUM_ROOT}/lib/libpdfium.a" INTERFACE_INCLUDE_DIRECTORIES "${PDFIUM_ROOT}/include" ) # 静态库内部的依赖要在消费侧带出来，否则链接时才会报一堆 undefined target_link_libraries(pdfium::pdfium INTERFACE pthread dl m) # Windows 静态库形态 # add_library(pdfium::pdfium STATIC IMPORTED) # set_target_properties(pdfium::pdfium PROPERTIES # IMPORTED_LOCATION "${PDFIUM_ROOT}/lib/pdfium_static.lib" # INTERFACE_INCLUDE_DIRECTORIES "${PDFIUM_ROOT}/include") # target_link_libraries(pdfium::pdfium INTERFACE gdi32 user32 advapi32)

逻辑说明：IMPORTED_LOCATION是库文件真实路径，INTERFACE_INCLUDE_DIRECTORIES会随目标自动往下游传，业务代码只要target_link_libraries(app PRIVATE pdfium::pdfium)就够。INTERFACE那几行是静态库特有的坑——静态库不像动态库自带依赖描述，pthread、dl、m这些不写，链接器就会抱怨一堆undefined reference，而你翻遍 pdfium 头文件也找不到线索。

如果是 Windows 的 DLL + 导入库形态，得同时设两个属性：IMPORTED_IMPLIB指向.lib，IMPORTED_LOCATION指向.dll，再加一条add_custom_command在构建后把 DLL 拷到输出目录，否则开发机上能跑、装到别的机器就找不到模块。

注意：PDFIUM_ROOT建议用CACHE PATH变量或环境变量注入，别写成绝对路径提交进仓库，否则换台机器就编不过。

3.2 /MT 与 /MD 不一致时的链接灾难

这是预编译库最高频的翻车现场，报错长这样：

LNK2038: 检测到"RuntimeLibrary"的不匹配项: 值"MT_StaticRelease"不匹配值"MD_DynamicRelease"

原因是 pdfium 编出来时用的是/MD（动态 CRT），你的工程设了/MT（静态 CRT），两者的标准库对象模型不同。这时候别去改自己的工程配置硬凑，因为你不知道这份预编译库到底是/MD还是/MDd。

# 判断方式：把库的编译选项打出来（有 pdb 或 cmake 配置时最准） # 没有配置信息时，用符号探测间接判断： # _DebugHeap 相关符号存在 -> 很可能是 /MDd 调试版 # 找不到任何调试运行时引用 -> 大概率 /MD Release # 正确做法是让消费侧跟随库： set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreadedDLL") # Release # set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreadedDebugDLL") # Debug

参数说明：MultiThreadedDLL对应/MD，MultiThreaded对应/MT，带Debug的是调试版。这条设置要放在所有add_library/add_executable之前，CMake 3.15 之后才支持按目标设置，老版本只能全局改。

比链接错误更阴的是"链接通过了"。CRT 不一致时，内存在 A 模块分配、在 B 模块释放，堆句柄不同，表现是跑一段时间后随机崩在free里面，栈回溯全是系统库。血泪经验是：只要库不是你亲手编的，第一件事就是把运行库配置对齐，对不齐就换库，别指望"先跑跑看"。

Debug 配置还有一个独立雷区：_ITERATOR_DEBUG_LEVEL。预编译库是 Release 版，你在 Debug 下链接，报错信息会变成值"0"不匹配值"2"，很多人以为是运行库问题，改了半天/MT没用——其实是迭代器调试级别。解决办法只有两个：找库作者要 Debug 版，或者在 Debug 配置下也用 Release 运行库。

3.3 头文件包含顺序与 C++ 混编的边界

pdfium 的头文件本身已经带了extern "C"守卫，C++ 里直接#include "fpdfview.h"就行，不需要你手动包一层。真正会出问题的是顺序和宏污染。

// 推荐写法：pdfium 头文件优先，且放在 windows.h 之前 #include "fpdfview.h" #include "fpdf_text.h" #include "fpdf_formfill.h" #ifdef _WIN32 # define WIN32_LEAN_AND_MEAN # define NOMINMAX // 不加这句，std::min/max 会被宏吃掉 # include <windows.h> #endif // 跨 DLL/静态库边界不要传 STL 容器和 C++ 类， // 只传 FPDF_* 句柄和 POD 结构，避免 CRT 边界问题

说明：NOMINMAX是必须的，windows.h定义的min/max宏会让所有用到std::min的头文件编译失败，而 pdfium 头文件里恰好有模板代码。另外fpdf_fwlevent.h会引入一套键盘虚拟码常量，不需要处理表单输入事件的项目别包含它，容易和 GUI 框架的常量撞名。

路径编码这一条值得单独强调：FPDF_LoadDocument接的是 UTF-8 字节串，Windows 下用GetModuleFileNameW拿到的宽字符路径不能直接强转塞进去，必须先WideCharToMultiByte(CP_UTF8, ...)。我见过不止一次"中文目录下的 PDF 打不开"，最后都是这一行的问题。

4. 渲染、文字、表单：真正改变输出的那几个参数

库链上了，接下来是控制输出。pdfium 的接口数量不多，但同一份 PDF 用不同的参数组合渲出来，可能一张能直接 OCR、一张糊得没法看。

4.1 FPDF_RenderPageBitmap 的标志位怎么组合

标志位是位掩码，可以叠加，但叠错方向很常见。常用的几个：

组合策略：屏幕预览用FPDF_ANNOT | FPDF_LCD_TEXT；批量出图喂 OCR 用FPDF_ANNOT单独一个，LCD 的彩色边缘会干扰二值化；打印导出用FPDF_PRINTING | FPDF_ANNOT。服务端一次渲染上千页时加FPDF_RENDER_LIMITEDIMAGECACHE，内存曲线会平很多。

这里最容易误解的一点：FPDF_ANNOT只负责页面上的注释对象，AcroForm 的表单字段外观不归它管。表单要靠 4.4 节的FPDF_FFLDraw单独画一遍，两件事不能互相替代。

4.2 位图格式、stride 与 alpha 通道

位图这块有个坑几乎人人踩一次：输出了图，颜色整体偏蓝或者红蓝互换。

/* 方案 A：pdfium 自己分配，最省事 */ FPDF_BITMAP bmp = FPDFBitmap_Create(w, h, 0); /* 0=BGRx 三通道+填充, 1=BGRA */ /* 方案 B：复用自己已经开好的一块显存/内存，避免二次拷贝 */ unsigned char* canvas = (unsigned char*)malloc((size_t)stride * h); FPDF_BITMAP bmp2 = FPDFBitmap_CreateEx(w, h, FPDFBitmap_BGRA, canvas, stride); /* 需要 RGBA 顺序时，别手动逐像素换，加这个标志让 pdfium 直接输出 */ FPDF_RenderPageBitmap(bmp2, page, 0, 0, w, h, 0, FPDF_ANNOT | FPDF_REVERSE_BYTE_ORDER);

参数说明：FPDFBitmap_CreateEx的第四个参数是首行地址，第五个是 stride（行字节数）。stride 必须 ≥ 宽 × 每像素字节数，只在"渲染到大画布的某个子区域"时才需要大于。很多人以为 stride 可以随便给，结果图像呈斜向撕裂——因为 pdfium 是按 stride 换行写的，你后面按w*4读，每行都错位。

FPDFBitmap_GetStride一定要在读取前调用，不要假设它等于w*4。GUI 框架的纹理上传接口如果要求 4 字节对齐，而你开的是灰度图（每像素 1 字节），宽不是 4 的倍数时同样会错行。

坐标原点这块也别想当然：位图坐标系原点是左上角，而页面坐标系（后面文字提取用的）原点是左下角，两者 y 轴方向相反。做"点击高亮"这类交互时，转换公式是bitmap_y = (page_height - page_y) * scale，漏掉这个翻转，高亮框会跑到页面外。

4.3 文字提取与坐标换算

文字提取用到的是FPDF_TEXTPAGE，和渲染是两套对象，生命周期各自独立。

#include "fpdf_text.h" FPDF_TEXTPAGE tp = FPDFText_LoadPage(page); int n = FPDFText_CountChars(tp); /* 含换行与空格，不含结尾 0 */ /* 一次性取全文，UTF-16LE，缓冲长度要 n+1 */ unsigned short* buf = (unsigned short*)malloc(sizeof(unsigned short) * (n + 1)); int got = FPDFText_GetText(tp, 0, n, buf); /* 返回实际写入的字符数，含结尾 0 */ /* 取单个字符的包围盒，单位是页面坐标（point），原点左下 */ double l, r, b, t; for (int i = 0; i < n; ++i) { if (FPDFText_GetCharBox(tp, i, &l, &r, &b, &t)) { /* 转到位图坐标：x 直接缩放，y 要翻转 */ double sx = l * scale, sy = (page_h - t) * scale; double sw = (r - l) * scale, sh = (t - b) * scale; } } FPDFText_ClosePage(tp);

逻辑说明：FPDFText_CountChars统计的是页内字符总数，FPDFText_GetText一次取完比分批取快得多，返回的 UTF-16 需要自己转 UTF-8（Windows 上用WideCharToMultiByte(CP_UTF8, ...)，Linux 上用std::wstring_convert或手写）。FPDFText_GetCharBox返回的是页面坐标，单位是 point（1/72 英寸），所以缩放系数要用目标像素宽 / FPDF_GetPageWidthF。

参数含义里有个细节：FPDFText_GetText的第三个参数是"要取多少个字符"，传n表示从 0 取到末尾，传-1也等价，但有些老版本对负数处理不一致

本文还有配套的精品资源，点击获取