Delphi 10.1 Berlin组件安装实战：Raize 6.1.1.12完整配置与排错

简介：面向 Delphi 开发者的 Raize 6.1.1.12 DX10.1 Berlin 修正版组件包，针对 Berlin 版安装时 pas 错误导致编译失败的问题做了修复，并重新调整配置，使组件能在 RAD Studio 10.1 Berlin 环境中顺利安装使用。资源共956个文件，压缩包约10.74MB，主要包含 hpp 头文件、dcu 预编译单元、pas 源码、dfm 窗体定义、bmp 设计期图像以及 dpk 包文件等，覆盖组件库的完整编译与运行所需。使用时可解压至指定目录并执行附带的构建脚本，即可完成安装，过程清晰，适合需要快速搭建 Raize 组件环境的开发人员。目前已有330人学习下载。借助修正后的源码和构建脚本，可避免手工排查错误，同时完整目录结构也便于后续按需定制或二次开发，对使用 Raize 6 的 Delphi 工程师具有实用价值。

1. 安装前的版本坑：DX10.1 不等于 DirectX 10.1

第一次把老项目从 Delphi XE8 往 10.1 Berlin 迁的时候，我在 Raize 组件上翻了个大跟头。工程里到处是 RxLabel、RaizeButton 这类控件，装完组件包后 IDE 直接报 “package not found”，编译列表满屏红，连着排查了两天才定位到是版本识别问题。包名里的 DX10.1 指的不是 DirectX 10.1，而是 Delphi 10.1 Berlin；这个版本号跟 XE10.1 的写法在安装脚本里经常混着用，选错一个目录，后面全是白费。这篇安装笔记按环境检查、编译包、注册、排错、验证的顺序来写，顺序就是我当时踩完坑之后整理出来的可执行流程。新手照着走能跑通，熟手可以重点看第 5 章的五个排查记录。

2. 环境检查与资源准备：Delphi 10.1 Berlin 匹配度决定能不能装

装这套包不顺的时候，大部分情况不是安装包本身损坏，而是 IDE 版本、包结构、安装路径三者没对齐。所以我不急着解压、不急着点 Install，先把环境确认清楚，每一步才有据可查。这一章花十分钟做完，后面挑错的时候能少走一半弯路。

2.1 确认 IDE 版本：DX10.1 指的是 10.1 Berlin，不是 DirectX

先打开 Delphi 10.1 Berlin，进入 Help > About 看版本号。10.1 Berlin 的 IDE 内部版本号是 18.0，Win32 编译器版本号是 31.0。包名里的 DX10_1、Delphi18、Berlin 本质都是指向同一个 IDE，只是不同组件包作者习惯用的目录名不一样。Delphi XE10.1 是 10.1 Berlin 在更名过程中的早期叫法，安装脚本里如果写的是 XE10.1，装到 Berlin 上也没问题，但你必须确认目标机器装的确实是这个版本，而不是 Delphi XE10.2 或 10.2 Tokyo。版本差一个小版本，编译出来的包符号都不通用。

还需要确认 IDE 的活动平台是 Win32。Raize 6.x 的组件包是按 32 位组件库方式编译的，在 10.1 Berlin 里用 Win64 平台打开包，编译时会提示平台不匹配，即使勉强装上，设计期也可能只显示占位框。打开 Tools > Options > Tools > Platforms，把当前活动平台切到 Win32，再继续后面的步骤。

2.2 检查安装包：解压后先看目录，再决定怎么装

拿到 Raize 6.1.1.12 修正版后，先不要急着双击什么 Install.exe。这类修正版通常已经把原版安装器拆开，改成了手动编译注册的模式，解压后你会看到几个固定目录。先确认下面几个目录都在，缺了哪一块，后面装到一半就会卡住。

