企业官网建设流程全解析

简介：PoDoFo 0.9.4 的 Visual Studio 2010 工程，专为需要在 Visual Studio 2010 环境下编译使用 PoDoFo C++ 类库的开发者准备。官方推荐的 CMake 生成解决方案流程常常失败，该资源已手工搭建好核心代码工程，直接生成动态库与静态库。压缩包共三百七十个文件，以二百六十三个头文件和九十三个 C++ 源文件为主体，另含 freetype2 与 zlib 的预编译静态库和 VS 项目文件，整体体积仅二点四三兆字节，未包含 Samples 等示例代码。已在 Windows 10 六十四位系统、Visual Studio 2010 下验证编译通过，核心源码覆盖 PDF 文档读取、页面解析、字体嵌入、图像处理、加密解密等常用模块。资源内头文件与库目录集中放置，便于自行调整链接路径；源码保留原始注释，适合有一定 C++ 基础的开发者阅读和改造。无论快速集成 PDF 能力，还是深入研究 PoDoFo 内部实现，这套工程都能减少环境配置与依赖折腾，可直接作为二次开发基础。已有七百四十八人学习下载。 在 Windows 下编译开源 C++ 库是个长期存在的折磨，尤其是当你手里只有一台装着 VS2010 的老机器，或者一个只支持 VS2010 的遗留工程时。我这次折腾的是 podofo 0.9.4，一个老牌的 PDF 处理库，前后花了两天时间，中间栽了无数跟头，最后总算把完整的 VS2010 工程跑通，库也编出来了。这篇文章就把完整过程记录下来，包括 CMake 怎么配、依赖库怎么处理、编完怎么集成到自己工程里，以及我踩过的那些文档里根本不会写的坑。

先说清楚 podofo 是什么，免得有人误入。它是一个开源的 PDF 库，支持读取、修改、写入 PDF 文件，也能提取文本、解析表单、处理加密文档。0.9.4 是 2013 年前后的版本，虽然不算新，但 API 相对稳定，很多老项目用的就是这一版。这次需要的场景是给一个历史遗留的 MFC 程序增加 PDF 生成功能，编译环境锁定 VS2010，所以我才专门把 podofo 0.9.4 的 VS2010 工程完整搭出来。如果你也在做类似的事，或者说你就想让一个老库在旧工具链下老老实实工作，这篇文章应该能帮你省掉不少试错时间。

1. 先搞清楚 podofo 0.9.4 的编译难点在哪里

1.1 这个库自身的问题

podofo 0.9.4 这套代码本身不复杂，但它有个老派开源项目常见的毛病：编译依赖特别多。官方源码包里有CMakeLists.txt，理论上可以生成任意 Visual Studio 版本对应的工程，但前提是你得把依赖库全部准备齐全，尤其是：

• libpng：PNG 图像编解码
• libjpeg：JPEG 图像编解码
• zlib：压缩解压，几乎绕不开
• freetype：字体渲染
• OpenSSL：处理 PDF 加密和签名（可选，但编译时默认会找）
• libtiff：TIFF 图像支持（可选，但默认也会找）

这就引出第一个问题：podofo 的 CMake 脚本并不会帮你自动下载这些依赖项。你必须先把它们各自编译好，再在 CMake 里指定路径。而这些依赖库本身也有版本兼容问题，跟 VS2010 搭配起来就是地狱难度。

1.2 为什么偏偏要在 VS2010 上弄

有人可能会问，为什么不升级到新版的 Visual Studio，省得这么折腾？原因很现实：有些项目因为用了老的第三方控件、老的驱动 SDK、或者客户的环境锁定，只能锁定 VS2010 编译。再加上 VS2010 对 C++ 标准的支持停留在远古水平，拿新版库代码硬编会碰到大量语法错误，与其改库代码，不如就把 podofo 0.9.4 这个同时代的版本编出来。

VS2010 还有一个操作上的细节：它用的编译器是 MSVC 16.0（对应 VC10），运行时是 v100。之后版本的库如果用了新的 C++11 特性，在 VS2010 上基本都会翻车。所以找库版本时要认准 0.9.4 这种和 VS2010 同年代的版本，别拿最新的 0.9.8 去试，纯属浪费时间。

