企业官网建设流程全解析

上周远程帮人看一个 Delphi 项目，现象挺典型：窗体设计器一打开就提示找不到单元，组件面板上那几个控件全是灰的，点一下弹一串英文异常。对方说组件是昨天刚装的，“安装程序跑完了，提示安装成功”。我让他打开 IDE 的库路径设置一看，路径确实加了一条，但加到了 Win32 下，而他正在编 64 位版本。改成对应平台之后，问题当场消失。

这类事情我这些年见得太多了。Delphi 第三方组件的安装，表面上就是“下一步、下一步、完成”，实际上从组件交付形态、IDE 的查找规则、包工程的依赖声明，到卸载清理和团队协作，每一环都有能让人卡半天的地方。这篇文章想干的事情很明确：把组件安装这件事从“点按钮”拆到“搞懂它在干什么”，让你拿到任何一个第三方组件包，不管是源码、预编译包还是散装单元，都能自己判断该走哪条路、出问题该往哪儿查。适合刚接手老项目的新人，也适合用惯了某个版本、换版本就抓瞎的老手。

1. 先分清手上拿的是什么东西，再谈安装

很多人卡住的第一步，不是操作错了，而是压根没搞清楚自己下载的是哪种形态的组件。Delphi 的组件生态里，同一个库可能同时提供三四种交付方式，每一种的安装动作完全不同。用错方法，比如拿预编译包去套源码安装的流程，或者反过来，后面所有的报错都会变得莫名其妙。

1.1 源码包、预编译包、散装单元：三条互不相通的路

源码包是最常见也最推荐的一种，特征目录里躺着一个.dpk文件，旁边是一堆.pas。.dpk本质是一个特殊的工程文件，作用是把若干单元打包编译成一个包文件。走这条路，你需要自己在 IDE 里打开这个工程、检查依赖、编译、安装，好处是它跟着你的编译器版本走，换 IDE 版本重新编一次就行。

预编译包给的是编译好的产物，通常包括.bpl（运行时和设计期都要用）、.dcp（链接期需要的声明文件）、一堆.dcu（编译单元）。这种东西拿来即用，但它和你当前的编译器版本是强绑定的，版本对不上直接罢工。

散装单元最原始，只有.pas文件，没有.dpk。这种情况你得自己决定：是建一个包工程把它们打进去，还是干脆不建包、把源码目录加到库路径里，在项目里直接 use。前者适合要在组件面板上拖拽使用的可视化控件，后者适合纯工具类、没有设计期注册代码的单元。

还有一种容易被忽略的安装器形态，也就是一个 exe，双击跑完提示成功。它内部做的事无非是解压文件、往注册表或配置里写库路径、注册包。听起来省事，但它猜的 IDE 安装位置、写的路径、用的权限，任一环节出岔子都会导致“看起来装好了其实没装好”。

1.2 “提示安装成功”为什么经常不等于装好了

安装器最容易在三个地方翻车。第一是权限，如果组件被装进了系统盘的程序目录，后续 IDE 写配置或者包自己生成缓存文件时可能没权限，表现出来的现象是编译时报一堆“无法写入”或者干脆卡死。第二是多版本共存，一台机器上装着两三个 Delphi 版本是常态，安装器经常只往它认为“最新”的那个版本写路径，另一个版本就找不到东西。第三是路径本身有坑，带空格、带中文的目录在老版本编译器上出问题的概率不低。

提示：装完之后别急着相信提示框。真正验证的标准只有一条，新建一个空项目，从组件面板拖一个该库的控件到窗体上，然后按一次编译并运行。这一步过了，才算装对了。

2. IDE 到底靠什么找到你的组件

要把安装这件事做扎实，得先明白 IDE 和编译器是按什么规则找文件的。这一层搞清楚，后面百分之八十的“找不到单元”都能自己定位，不用到处问人。

2.1 库路径和浏览路径不是一回事

IDE 的路径设置里有两个概念经常被混为一谈。**库路径（Library Path）**是编译器找.dcu和.pas的地方，它直接参与编译，路径没加对，编译必然报找不到单元。**浏览路径（Browsing Path）**只影响代码编辑器的跳转，你按住 Ctrl 点一个类型名能跳过去看源码，靠的是它，但它对编译结果没有任何影响。

我见过不止一个人，把组件源码目录只加到了浏览路径里，然后代码跳转一切正常，一编译就报错，于是坚信是组件有问题。这个误解的根源就是把“能跳转”当成了“能编译”。

正确的做法是：组件源码目录加到库路径，如果希望跳转体验好，同一目录顺手也加到浏览路径。另外源码目录和.dcu输出目录要分开设置，别让编译产物和源码混在一个文件夹里，时间长了会非常乱。