• Sources：组件源码目录，设计器定位和调试用，必查。
• Packages：按 Delphi 版本分子目录存放的 dpk 包工程，核心目录。
• Compiled 或 Bpl：存放编译后的 bpl / dcp 文件，有些版本会预先编好一份。
• Examples：示例工程，可以不装，但建议留着对照验证。
• Readme.txt 或“安装说明.txt”：修正版作者通常会把改动点写在这里，先看。

同时认识一下这几种文件类型，后面会反复用到：

这里我一般不会直接用修正版预编译好的 bpl。.bpl 对编译器版本非常敏感，你本机如果装过 10.1 Berlin 的 Update 补丁，而预编译 bpl 是在另一个补丁版本下编的，加载时就会报“对象版本不匹配”或“接口单元冲突”。宁可自己动手重编一遍，花不了几分钟，能省下后面一堆玄学问题。

2.3 规划安装路径：三个不能放的位置

安装路径的规划，直接决定后面编译能不能一次过。我见过太多人的包放在中文用户名目录下，编译时报错路径乱码，还以为是包坏了。三个位置不要放：

• 不要放在 C:\Program Files (x86) 下。这个目录有 UAC 权限保护，编译时写入 dcu、bpl 会频繁弹权限提示，甚至静默失败。
• 不要放在带中文的路径下。Delphi 编译器对非 ASCII 路径的支持一直很一般，老组件包尤甚。桌面路径如果带中文，也会踩同样的坑。
• 不要放在桌面或网盘同步目录。网盘同步会锁文件，编译时正好撞上文件占用，报错没有任何规律。

建议装到 D 盘根目录下的纯英文目录，比如 D:\Raize61112 或 D:\RaizeComponents。整个安装过程记录一个固定路径，后面每次配置 Library 路径、bpl 路径都用这一条，不要今天用 D 盘明天用 E 盘，项目换台机器打开时路径不一致会很难排查。

提示：如果机器上之前装过旧版 Raize，先记下旧版本的安装位置，后面第 5 章会讲怎么清理。现在先确保新版本在一个干净、独立、纯英文的目录里。

3. 安装流程：从编译运行期包到注册设计期包

安装顺序不能乱，必须先编译运行期包，再安装设计期包。因为设计期包在 IDE 中注册时要解析运行期包的符号，顺序反了，IDE 会报 “package not found” 这种假错误，看起来像是包坏了，其实只是依赖没就绪。整个流程分三步：编译 Runtime 包、注册 Design 包、配置 Library 路径。

3.1 第一步：编译运行期包（Runtime Packages）

区分一下两个概念：运行期包是程序运行时加载的 bpl，里面是组件实现代码；设计期包是 IDE 设计器使用的，负责把组件注册到面板上，它自身引用运行期包。所以编译顺序一定是 Runtime 在前。

用 IDE 编译的方式比较适合新手。先以管理员身份打开 Delphi 10.1 Berlin，执行 File > Open，找到 D:\Raize61112\Packages\DX10_1 目录下的运行期包文件。文件名通常是 Raize 开头、带 Runtime 或 Run 后缀的 dpk。打开后，在 Project Manager 面板里右键这个包节点，选择 Compile，等输出窗口出现 BUILD SUCCESSFUL 就算过了。

如果手头有开发构建环境，也可以走命令行，速度更快也更好复现：

cd /d D:\Raize61112\Packages\DX10_1 call "C:\DelphiInstall\Studio\18.0\bin\rsvars.bat" msbuild RaizeVCLRuntime.dpk /p:Config=Release /t:Build

第一行进入包目录；第二行调用 Delphi 的环境变量脚本，把编译器路径、库路径等设置到当前命令行；第三行用 MSBuild 执行编译。rsvars.bat 的路径要改成你本机 Delphi 10.1 Berlin 的实际安装位置，找不到就搜索一下，它在安装目录的 bin 文件夹下。参数方面，/p:Config=Release 指定按 Release 配置编译，组件包一般用 Release；/t:Build 表示执行构建动作。如果你看到不止一个 dpk 文件，文件名不是 RaizeVCLRuntime.dpk，那就把文件名替换成实际包名。