1.3 编译产物与使用场景

最终编好的 podofo 会生成两个关键产物：一个是静态库或 DLL（取决于你 CMake 怎么配），另一个是一堆头文件。对于 VS2010 工程而言，最省心的用法是把 podofo 编成静态库，然后在你自己的程序里把头文件路径和库文件路径加进工程配置。静态库的好处是发布时不用带一堆 DLL，对老系统部署非常友好。

当然，如果你有多种程序都要用 podofo，那编成 DLL 可以减少编译时间。我个人更推荐静态库，原因是 podofo 的依赖库本身就多，如果每个依赖都弄成 DLL，发布时拷 DLL 都能把你逼疯。

2. 构建前的准备：工具链、依赖与目录规划

2.1 工具链准备：VS2010 SP1 必须装

第一个容易忽略的大坑是：VS2010 必须要打 SP1，否则 CMake 生成工程或者编译过程中会出现各种莫名奇妙的错误。尤其是如果你在 Win10 或 Win11 上装 VS2010，不打 SP1 的话，连安装可能都别别扭扭。SP1 的离线安装包以前微软官方有下载，现在不在官方渠道了，但网上能找到。装好之后建议顺手验证一下编译器版本，在命令行里执行：

cl

如果能显示出 Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 16.00.30319.01，就说明环境正常。如果你看到的是 16.00.xxxxx 以下的老版本，多半是没打 SP1。

另外注意，CMake 版本不要用太新的。CMake 4.x 已经明确放弃 VS2010 支持，CMake 3.20 以上对 VS2010 的生成器支持也有退化迹象，我实测最稳的是 CMake 3.18.x。别看 CMake 只是个生成工具，版本不对，生成的 .sln 文件打开后会有各种兼容提示，工程属性页里有些选项还会错乱。

2.2 准备第三方依赖库

这是整个过程中最耗时的一步。podofo 0.9.4 的 CMake 脚本会查找 zlib、libpng、libjpeg、freetype、OpenSSL、libtiff。你不可能指望它自己找到，所以最好手动编译，或者直接找编译好的 Windows 版本库。

我当时的做法是：

• zlib：直接拿 zlib 1.2.11 源码包里的 VS2010 工程，打开contrib/vstudio/vc10/zlibvc.sln，分别编译 Win32 的 Debug 和 Release 版本。
• libpng：需要先有 zlib。下载 libpng 1.6.37，里面自带 CMakeLists 和 vstudio 工程，用 CMake 生成 VS2010 工程后再编译。注意 libpng 的 CMake 配置里要手动指定 ZLIB_ROOT。
• libjpeg：用 jpeg-9b 版本，里面的结构很简单，直接拿它的 VS2010 工程文件编就行。如果找不到工程文件，也可以手动创建一个空工程把源码加进去，编译成静态库。
• freetype：老版本 freetype 2.5.5 自带builds/windows/vc2010工程目录，直接打开编译即可。新版 freetype 目录结构变化很大，没必要用新版。
• OpenSSL：这个最恶心。OpenSSL 1.0.2 系列支持 VC2010，但编译需要 Perl，还需要 NASM。如果不需要加密 PDF，可以在 CMake 配置时直接关掉PODOFO_HAVE_OPENSSL，别跟它死磕。
• libtiff：不是必要项，如果不用 TIFF 图片处理，同样建议关掉。

这里有一个关键技巧：所有依赖库最好统一编译成静态库，而且运行库设置要和 podofo 工程保持一致。如果你在用/MT或/MTd（静态运行库），那 podofo 和所有依赖库也都得用/MT或/MTd，混着用一定链接报错。我因为偷懒，zlib 编的是/MD，后来 link 时一堆libcmt.lib和msvcrt.lib冲突，整整折腾半天。

2.3 目录规划与命名约定

建议建一个规范的第三方库目录，方便 CMake 查找。我的目录结构是这样的：