2.2 平台和编译配置是分开记账的

从支持多平台开始，库路径的设置就是按平台隔离的。你在 Win32 下加的路径，切到 Win64 之后是不生效的。同理，Debug 和 Release 两套配置在某些情况下也会有不同的路径设置。

这就解释了一个特别常见的困惑：32 位编得好好的，切 64 位就报找不到单元，路径明明加了。解决办法是在库路径设置界面把目标平台切换过去，逐个平台确认路径是否存在。组件库一般会按平台分目录存放编译产物，比如lib\win32和lib\win64，加路径时两个都要加。

用宏代替绝对路径能让配置更省心。IDE 提供了若干内置宏来指向安装目录、公共数据目录这些位置，把组件的根目录定义成一个自定义环境变量，路径里引用这个变量，将来换机器、换安装位置只需要改一处。

2.3 输出目录污染会制造非常诡异的报错

有一种故障特别消耗时间：改了组件源码里的某一行，重新编译，运行结果却像是改动没生效。原因通常是编译器在库路径里先找到了旧的.dcu，压根没去读.pas。

判断方法很简单，在源码里改一个字符串常量或者故意写一行会报错的代码，重新编译。如果报错的行号和你改的位置对不上，或者根本没报错，那基本可以确认编译器用的是旧编译产物。

清理的思路是，把组件目录下所有.dcu删干净，项目自身的输出目录也清一遍，然后强制全编译。有些组件包的工程选项里把.dcu输出到了源码目录，这种设置其实不太好，能改就改成独立的输出目录。

3. 源码包从打开到出现在组件面板的完整动作

源码包是最值得投入时间搞清楚的一条路，因为一旦搞明白，绝大多数开源组件你都能自己搞定，不会被别人的安装器牵着走。

3.1 打开工程之前的四项预检

在双击那个.dpk之前，先花两分钟做四件事。

第一，看版本兼容说明。组件的说明文档里通常会写最低支持到哪个版本，如果你的 IDE 比它还老，编译报错就是必然的，不用怀疑人生。第二，确认依赖库是否齐全。有些组件库会依赖另一个基础库，缺了就编不过，Requires里会体现出来。第三，检查目录里有没有空格和中文。老版本编译器对这类路径的容忍度很低，能挪就挪到纯英文路径下。第四，检查文件属性。从压缩包里解出来的文件偶尔带着只读属性，编译器写不进产物目录，报的错还特别隐晦。

这四步加起来不到三分钟，但能省掉后面半小时的瞎猜。

3.2 Contains 和 Requires 各填什么

打开包工程之后，工程管理器里能看到两棵子树。Contains下面列的是要编译进这个包的单元，你新增或者删减源码文件都要在这里同步。Requires下面列的是这个包依赖的其他包，常见的有运行时库、可视组件库、设计期支持库。

这里有个坑值得单独说。带设计期功能的组件，也就是能在组件面板上出现、能在对象检查器里编辑属性的那些，其注册代码通常依赖设计期支持单元。如果Requires里漏了对应的包，编译时会报找不到设计相关的接口单元。老手看到这个报错，第一反应就是去Requires补一行。

还有一种情况，组件的设计期代码和运行期代码写在同一个单元里，这种老派写法在新版本上会出问题，因为运行期包里不该引用设计期单元，否则发布程序时会莫名其妙依赖一堆 IDE 才有的东西。遇到这种组件，一般需要手工把设计期部分拆到单独单元，虽然麻烦，但改一次一劳永逸。

3.3 编译、安装、验证的三步确认

Build。注意不是 Compile。Compile 只编译有改动的单元，Build 会强制全量重编。组件安装阶段永远用 Build，避免旧产物干扰。Build 成功才会生成.bpl和.dcp。

Install。在工程管理器的包节点上右键，选择安装。这一步做的是把包登记到 IDE，让设计期代码跑起来，把组件注册到面板上。装完之后组件面板应该多出一个页签。

验证。新建一个空白项目，拖一个控件到窗体上，设置几个属性，然后编译运行。这一步能揪出很多“装上了但用不了”的问题，比如运行期包没被正确找到、组件的初始化代码有问题等等。

注意：三步里最容易跳过的是第三步。很多人看到组件面板出现页签就以为完事了，结果交付的时候才发现运行期缺包。养成拖一个控件跑一遍的习惯，能省掉后面很多返工。

3.4 设计期包和运行期包到底要不要拆

商业组件库几乎都会拆成两个包，一个是运行期包，一个是设计期包。开源组件为了省事，经常合成一个。两种做法各有道理，但我个人的倾向是，只要这个组件库会跟着项目发布到客户机器上，就尽量拆开。