编译完成后，去输出目录确认生成了两个文件：一个 .bpl 和一个 .dcp。只有 bpl 没有 dcp，或者两个都没有，说明 Output directory 没配对。到 Project Manager 里双击包节点，查看 Project Options 中的 Output directory，确保它指向 D:\Raize61112\Compiled，然后重新编译一次。有人会在这里漏看，导致后面设计期包安装了却找不到运行期符号，浪费大量时间。

3.2 第二步：安装设计期包（Design Packages）

运行期包编译好后，回到 IDE 主窗口，执行 Components > Install Packages。在弹出的对话框里点 Add，找到设计期包对应的 bpl 文件。设计期包的文件名一般带 Design 后缀，注意别选成运行时包。选完后，对话框列表里会多出一条 Raize 相关记录，组件面板上也会出现一个名为 Raize 的页签。

这里有个细节：Add 时选的是 bpl，不是 dpk。有人直接在 Project Manager 里打开设计期 dpk 然后点右键 Install，这也可以，但我更建议用 Install Packages 对话框操作，因为它能直观看到“哪个包被加载了、来自哪个路径”，排查时方便。另外，不要双击 bpl 文件来安装，bpl 双击只会一闪而过，Windows 不会因此把它注册到 Delphi 的包列表里，什么都装不上。

如果安装后组件面板没有出现 Raize 页签，先检查当前是否还开着一个含有 Raize 控件的项目。IDE 加载失败时会锁住包注册流程，关掉项目再装。还有一种可能是活动平台不在 Win32，回到 2.1 节核对。这一步骤做完了，设计期算是通了，但离真正跑通还差最后一步路径配置。

3.3 第三步：配置 Library 路径

打开 Tools > Options > Environment Options > Delphi Options > Library，在 Library path 框里新增两个路径：

D:\Raize61112\Sources D:\Raize61112\Compiled

第一行是源码路径，让 IDE 在设计器中打开含 Raize 控件的窗体时，能定位到控件类的源码文件；第二行是 dcp 所在目录，让编译器在编译项目时能解析到 Raize 包的符号。这两个路径缺一个，后面都会出现“编译通过但设计器打不开”“设计器能打开但编译报错”的奇怪组合问题。

加完路径后，强烈建议重启一次 IDE。Library 路径的缓存不会在修改后立即全部刷新，有时候面板上已经能看到组件，但一编译就报找不到 dcu，重启后缓存重建，问题自动消失。这一步很多人跳过，然后在群里问“为什么我都装好了还是编译失败”，其实只是没重启。

4. 配置细节：bpl、dcp、源路径三个关键项

组件面板出来了，编译也过了，并不代表这项工作结束了。真正在项目里跑一段时间，你会发现大部分问题都集中在三件事上：bpl 文件是不是在系统能找到的位置、dcp 文件是不是和 bpl 配套、源码路径是不是让设计器认到了。这一章专门把这三个细节拆开讲，每一项我都踩过坑。

4.1 bpl 输出路径与系统 PATH

bpl 本质上是一个 Windows DLL。程序在运行时加载它，Windows 会按固定顺序去搜索：先看 exe 所在目录，再找系统目录，最后按系统 PATH 逐个找。如果你的 bpl 放在 D:\Raize61112\Compiled，而系统 PATH 里没有这个目录，就会出现一个很经典的场景：IDE 里编译运行一切正常，把 exe 单独拷到一个目录去跑，立刻弹窗“找不到 RaizeVCLRuntime.bpl”。

解决方法是把 bpl 目录加进系统 PATH。我推荐用 PowerShell 修改机器级 PATH，而不是用 setx：