D:\thirdparty ├── zlib │ ├── include │ └── lib ├── libpng │ ├── include │ └── lib ├── libjpeg │ ├── include │ └── lib └── freetype ├── include └── lib

每个库的 lib 目录里统一把文件命名为libpng.lib、libjpeg.lib、zlib.lib、freetype.lib，Debug 版本可以加个_d后缀，别让 CMake 傻傻分不清。这个步骤看着简单，实际很关键：CMake 默认找库时是按固定名字找的，你文件名起得乱七八糟，后面全是在跟 CMake 报错斗智斗勇。

3. 用 CMake 生成 VS2010 工程的核心步骤

3.1 第一次配置 CMake 的参数

podofo 源码解压后，进入根目录，用 Cmake GUI 或者命令行配置。先说说最省心的 Cmake GUI 操作路径：

1. 打开 CMake GUI，源码目录选 podofo 0.9.4 根目录
2. 构建目录单独建一个build-vc10文件夹，别跟源码混在一起，否则后面想删掉重新生成很麻烦
3. 点击 Configure，生成器选Visual Studio 10 2010
4. 如果选了 Win64，就选Visual Studio 10 2010 Win64，这取决于你要编 32 位还是 64 位。一般老项目都是 32 位，选前者就行
5. 首次配置必然报错，最重要的是看红色报错项，逐个解决

3.2 解决 CMake 找不到依赖库的报错

第一次 Configure 后，CMake 会列出一堆未找到的变量，常见的有：

• ZLIB_INCLUDE_DIR、ZLIB_LIBRARY
• PNG_PNG_INCLUDE_DIR、PNG_LIBRARY
• JPEG_INCLUDE_DIR、JPEG_LIBRARY
• FREETYPE_INCLUDE_DIR_FT2BUILD、FREETYPE_LIBRARY
• OPENSSL_INCLUDE_DIR、OPENSSL_LIBRARIES
• TIFF_INCLUDE_DIR、TIFF_LIBRARY

这些变量必须手动指定路径。比如设置ZLIB_INCLUDE_DIR为D:/thirdparty/zlib/include，ZLIB_LIBRARY为D:/thirdparty/zlib/lib/zlib.lib。遇到OPENSSL和TIFF找不到时，如果不需要这些功能，直接去 CMake 的变量列表里找到对应的PODOFO_HAVE_OPENSSL和PODOFO_HAVE_TIFF之类的选项，把勾去掉或者设为空。有些细分变量叫PODOFO_USE_STATIC_OPENSSL，不用管，只要主开关关了就行。

如果你第一次 Configure 后界面是白板，说明 CMake 缓存还没生成，点 Configure 后它会变成红色错误项，正常。根据我的经验，至少要把所有红色项清零、列表底部没有明显错误信息，点 Generate 才能生成 VS2010 工程文件。

3.3 编译过程需要多长时间的预期

点 Generate 之后，会在构建目录里生成podofo.sln。用 VS2010 打开它，在解决方案资源管理器里找到podofo项目，直接右键生成。首次编译时间取决于你机器性能，一般吃 5 到 15 分钟不等。如果你之前依赖库编译时踩了坑，这里会爆出一堆 LNK 错误，先不要慌，逐个看是哪个依赖没找对。

我在这一步遇到的典型问题是 freetype 的头文件路径找不到。因为 freetype 头文件有两种组织方式，一种有ft2build.h在外层，一种没有。CMake 查FREETYPE_INCLUDE_DIR_FT2BUILD时，要用包含ft2build.h的那个目录，而不是 freetype 的根目录。这个坑文档里写得不清不楚，我把两个变量都指到同一层，结果编译时爆了二十多个ft2build.h: No such file or directory才意识到问题。

3.4 确认编译产物是否正常

编译成功后，到build-vc10/src/Debug或Release目录下查看，会有podofo.lib或podofo.dll。如果你编的是静态库，大概率只有.lib文件，也可能附带一些.exp和.pdb。这时候可以把一个简单的 PDF 文件丢给 podofo 自带的测试工具试一下，看看能否正常读取。