拆开的好处很实在。运行期包只包含程序真正需要的代码，体积小，依赖干净，不会把设计期的编辑器界面、属性编辑器这些东西带进去。设计期包单独存在，只在你开发时加载，发布时完全不用管。合成一个包最直接的后果是，你的程序可能会依赖一些只有装了 IDE 的机器上才有的文件，在客户那边启动就报缺包，而且报的错往往指向一个你压根没听说过的文件。

4. 只有编译产物没有源码时怎么落地

商业控件或者某些内部库，给的往往是编译好的文件，没有.pas。这种安装方式跟源码包完全不同，核心思路是“文件放对位置 + 把包登记上”。

4.1 运行期文件和设计期包的分开放置

先理清楚每个文件是干嘛的。.dcu是编译单元，编译器在编译你的项目时需要它，所以要放到库路径能找到的地方。.dcp是包的声明信息，链接时需要。.bpl是实际的包二进制，设计期的那个要被 IDE 加载，运行期的那个要被你的 exe 在启动时找到。

推荐的组织方式是按版本和平台建目录，比如根目录下分lib\win32、lib\win64，.dcp和.dcu各自放进去，.bpl单独放一个bin目录。库路径指向对应平台的lib子目录，设计期包在 IDE 的包管理界面里通过“添加”指向具体文件。

运行期.bpl的查找是个独立的坑。程序启动时按系统 PATH 找，或者在你 exe 同级目录找。开发机上因为 IDE 的 bin 目录已经在 PATH 里，往往试不出问题，一拷到没装 IDE 的机器上就报缺包。稳妥的做法是把运行期.bpl复制到输出目录，作为部署清单的一部分固定下来。

4.2 版本绑定是一条看不见的锁链

编译产物和编译器之间有强绑定关系，具体体现在.dcu文件内部记录了编译器版本标记。版本不匹配时，报错信息通常是某个单元“由不同版本编译”，后面跟一串版本号。这个错没法绕过，只能换对应版本的产物。

包文件名通常带版本号后缀，比如文件名里嵌着数字，这个数字就是版本标识。升级 IDE 之后，第一件事是把所有第三方组件的对应版本找齐，别想着凑合用。混用不同版本的.bpl和.dcu最典型的症状是编译能过，但一运行就报内存错误或者访问违例，排查起来极其痛苦，因为报错位置和真正的问题源头完全对不上。

5. 六类高频故障的实际排查链路

这一节是按我这些年遇到的频率排的，每条都给出可复现的排查步骤，而不是直接甩结论。

5.1 报“找不到单元”的四种成因与分辨方法

这个报错太常见了，但成因至少有四种，处理方法完全不一样。分辨的关键是先确认“路径到底加没加对”。

第四种在老项目里出现得不少。Delphi 要求单元声明的名字和文件名（不含扩展名）一致，不一致时编译器就找不到。老代码从别处拷来拷去，文件名被改过但单元声明没跟着改，这种问题只能靠人眼比对。

5.2 控件拖得上，一编译就链接失败

组件面板上看得见、拖得下来，说明设计期包加载成功了。但编译你的项目时链接失败，问题在运行期那一侧。

最常见的原因是同一个单元同时存在于两个包里。IDE 加载包的时候会校验这一点，有时候会在启动时弹一个警告，说某个包无法加载，因为包含的单元已经在另一个包里了。这条警告千万别忽略，它往往就是链接失败的根因。处理方式是打开包管理界面，把重复的那一个移除，注意看清楚保留的是哪个版本。

第二个原因是运行期包的版本和设计期包不一致。设计期包引用的是 A 版本的运行期包，你项目里链接的却是 B 版本，符号对不上。统一版本就好。

第三个原因比较隐蔽：包的隐式链接和显式链接混用。项目选项里如果勾选了“带运行时包编译”，那你项目运行时就需要那些.bpl在场；没勾选则是静态链接，需要.dcp和.dcu。两种模式切换之后，之前的残留产物可能还在被引用，清理重建是标准动作。

5.3 卸载之后组件面板上还有幽灵页签

决定不用某个组件了，从包管理界面里移除，重启 IDE，页签还在，点一下还报错。这种情况需要清三个地方。

第一，包管理列表里是否真的移除了。有些包被移除后，注册信息还留在配置文件里，下次启动又自动加载。第二，组件面板的页签配置。页签本身是一份独立的配置，包没了但页签还在，就会变成空壳。一般在面板上右键可以编辑页签，把空的删掉。第三，项目里的单元引用。组件包的单元还在某个项目的 uses 里，只要编译那个项目就会报错，这跟 IDE 层面装没装是两码事。