$bplPath = "D:\Raize61112\Compiled" $oldPath = [Environment]::GetEnvironmentVariable("Path", "Machine") [Environment]::SetEnvironmentVariable("Path", $oldPath + ";" + $bplPath, "Machine")

第一行定义要加入的 bpl 目录；第二行读取当前机器级 PATH；第三行在原值后面追加新目录并写回。Machine 作用域表示对所有用户生效，修改时需要管理员权限。为什么不建议用 setx？setx 有个老毛病，它会把 PATH 截断到 1024 个字符，一旦你的 PATH 原本就比较长，追加完发现后面的路径全丢了，系统里一堆命令失效，这个后果比装组件失败还难受。用 PowerShell 的 .NET 接口可以绕过长度限制。

改完 PATH 后，关掉当前打开的命令行窗口和 IDE，重新打开一次，让环境变量刷新。如果项目要交给其他机器编译，也要在构建机上重复这一步。另一种做法是把 bpl 复制到 exe 输出目录，这样单机跑没问题，但项目一多，每个输出目录都放一份 bpl，版本容易乱，我一般不这么做。

提示：改 PATH 前先跑一遍上面的第二行命令，把原值存成一个文本文件备份。改系统环境变量这种事，有后悔药总比没有好。

4.2 dcp 文件必须与 bpl 配套

dcp 是编译 dpk 时生成的包符号文件，它记录了这个包里所有单元的公开符号。IDE 编译项目时，如果能在 Library path 里找到 dcp，就直接引用包符号编译，不会去重新编译源码；如果找不到，IDE 会退回源码路径去找 dcu，再找不到就直接编译源码。这个过程看起来“也能过”，但代价是你的工程对源码的依赖变得非常强，源码目录只要有一点变动，编译结果就跟着变，出现那种“换个目录就报错”的病。

我习惯把 dcp 和 bpl 放在同一个目录里，也就是 D:\Raize61112\Compiled。这样 Library path 里只需要这一条路径，既能找到 dcp，也能兼顾运行时 bpl 的查找，路径越少，排查越简单。

不要做的一件事，是把 dcp 复制到 Delphi 自带的 Lib 目录。表面上编译速度变快了，但后续麻烦很大：下次 Delphi 打补丁或者你装另一个组件包的版本时，Lib 目录被覆盖，残留的旧 dcp 会让 IDE 报“单元标识符重定义”或者“常量重复定义”，报错信息指向的根本不是你的代码。检查 dcp 是否配套，我一般直接看文件的修改时间和所在目录。在 Windows 资源管理器里搜索 Raize*.dcp，如果搜出来多份，只保留 D:\Raize61112\Compiled 这一份，其余全部删除，再重启 IDE。

4.3 源路径要加到 Library path 而不是 Search path

设计器打开含有 Raize 控件的窗体时，需要读到控件类的源文件或至少是源路径里的声明。如果 Library path 里没有加 D:\Raize61112\Sources，你会看到两种典型情况：一种是窗体打开后控件变成灰色矩形，属性窗口里什么都点不了；另一种是 IDE 弹窗提示 cannot find source，让你手动定位文件。

Library path 和 Search path 的区别很多人分不清。Library path 是编译器和 IDE 共用的单元搜索路径，设计器定位类声明也用它；Search path 是编译器专用的辅助搜索路径，IDE 的设计器不一定认。所以我两个都加，Library path 用来保证源码可见，Search path 用来防止编译器漏掉某些间接引用。路径重复不会报错，不需要担心。

加好源路径后，有一个简单的验证方法：在窗体设计器里右键一个 Raize 控件，选择 View Source（不同版本菜单名可能略有差异），如果能跳到对应的 .pas 文件，说明源路径生效；如果跳不到，回 3.3 检查路径有没有写错、有没有重启 IDE。另外，代码导航用的 Browsing Path 有时候也需要同步加一条 D:\Raize61112\Sources，否则 Ctrl + 点击控件属性时同样跳不到实现位置。