当然，podofo 的很多工具函数本身编译出来也不一定会暴露出来，最稳妥的验证方式是自己写个几行代码调用。但在这个阶段，只要看到podofo.lib生成成功，基本上就说明库本身没问题，可以进入集成阶段了。

4. 编译一个最小测试程序验证库能不能用

4.1 配置包含目录、库目录与附加依赖项

这一步很容易翻车。VS2010 的工程属性配置里，要依次设置：

• C/C++ -> 常规 -> 附加包含目录：把 podofo 的源码根目录加进去。因为 podofo 的头文件经常是#include <podofo/podofo.h>，所以源码根目录必须要在包含路径里
• 链接器 -> 常规 -> 附加库目录：把编译好的podofo.lib所在目录加进去
• 链接器 -> 输入 -> 附加依赖项：手动敲入podofo.lib，或者用生成后的 lib 文件名

同时，还要把 zlib、libpng、libjpeg、freetype 这些依赖库的.lib一并加进附加依赖项。比如：

podofo.lib zlib.lib libpng.lib libjpeg.lib freetype.lib

如果你链接时提示某个函数找不到，先检查是不是漏了哪个依赖库。再提示一次，所有库的/MT/MD设置要一致，否则链接时就会有LNK2038这类"运行库不匹配"的错误，而且是在工程里看不出来的那种隐藏问题。

4.2 写一个最基础的程序来验证链接

为了验证库能不能用，我写了一个非常简单的程序：创建一个空白 PDF，往里面加一页文本。核心代码就这几行：

#include <podofo/podofo.h> #include <iostream> using namespace PoDoFo; int main() { PdfStreamedDocument document("test.pdf"); PdfPage* pPage = document.CreatePage(PdfPage::CreateStandardPageSize(PdfPageSizeType::PdfPageSize_A4)); PdfPainter painter; painter.SetPage(pPage); painter.DrawText(100, 100, "Hello PoDoFo on VS2010"); painter.FinishDrawing(); document.Close(); std::cout << "PDF created successfully!" << std::endl; return 0; }

注意，PdfPageSizeType::PdfPageSize_A4这个枚举在 0.9.4 里是有的，但不同版本的 podofo 可能 API 有变化。如果你用的是 0.9.4，这段代码基本可以编译通过。编译后运行，如果生成了test.pdf，那就是真的成功了。

4.3 为什么不建议用 Debug 版本跑生产

我测试时习惯先用 Debug 配置跑通，但实际发布时会切成 Release。podofo 0.9.4 的 Debug 版本在 VS2010 下跟 Release 版本行为差异很大，主要是因为调试迭代器和 STL 检查，在某些 PDF 操作中会影响性能。所以最后集成到正式工程里，务必用 Release 版本的 podofo 库，并且在工程配置里保持运行库一致，否则运行时会崩得莫名其妙。

另外，如果你要发布程序给别人使用，还要注意 podofo 是否依赖其他 DLL。如果是静态库就不存在这个问题，但如果你编的是 DLL，必须把 podofo.dll 和依赖库的 DLL 一起拷贝到可执行文件目录。最保险的方法是用 Dependencies 或者 Process Explorer 打开生成的 exe 看一眼加载了哪些 DLL，别等别人报错"找不到 dll"才追悔莫及。

5. 常见问题与排查技巧实录

5.1 LNK2038：运行库不匹配

这个问题我在前面反复提过，因为真的太常见了。典型报错是：

LNK2038: mismatch detected for 'RuntimeLibrary': value 'MT_StaticRelease' doesn't match value 'MD_DynamicRelease'

一般原因就是 podofo 工程里设置的是多线程静态库/MT，但你自己的工程用的是动态库/MD。解决办法是进入项目属性，把运行库设置成一致。如果你依赖库也多，那所有库都得统一。最简单的做法是全部用/MT、/MTd，这样发布时不用带 VC 运行库，在旧系统上部署也方便。

5.2 头文件路径找不到podofo/podofo.h