我个人的习惯是，卸载组件之后立刻新建一个空项目编译一次，确认没有残留的单元引用被隐式带入，再继续干别的。

5.4 32 位能跑，切到 64 位就编不过

前面提过路径按平台隔离，这里补充另一半：组件本身必须提供对应平台的编译产物。如果预编译包只给了 32 位的.dcu，你切到 64 位必然编不过，这不是配置问题，是素材缺失。

判断方法很简单，去lib目录看有没有对应平台的子目录。没有的话，只能找发布方要，或者改用源码包自己编。源码包的场景下，在包工程里把目标平台勾上，重新 Build 一次，64 位产物就出来了。

有时候组件源码里有针对平台的汇编或者特定 API 调用，64 位下编不过。这种情况要么等发布方更新，要么自己在条件编译里把那段代码隔离掉，前提是你确认那块功能在你的项目里用不到。

6. 多版本共存和团队协作下的组件治理

一个人一台机器的时候，组件怎么装都行。一旦涉及多版本 IDE、多人协作、机器迁移，没有约定就会变成灾难。

6.1 一套源码喂多个 IDE 版本的目录约定

我习惯的目录结构是这样的：在某个固定的开发盘符下，一个第三方组件根目录，下面按厂商或库名分层，再往下是版本号，版本号下面是源码，源码旁边是编译产物目录，产物目录里再按平台和配置细分。库路径用环境变量引用根目录，这样换机器只需要设一次环境变量。

关键的一点是，编译产物绝对不要输出到公共目录。我见过把.dcu统一输出到一个全局文件夹的配置，理由是“省空间”。结果是两个不同版本的 IDE 互相覆盖产物，谁也不知道当前编译用的是哪个版本的单元，报错信息五花八门。按 IDE 版本隔离产物目录是底线。

另外，同一个库在不同项目里可能需要不同版本，这种情况就别想着全局一份了，直接按项目做本地化目录，项目目录下建一个thirdparty放依赖，随项目一起进版本管理。体积大一点，但可控。

6.2 把组件依赖写进项目文档

这一条听起来像流程要求，实际是救命的东西。我接手过一个项目，要用到七八个第三方组件，散落在各个开发机本地，谁也不知道完整清单。重装系统之后花了整整两天才把环境搭回来，中间还因为某个库版本不对，编出来的程序在客户那边崩了。

后来我们固定了一个清单表，每行记录库名、版本、来源、安装路径、依赖的其他库、安装方式（源码还是预编译）。新机器照表装一遍，半小时搞定。这张表其实不用多正式，一个 Markdown 文件放在项目根目录就行，关键是要有人维护，装新组件的时候顺手加一行。

7. 几个只有踩过才知道的细节

包工程编译前先关掉其他项目。听起来无关，实际上当多个项目同时打开时，IDE 的搜索路径会受当前激活项目影响，编译包工程时偶尔会意外引用到另一个项目目录下的同名单元，报出的错指向一个你压根没想到的文件。我现在编译组件包之前习惯把其他项目全关掉。

.bpl输出路径和 IDE 的搜索路径要对得上。包编译完，.bpl落在工程设置的输出目录里，但 IDE 加载设计期包时是按你指定的绝对路径找的。这两者不对应的时候，会出现“编译成功但安装报找不到文件”。要么把输出目录设成固定位置，要么安装时手动指到实际产出位置。

从网络共享盘上直接编译组件包不靠谱。文件锁、路径长度、权限检查都会制造麻烦，尤其涉及大量小文件写入的时候。把源码拷到本地盘再编，能避开一大类莫名其妙的失败。

注意依赖库之间的加载顺序。如果 A 包依赖 B 包，B 必须先被加载。IDE 通常会自己处理，但手工调整过包列表顺序之后，偶尔会出现加载失败。遇到这种情况，把依赖包先移除再按正确顺序添加回去。

设置完路径之后重启一次 IDE。有些路径设置的生效时机是 IDE 启动时读取配置，运行中修改虽然大多数时候也能生效，但涉及包加载的场景，重启一下最省事，别跟自己较劲。

最后分享一个我自己的小技巧：给每一个装过的组件库，在它源码目录里放一个纯文本的INSTALL.txt，写清楚这台机器上的安装步骤、当时用的是哪个 IDE 版本、遇到什么问题怎么解决的。半年后回头看，这几行字的价值远超当时写它的两分钟。组件安装这件事，难点从来不在操作本身，而在于搞清楚每一步在干什么、失败的时候该往哪儿看。把这个逻辑理顺了，以后再遇到没见过的组件包，你也一样能自己搞定。