5. 避坑与排查：Raize 6.1.1.12 在 Berlin 下的 5 个常见问题

这五个问题基本覆盖了 6.1.1.12 在 10.1 Berlin 下最常翻车的点，每条我都按“现象、原因、解决”三个步骤拆开写。你在群里问装机问题的时候，多半也是这几个姿势。

5.1 坑一：组件面板空白

现象：Install Packages 对话框里能看到 Raize 设计期包，但组件面板翻遍所有页签都没有 Raize 页。

原因：大概率是 Add 错了 bpl，装成了运行时包。运行时包只提供实现代码，不负责注册设计期组件，所以它在包列表里但面板没有任何变化。另一个可能是 IDE 当前活动平台是 Win64，而 bpl 是按 32 位编译的，加载被静默跳过。

解决：先在 Install Packages 列表里把已经加进来的 Raize 条目 Remove 掉，重新 Add 那个带 Design 后缀的 bpl。接着确认 Tools > Options > Tools > Platforms 里的活动平台是 Win32，最后在组件面板右键选择 Reset Component Palette，强制刷新一次面板缓存。多数情况走完这三步，Raize 页就回来了。

5.2 坑二：编译报 can't load package 或 package not found

现象：打开项目或启动 IDE 时弹窗，提示 Can't load package D:...\RaizeVCLDesign.bpl 或者找不到指定的模块。

原因：常见的是 design 包依赖的运行时 bpl 不在这台机器的搜索路径里，或者 bpl 文件根本不存在。设计期包加载时会连带加载依赖的运行期包，运行期包找不到，设计期包也跟着加载失败。还有一种可能是机器上装了两个版本的 Raize，IDE 加载时先撞到了旧包的路径。

解决：在 D:\Raize61112 下搜索 Raize*.bpl，确认 Runtime 和 Design 两个包都在 Compiled 目录里，并把目录加进 PATH（见 4.1）。如果搜出来多个不同位置的 bpl，删除旧的，只保留 6.1.1.12 这一份。删完后打开 IDE 的 Install Packages，把设计期包先 Remove 再重新 Add，让它按新路径重新注册一次。

5.3 坑三：设计期正常，运行期找不到类

现象：IDE 里拖控件毫无问题，设计器也正常，但程序一运行就报 Class TRaizeButton not found，或者窗体加载失败，进程直接挂掉。

原因：项目勾选了 Build with runtime packages，运行时必须能加载 Raize 运行期包。但开发机上 bpl 目录没有加到系统 PATH，或者发布部署时没有把 bpl 一并带过去。IDE 里能跑是因为 IDE 自己加载过这个包，脱离 IDE 跑 exe 时系统找不到了。

解决：开发机把 D:\Raize61112\Compiled 加入 PATH，重启后再跑。发布机上把 Raize 相关的几个 bpl 复制到 exe 同一目录，或者用安装脚本装到系统目录。如果项目不是必须要用 runtime packages，也可以在 Project Options > Runtime Packages 里取消勾选，让组件以静态链接方式编进 exe，体积变大一点，但省了分发 bpl 的麻烦。

5.4 坑四：中文用户名导致路径乱码

现象：编译时提示 Cannot open file，输出窗口里路径显示成乱码，或者直接提示文件路径非法，但文件明明就在那里。

原因：Windows 用户名是中文时，桌面和文档目录都带非 ASCII 路径。Delphi 10.1 的编译器对非 ASCII 路径支持有历史问题，组件包的编译脚本里如果有相对路径引用，拼接后就会变成乱码。修正版虽然处理了安装脚本，但源码工程一旦放到中文路径下，编译仍然可能踩中。

解决：把安装包和工程都放到纯英文路径下，比如 D:\Raize61112 和 D:\MyProject。工程已经在中文路径的，先用资源管理器移动到英文目录，再在 Project Manager 里调整输出路径。如果非要放在带中文的用户目录下，可以给中文用户目录做英文 junction 映射，但这样换一台机器就要重配一次，我试过一次就不再用了，统一英文路径是最省心的。

