企业官网建设流程全解析

简介：面向 Delphi 与 C++ Builder 开发者的 PDF 处理组件套件，基于开源 PDFium 渲染引擎，可在 Delphi/C++ Builder 5 至 10.3 及 Lazarus 2.0.6 环境中实现 PDF 查看、页面导航、文本提取与内容编辑等功能，适合需要在桌面应用中集成 PDF 能力的初中级开发者。压缩包共 1010 个文件，约 23.75MB，以 671 个 dcu 编译单元、35 个 pas 源码、31 个 dpk 包工程及 13 个 dfm 窗体文件为主体，另含 hpp、obj、res、dll 与 pdfium 相关运行库，并附带 Demo 工程与 chm 帮助文档，版本内含全部源代码，便于二次开发与调试。已有 623 人学习下载，可据此快速搭建 PDF 预览与编辑模块，参考源码理解组件封装方式与引擎调用流程。

1. 装 Delphi 10.3 的 PDF 组件：为什么我建议先锁死 5.4 这个版本

上周帮一个做档案管理系统的朋友收拾烂摊子，他的 Delphi 10.3 项目里 PDF 预览一滚动就闪退，查了两天才发现是组件版本和 IDE 对不上——他随手装了个更新的 PDFium 封装，结果 VCL 和 FMX 两套接口的编译单元互相打架。这类问题在 Winsoft PDFium 组件上特别常见，因为它的版本号是跟着 Delphi 走的，5.4 对应 5 到 10.3，装错一个大版本，轻则编译报缺单元，重则运行时直接 AV。这篇笔记记录的是 Winsoft_PDFium_Component_Suite_5.4_for_5-10.3_FULL_SOURCE 这套完整源码包从解压、编译、注册到验证的完整过程，适合正在用 Delphi 10.3 做 PDF 编辑、渲染、表单处理的开发者，尤其是那种拿到源码包却不知道从哪个 .dpk 开始下手的人。装之前先把环境对齐，比装完再救省事得多。

2. 环境对齐：Delphi 10.3 与 PDFium 5.4 的版本咬合关系

2.1 先确认 IDE 版本和编译目标

这套源码包的版本号里写着for_5-10.3，意思是它覆盖 Delphi 5 到 Delphi 10.3 这一段。落到 10.3 上，你要先确认自己装的是 10.3 Rio 的哪个 Update。打开 IDE，菜单 Help → About 看版本号，10.3 的 Release 1、2、3 在包编译上差异不大，但如果你混装了 10.3.3 的补丁又保留了旧版 DCU 路径，编译时会出现「Unit not found」和「DCU version mismatch」交替出现的情况。我一般会先做一件事：把项目里所有旧的Winsoft.PDFium*.dcu从搜索路径里清掉，只留源码目录。

确认完 IDE，还要确认目标平台。这套组件同时提供 VCL 和 FMX 两套封装，32 位和 64 位都有对应的包。你如果只做 Windows VCL 桌面程序，就只编译 VCL 那一套，别把 FMX 的包也装进去，否则 IDE 的组件面板里会出现两套同名控件，拖控件时很容易拖错，编译期看不出问题，运行期才发现用的是 FMX 版本，在 VCL 窗体上直接异常。

2.2 源码包的目录结构先摸清楚

解压Winsoft_PDFium_Component_Suite_5.4_for_5-10.3_FULL_SOURCE.rar之后，不要急着双击任何文件。先按下面这个顺序把目录过一遍，这一步花五分钟，后面能省两小时。

# 解压后进入根目录，先看整体结构（Windows 下用 dir /s /b 效果类似） find . -maxdepth 2 -type d | sort # 典型输出里你会看到这几类目录： # ./source/ 组件源码，.pas 文件都在这里 # ./packages/ 各 Delphi 版本对应的 .dpk 包工程 # ./packages/Delphi10_3/ 10.3 专用的包工程 # ./lib/ 预编译的 PDFium 动态库（pdfium.dll 等） # ./demos/ 示例工程，验证时用

关键点在于packages下面按 IDE 版本分了子目录，10.3 的包工程在Delphi10_3里，不要拿Delphi10_2的 .dpk 去编译，虽然有时能过，但条件编译符号对不上，生成的组件注册信息会缺方法。lib目录里的pdfium.dll是运行时依赖，位数必须和你的编译目标一致：编 32 位程序就用 32 位的 dll，编 64 位就用 64 位的，混用会在第一次调用渲染接口时抛「找不到入口点」。

2.3 版本对照表：别拿错包

这张表不是让你背，是让你在解压后第一眼就能定位到自己该进哪个目录。我见过最常见的翻车就是把 10.3 的源码包整个丢进 10.2 的 IDE 里编译，报了一屏的E2003 Undeclared identifier，其实是条件编译把新版本才有的方法给打开了。