这个基本都是包含目录没设置对。podofo 的头文件组织方式是源码根目录下有个src目录，里面podofo.h被藏在多层路径下。最稳妥的方法是把 podofo 源码的src目录和根目录都加到附加包含目录里，然后代码里统一用：

#include <podofo/podofo.h>

如果你直接写#include "podofo.h"，编译时会找不到，因为头文件并不在工程文件的同目录下。

5.3 编译时爆大量 C4996 或 C4244 警告

VS2010 对 C4996（使用了不安全的 C 函数）非常敏感，podofo 0.9.4 又是 2013 年的代码，里面用了一堆strcpy、sprintf这类函数。编译时会产生大量警告，不影响功能，但看着糟心。可以在工程属性里把警告级别调低，或者直接禁用 C4996：

C/C++ -> 高级 -> 禁用特定警告，填入 4996

如果想保持代码整洁，也可以定义_CRT_SECURE_NO_WARNINGS宏。这个方法对任何老库都有效。

5.4 Unicode 字符集 vs 多字节字符集

VS2010 工程创建时默认字符集是多字节，但很多老代码写的是char*，podofo 内部处理文件名也是面向窄字符的。如果你的工程设置成了 Unicode 字符集，调用 podofo 的打开文件 API 时可能碰到类型不匹配的编译错误，比如PdfStreamedDocument构造函数要求const char*，而你传的是CString，那就得手动转换：

CString strPath = _T("test.pdf"); CT2A asciiPath(strPath); PdfStreamedDocument doc(asciiPath);

这个坑在 MFC 程序里很常见，如果你新写的是纯控制台程序就不用操心。

5.5 编译 podofo 时报错找不到pthread.h

有些版本的 podofo 在 Windows 下会去找 pthread 头文件，但 0.9.4 默认是不依赖 pthread 的。如果遇到这种错误，八成是 CMake 误开了什么选项，或者在 FindThreads 那里把 pthread 选中了。去 CMake 配置里把跟 thread 相关的选项都关掉，再重新生成工程。如果还不行，检查你的依赖库里是否有某个库（比如 freetype 的某些版本）内部依赖 pthread。Windows 下没有 pthread.h，碰上了可以直接删掉工程里的 pthread 引用，或者使用 Windows 自带的CreateThread替代，但这一步比较麻烦。

5.6 重新生成工程时 CMakeCache 残留

改 CMake 配置改到烦躁的时候，我建议直接把整个build-vc10目录删掉重建，不要尝试在旧缓存上反复横跳。CMakeCache.txt 里的残留变量会让新配置受到干扰，特别是路径变了之后，它还会固执地寻找旧路径。简单粗暴删除构建目录，重新 Configure 和 Generate，常常能解决很多奇怪问题。

6. 一些个人沉淀下来的编译经验

这次折腾 podofo 0.9.4 和 VS2010 让我重新认识到一个问题：老库在旧工具链下编译并不是没有章法，关键是依赖关系的梳理。很多人一上来就想先把 podofo 直接编出来，结果发现缺这个缺那个，一下子就被劝退了。如果先花时间把依赖库全部准备好、统一运行库模式、规划好目录，后面 CMake 配置就是单纯指路径的事情。

另外想特别提一点，编译开源库时不要迷信官网给的 README。很多时候那些文档对应的是 Linux 环境，在 Windows 上跑完全不是一回事。我建议直接把 CMake 当成主心骨，只要把 CMake 的变量逐个搞清楚，编译路径就基本掌控在自己手里。VS2010 老归老，它毕竟是微软官方的编译器，对老版本库的兼容性反而比新版 Visual Studio 好得多，你根本不用担心像 VS2019 那样因为标准支持过度而编译不过。

最后再分享一个小技巧：如果你编译的不是库而是最终程序，一定要在工程属性里把"链接器 -> 生成调试信息"打开，并且把/INCREMENTAL选项正确设置。VS2010 的链接器很脆，Debug 编译失败后有时会留下一个坏的 .ilk 文件导致反复报错，删掉Debug目录里的.ilk文件再重新生成就能恢复。这个小坑我第一次遇到时排查了大半天，希望你能绕过去。

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