5.5 坑五：覆盖安装后旧版本残留

现象：装完 6.1.1.12 后启动 IDE 很慢，编译时大量报 Duplicate unit 或 Unit 重定义，指向的文件路径既有新版本又有旧版本。

原因：旧版 Raize 没有卸载干净。安装新包时，旧 bpl、dcp 还残留在系统 PATH、Library path 和 Delphi 包缓存里，IDE 同时加载新旧两套组件，单元符号重复注册，编译自然冲突。

解决：这一步要按顺序来。先在 Install Packages 里移除旧版本的设计期包；再用 Everything 或资源管理器搜索 Raize*.bpl 和 Raize*.dcp，按修改时间筛选，把旧版本文件删除，只留 6.1.1.12 对应的那一份；最后清理 Delphi 包缓存，位置一般在用户目录的 AppData 下的 BDS 18.0 相关文件夹，找到 KnownIDE 或 Package 缓存子目录，把里面 Raize 相关记录清掉。清理前先备份目录，删除操作比安装更需要谨慎。重启 IDE，确认编译不再报重复单元即可。

6. 装完怎么验证：用一个小项目把 Raize 组件跑起来

装完先别急着打开老工程，用最小验证跑一遍，确认安装是干净可用的。这一步只花十分钟，能挡住后面一整天“明明装好了但项目就是怪怪的”的折腾。

6.1 新建 VCL 应用并拖入组件

File > New > VCL Forms Application，新建一个空窗体。在组件面板找到 Raize 页，依次拖一个 RxLabel、一个 RaizeButton、一个 RaizePanel 到窗体上。然后重点检查对象监视器：选中控件，右侧属性列表能不能完整展开，能不能修改 Caption、Color 这些基础属性。如果属性列表空白，或者出现灰色的未识别对象，说明源路径配置有问题，回到 4.3 再查一次。

6.2 写代码编译并拷出去运行

给窗体加一个 FormCreate 事件，输几行最基础的代码验证运行期包：

procedure TForm1.FormCreate(Sender: TObject); begin RxLabel1.Caption := 'Raize 6.1.1.12 is ready'; RaizeButton1.Caption := 'Click me'; RaizePanel1.Color := clBtnFace; end;

编译前看一下 Project Options 里的 Runtime Packages 状态，确认你是按需要勾选或取消的。按 F9 运行，窗体应该正常显示，标签文字正确，按钮可点击，不弹任何找不到包的提示。运行没问题后，到工程输出目录把 exe 单独复制到一个空目录，双击运行它。这一步专门验证脱离 IDE 后 bpl 能不能被系统找到。如果弹缺 bpl，说明 4.1 的 PATH 还没配对，回去确认。

6.3 反向验证：移除源路径后重新编译

最后做一个比“看到组件面板”更严格的验证。打开 Tools > Options，把 Library path 里的 D:\Raize61112\Sources 临时移除，只保留 Compiled 路径，然后重新编译刚才这个测试工程。如果能编译通过，说明项目是通过 dcp 包符号来解析 Raize 单元的，而不是依赖源码现编。这是安装配置真正合格的标准。如果报错，说明当前工程还对源码路径有直接依赖，把源路径加回去，检查 dcp 是否真的被 IDE 找到了。验证完再把源路径加回来，第一次重新编译会慢一点，因为 IDE 要重建部分 dcu 缓存，属于正常现象。

从那以后，我每次装完 Raize 6.1.1.12 修正版，都强制走一遍“新建工程、拖三个控件、写一行代码、编译、拷 exe 到干净目录运行、移除源路径再编一次”的流程，一条不过就回查对应章节。这套流程十分钟不到，但能省下后续项目里大量“明明装好了怎么还报错”的无效排查。希望帮到你。

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