3. 编译与注册：从 .dpk 到组件面板的完整落地

3.1 先编运行时包，再编设计时包

这套组件的包分两层：运行时包（Runtime）和设计时包（Design）。顺序不能反，设计时包依赖运行时包。在 10.3 里打开packages/Delphi10_3下的运行时包工程，先 Build 再 Install。Build 之前检查两件事：一是 Output 路径别指向 IDE 的默认 BPL 目录之外的地方，二是 Search Path 里要包含source目录。

// 运行时包工程里通常能看到这样的 requires 段，确认依赖项齐全 requires rtl, vcl, vclx; // contains 段列出所有编译单元，缺一个都会在 Install 时报缺单元 contains Winsoft.PDFium in '..\..\source\Winsoft.PDFium.pas', Winsoft.PDFium.Types in '..\..\source\Winsoft.PDFium.Types.pas', Winsoft.PDFium.Document in '..\..\source\Winsoft.PDFium.Document.pas';

这段requires和contains是包工程的核心。requires里列的是它依赖的 IDE 自带包，10.3 下vclx是设计时支持需要的，漏了会在注册组件时提示找不到基类。contains里每个.pas的路径是相对路径，如果你把源码包挪了位置，这里要同步改，否则 Build 直接报文件找不到。我一般不改路径，而是把整个源码包放在一个固定目录，比如D:\DevLibs\WinsoftPDFium54\，以后所有项目都从这个路径引用，避免每个项目各拷一份导致版本漂移。

3.2 设计时包的注册与组件面板检查

运行时包 Install 成功后，再打开设计时包工程，同样先 Build 再 Install。Install 的瞬间 IDE 会把组件注册进面板，正常情况下你会看到一个新的页签，里面是 PDF 文档、页面、渲染器这几个控件。如果 Install 报「Cannot load package」，八成是运行时包的 BPL 没在系统路径里，或者位数不匹配——32 位的 IDE 只能加载 32 位的设计时包。

# 编译完成后，确认 BPL 和 DCP 输出到了预期目录 # 在 IDE 的 Tools → Options → Environment Options → Delphi Options → Library 里 # 检查 BPL output 和 DCP output 路径，确保和包工程的 Output 设置一致 # 命令行下可以这样快速核对文件是否生成 dir /b "%PUBLIC%\Documents\Embarcadero\Studio\20.0\Bpl\*pdfium*"

上面这条命令查的是 10.3 默认的 BPL 输出目录（20.0 是 10.3 的内部版本号）。如果这里没有生成文件，说明包工程的 Output 路径被改到了别处，或者 Build 其实失败了但你没注意看消息窗口。设计时包装完后，新建一个空 VCL 窗体，从面板拖一个 PDF 控件上去，能拖上去且不报错，说明注册链路通了。这一步别省，很多人直接进项目编译，结果项目里uses了单元但控件类没注册，运行期创建窗体时抛「Class not registered」。

3.3 项目级引用：Search Path 和 DLL 部署

组件装好后，具体项目里还要配两样东西。第一是 Search Path，把source目录加进项目的编译搜索路径，这样uses Winsoft.PDFium.Document才能找到单元。第二是运行时 DLL 的部署，pdfium.dll必须和生成的 exe 放在同一目录，或者放在系统 PATH 能搜到的目录。我一般会在项目里建一个lib子目录放 dll，然后在 IDE 的 Debugger 选项里把工作目录设成 exe 输出目录，保证调试时也能找到 dll。

// 项目主单元里最小化的引用写法，验证组件是否可用 uses Winsoft.PDFium.Document, // 文档加载与页面管理 Winsoft.PDFium.Types; // 页面尺寸、渲染参数等类型定义 procedure TForm1.LoadPdf(const AFileName: string); var Doc: TPDFiumDocument; begin Doc := TPDFiumDocument.Create; try Doc.LoadFromFile(AFileName); // 加载本地 PDF Caption := IntToStr(Doc.PageCount); // 页数能读出来说明 dll 和组件都正常 finally Doc.Free; end; end;

这段代码的作用是做一个最小闭环验证：创建文档对象、加载文件、读页数。LoadFromFile内部会去调pdfium.dll的初始化接口，如果 dll 位数不对或路径不对，这里就会抛异常，异常信息通常是「无法加载 pdfium.dll」或「找不到指定的模块」。PageCount能正常返回，说明渲染引擎已经起来了，后面再做页面渲染、文本提取、表单填写才有意义。参数上注意LoadFromFile传的是完整路径，相对路径在调试时的工作目录下容易找不到文件，我习惯在调用前用ExpandFileName转一下。

4. 避坑与排查：五个装完才发现的坑

4.1 现象：编译通过，运行时报「找不到 pdfium.dll」

原因通常不是 dll 没拷，而是拷错了位数。32 位 exe 配了 64 位 dll，Windows 加载器会直接拒绝，报错信息又很含糊。解决方法是先用 Dependency Walker 或dumpbin /headers pdfium.dll看 dll 的机器类型，确认是 x86 还是 x64，再和项目的 Target Platform 对齐。我一般会在项目里放两个子目录lib\win32和lib\win64，编译后脚本按平台自动拷对应的 dll，避免手工拷错。

4.2 现象：组件面板里控件是灰的，拖不上窗体

原因是设计时包 Install 了但运行时包没先 Install，或者两个包的位数不一致。IDE 是 32 位的，设计时包也必须是 32 位，运行时包如果编成了 64 位，设计时包加载时会找不到依赖的 BPL。解决方法是回到包工程，把 Target Platform 统一设成 Win32，重新 Build 两个包再依次 Install。装完后重启 IDE 一次，让组件面板刷新。

4.3 现象：加载中文路径的 PDF 失败

原因是pdfium.dll的底层接口对 ANSI 路径的处理在部分版本上有差异，直接传 Unicode 字符串可能被截断。常见做法是先把文件路径转成短路径（8.3 格式）再传，或者把文件拷到纯英文目录下加载。我在项目里封装了一个SafePdfPath函数，内部用GetShortPathName转一道，中文路径的问题就基本不出现了。这个坑在 10.3 上尤其要注意，因为 10.3 默认字符串是 Unicode，而老版本组件内部有些地方还在用 ANSI 转换。

4.4 现象：渲染出来的页面模糊或比例不对

原因是渲染时的 DPI 和缩放参数没设对。PDFium 的渲染接口接受一个缩放因子，默认值在不同封装版本里不一样。5.4 这套源码里，渲染参数结构体有Scale和DPI两个字段，只设其中一个往往不够。我的做法是先把DPI设成屏幕 DPI（通常 96），再按需要乘缩放系数，两者配合才能得到清晰且尺寸正确的位图。如果只调Scale不调DPI，在高分屏上会明显发虚。

4.5 现象：卸载旧版组件后新项目编译报重复单元

原因是旧版的 DCU 还留在 IDE 的库路径里，和新源码的单元同名但版本不同。解决方法是打开 Tools → Options → Library，把旧版组件留下的路径全部删掉，再手动搜索硬盘上残留的Winsoft.PDFium*.dcu并删除。这一步做完后，最好把项目的__history和__recovery目录也清一下，避免 IDE 用缓存的旧单元去编译。我吃过一次亏，删了路径但没删 DCU，编译一直用的是旧单元，查了半天才发现。

5. 装完怎么验证：三步跑通再进项目

5.1 第一步：用自带 Demo 做冒烟测试

源码包的demos目录里通常有一个最简单的查看器工程，先别改任何代码，直接打开编译运行。这个 Demo 能正常打开一个 PDF 并翻页，说明组件、dll、包注册三条链路全通。如果 Demo 跑不起来，先别往自己项目里搬，回到第 3 章检查包和 dll。我习惯把 Demo 的编译输出目录和自己的工作目录分开，避免 Demo 的 dll 覆盖项目里的版本。

5.2 第二步：写一个十行的加载测试

Demo 通过后，新建一个空项目，只写第 3.3 节那段LoadFromFile加PageCount的代码，编译成 Release 版，拿到一台没装 Delphi 的干净机器上跑。这一步验证的是运行时依赖是否完整——很多人的项目在自己机器上好好的，一到客户机器就报缺 dll，就是因为调试时 dll 在 IDE 目录里，Release 包没带上。干净机器上能读出页数，才算真正部署成功。

5.3 第三步：渲染一页并保存成图片做比对

最后一步验证渲染链路。加载一个已知页数的 PDF，渲染第一页到TBitmap，保存成 PNG，用看图软件打开确认内容正确、方向正确、没有黑边。这一步能暴露 DPI 和缩放参数的问题，也能确认pdfium.dll的渲染模块没缺。我一般会准备一个两页的测试 PDF，第一页横版、第二页竖版，渲染两页都正常，才认为这套环境可以进正式项目。

这张表我一般贴在项目 wiki 首页，每次换机器或升级 IDE 都照着走一遍。从那以后我每次装这类带原生 dll 的组件，都强制先跑一遍 Demo 再碰业务代码，宁可多花二十分钟，也不在项目里一边写业务一边查环境。希望帮到你。

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