Delphi XE10老源码从零到可用：环境搭建与编译排错

搞 Delphi 老项目的人都体会过那种感觉源码包解压开几十个 .pas 铺满屏幕双击工程文件IDE 一加载就弹红字F9 按下去编译器甩给你一屏 “File not found” 和 “Unsatisfied forward or external declaration”。我最近重新捡起来折腾的这套 BLUE 源码就是典型它是一套用 Delphi 写的老工程包含服务端主程序和几个配套工具代码风格停留在 Delphi 7 到 2007 那个年代后来社区陆续打补丁最终的口径是“能在 Delphi XE10 上编译通过”。标题里说的“从零到可用”指的不是把代码改到多优雅而是让这套 BLUE 源码在一个干净的 Windows 环境里从装 IDE 开始一路走到双击 exe 能出界面、能读到配置、能连上依赖库。这个过程踩的坑非常集中字符集从 ANSI 到 Unicode 的断层、第三方组件包的编译顺序、32 位与 64 位的取舍、老式内联汇编的硬限制每一个都能让你卡半天。这篇东西适合三类人看——手上正好有一份类似老 Delphi 工程要救活的、想搞清楚 XE10 编译链细节的、以及被“单元找不到”折磨过想系统补一遍的。下面按我实际操作的顺序讲凡是涉及参数的都给出来历凡是涉及选择的都说明为什么不选另一条路。1. 摸清这套源码的底子为什么 XE10 是那个“刚刚好”的版本动手改任何一行代码之前我花了大概两个小时只做一件事不做编译纯读代码搞清楚这套 BLUE 源码到底依赖什么。这一步看起来浪费时间实际上决定了后面所有的配置决策。老 Delphi 工程的兼容性不是线性的不是说版本越新越好也不是说越老越稳它有一个“甜点区间”而 XE10 恰好落在这个区间里。1.1 代码年代决定了编译器的上限和下限判断代码年代有几个快速信号看有没有Application.Title之外的 VCL 风格属性、看字符串是string还是AnsiString还是ShortString、看有没有Forms单元之外还引用了Controls、看.dpr里有没有Application.Initialize。这套 BLUE 源码里大量出现ShortString和显式PChar还有若干处asm ... end内联汇编这两条基本就把路锁死了。内联汇编在 Delphi 的 64 位编译器下是不支持的这是硬约束不是配置问题。也就是说无论你多么想上 Win64只要代码里有asm块并且没有对应的 Pascal 替代实现你就只能老老实实编 Win32。我在源码里搜到七处asm其中三处是内存拷贝和位运算优化四处是老的钩子调用改成 Pascal 不是不能改但改完要重新验证行为风险远大于收益。所以我的结论是目标平台锁定 Win32不做 64 位尝试。版本下限则由语法决定。代码里用到StrToInt64Def、FormatFloat这些 RTL 函数Delphi 7 就有所以下限并不高。真正卡住下限的是第三方组件——这套工程引用的几个控件包需要至少 XE2 以上才能装。上限则来自 UnicodeDelphi 2009 之后string默认变成UnicodeString而这套代码里到处是按字节处理字符串的逻辑直接上高版本会大面积行为变化。XE10 是社区验证过的版本条件编译分支基本都写好了所以选它不是因为它先进是因为它“踩过的人最多坑都被填过”。1.2 组件与第三方库盘点先列清单再动手我习惯在动手前先列一张依赖表把源码里所有uses中出现但明显不属于 RTL/VCL 的单元挑出来反查它们属于哪个包。这套 BLUE 源码的清单大致是这样单元名前缀所属类型是否随源码附带处理方式数据访问相关数据库直连组件否需单独获取装包后加入 Library Path网络通信相关Socket / 异步 IO 封装部分附带缺的部分按版本补齐压缩解压相关压缩库封装是含源码直接编入工程组界面增强相关VCL 皮肤/表格控件是含 .dpk先编译安装包加密摘要相关哈希/校验封装是随主工程编译这张表的价值在于它把“编译错误”提前转化成了“环境准备任务”。等你真的按下编译报错就只剩两类我漏装的和我配置错的。前者查表补后者查路径。没有这张表你会在几十条 “Unit not found” 里反复试错一条一条去猜是哪个包。注意不要相信源码压缩包里自带的 ReadMe 里写的版本号。老项目的 ReadMe 往往是三手信息改代码的人换了文档没跟着换。以uses里的实际单元名和包内.dpk的requires子句为准。1.3 编译目标与运行环境的匹配关系平台锁定 Win32 之后还有一个容易被忽略的点运行环境必须和目标位数一致。这套 BLUE 源码依赖的几个 DLL 只有 32 位版本如果你在 64 位系统上用 64 位的宿主进程去加载会直接报“不是有效的 Win32 应用程序”。这不是编译错误是运行期错误而且报错信息极其误导人。我的做法是在工程目录下建一个bin目录把编译产物和所有依赖 DLL 统一丢进去然后在 IDE 的运行参数里把工作目录指向它。这样调的时候相对路径的查找基准就是bin不会出现“IDE 里跑得好好的双击 exe 就崩”的情况。这个习惯我从很早以前就养成了救过很多次。2. 把 IDE 和目录规划先做对环境搭建这一步很多人是“装完就开干”然后花三天时间在和路径搏斗。我的顺序是先装、再规划、最后配路径三步分开做每一步做完都验证一次不让问题叠加。2.1 XE10 安装时那几个必须手动勾的选项XE10 的安装器默认安装项是“能跑 Hello World”的最小集对老工程远远不够。我在安装时额外确认了这几项Win32 的编译器与 RTL 源码默认装但要确认、VCL 组件库、命令行编译器 dcc32、以及IDE 的英文界面包。最后一项不是洁癖是因为大量老教程、老报错信息的截图都是英文界面中文界面下你搜报错都对不上号。安装路径我强烈建议不要带空格、不要带中文、不要放在用户目录下。默认路径里有Program Files (x86)这个括号和空格在某些老式构建脚本里会被截断导致命令行编译莫名其妙失败。我一般装到D:\Dev\DelphiXE10这种纯 ASCII、无空格的短路径下。这一个动作能省掉后面至少三类诡异问题。另外安装完成后第一次启动IDE 会问你要不要参与体验改进计划之类的全部选跳过。这些东西会往注册表和用户目录写配置出问题时排查成本很高能少一个变量就少一个。2.2 目录结构源码、输出、依赖三分家我这套 BLUE 源码最终落地的目录结构是这样的你可以直接照抄BLUE\ ├── src\ 原始源码只读不改结构 │ ├── main\ 主工程 .dpr │ ├── common\ 公共单元 │ └── tools\ 配套工具工程 ├── thirdparty\ 第三方组件源码与 .dpk ├── lib\ 编译中间产物.dcu ├── bin\ 最终 exe 与依赖 DLL ├── cfg\ 运行时配置文件 └── build\ 构建脚本这么分的核心理由是把“会被修改的东西”和“不该被修改的东西”物理隔开。src我只读不写需要改的地方一律通过条件编译或者在外层包一层lib和bin随时可以整个删掉重来不影响源码。老工程最怕的就是改着改着分不清哪份是原始代码等你哪天想回滚发现已经回不去了。实际配置的时候IDE 里的Output directory指向..\libFinal output directory指向..\binUnit output directory也指向..\lib。注意 Unit output directory 一定要设否则.dcu会和.pas混在一起源码目录会越用越脏而且增量编译容易拿到过期单元。2.3 库搜索路径的配置顺序决定编译成败Delphi 的单元搜索顺序是工程目录 → 工程 Search Path → IDE 的 Library Path → 系统安装目录。这个顺序意味着如果你在 Library Path 里放了旧版本的公共单元它会覆盖掉你工程里自带的同名单元——这是个非常隐蔽的坑报错表现是“单元里的函数签名对不上”你会以为代码写错了其实是加载了错的单元。我的配置原则是能在工程级 Search Path 里写的绝不写进全局 Library Path。全局路径只放真正跨工程共享的东西比如第三方组件的编译输出目录。工程级的 Search Path 我按这个顺序排..\src\common公共单元优先级最高..\thirdparty\xxx\source第三方源码..\lib编译产物放最后把产物目录放最后是个小技巧。这样万一某个单元既在源码里又在产物里编译器优先拿源码重新编不会用到过期的.dcu。代价是首次编译慢一点换来的是“改了代码一定生效”这个确定性我觉得很值。2.4 字符集与中文路径两个老生常谈但每次都中招的坑字符集问题在这套 BLUE 源码里表现得特别典型。代码里大量出现这种写法var Buf: array[0..255] of Char; Len: Integer; begin Len : Length(SomeStr); Move(SomeStr[1], Buf[0], Len);在 Delphi 7 里Char是 1 字节这段代码按字节拷贝没问题。在 XE10 里Char是 2 字节的WideCharMove的长度算出来还是字符数拷过去就是半截数据后面所有解析全乱。这类问题不会报错只会让程序行为诡异是最难查的一种。处理方式有两条路一是把相关声明统一改成AnsiChar并显式用AnsiString二是加编译开关把默认字符串退回 ANSI。我选的是第一条逐个改因为编译开关是全局的一旦开了会影响所有单元包括那些本来就用对了 Unicode 的地方。改的时候我做了个约定凡是和外部字节流打交道的变量一律显式声明为AnsiString或TBytes凡是在界面和日志里用的一律string。这条约定写进注释后面接手的人不会乱。中文路径的坑更直接只要工程路径里有中文某些老式资源编译器就会失败报“找不到 .res 文件”。解决办法就一句话——整个工作目录不要出现任何非 ASCII 字符。配置文件的路径也一样cfg目录下的文件名我全用英文短名中文只出现在文件内容里。3. 工程文件与编译选项逐项过一遍真正开始动工程文件的时候我建议先在 IDE 里把所有选项过一遍然后把.dproj存一份副本。因为 XE10 的 IDE 有时候会在你不知情的情况下改写.dproj加了几个默认节点进去出问题时对比副本能立刻定位。3.1 .dpr 与 .dproj 里必须动的地方.dpr是工程入口结构很简单但有几个地方必须改。第一是uses里的单元顺序Forms必须在依赖 VCL 的单元之前ShareMem如果用到必须排第一这套源码没用到我确认过没有跨模块传字符串的情况。第二是初始化代码老工程常有Application.Initialize之后直接跑主窗体的写法需要确认没有依赖已废弃的全局变量。.dproj是 XML我一般只改三类节点DCC_Define里的条件编译宏、DCC_UnitSearchPath里的搜索路径、DCC_Output系列里的输出目录。其余交给 IDE 管。手改.dproj有个好处是可以进版本管理团队里每个人拿到的编译配置完全一致不会出现“你那边能编我这边不行”。条件编译宏这块这套 BLUE 源码里用到了版本判断大致长这样{$IF CompilerVersion 30} // XE10 及以上分支 {$ELSE} // 老版本分支 {$IFEND}CompilerVersion是个很有用的常量XE10 对应的是 30。但要注意不同版本的常量名不统一有的代码里写的是VER300具体以你手上源码的定义为准编译前先全局搜一遍确认两边一致。我在源码里发现过同时存在VER300和CompilerVersion 30两套判断逻辑上等价但风格混乱就统一成了后者。3.2 编译指令开关的组合决定了你会不会“编过但跑错”Delphi 的编译开关是这套工程里最容易出事的地方因为它不报错只改行为。我最终用的组合是这样开关取值为什么这么设$H-短字符串兼容老代码里string当ShortString用的地方$Z1结构体按 1 字节对齐配合外部 DLL 的 packed 结构$A8常规对齐性能好只有显式packed的才用 1$R-关范围检查Release 版调试版另开$Q-关溢出检查同上$W-关栈帧减少开销方便外部调试器接管$D调试版生成调试信息$Z1这一项要特别说。这套源码要和外部 DLL 交换结构体DLL 那边是 C 写的默认按 1 字节对齐压紧。如果 Delphi 这边按 8 字节对齐字段偏移全错传过去的数据就是垃圾。$Z1的作用就是让所有record默认按 1 字节对齐。代价是访问速度略慢但在这种场景下正确性优先。如果某个 record 需要 8 字节对齐比如里面有Int64且要做原子操作单独用{$A8}包一下。提示$H-这个开关只影响string的默认含义不影响显式声明的AnsiString和UnicodeString。如果你不确定某处该不该开最稳的办法是显式声明类型不要依赖默认值。3.3 输出目录与条件编译宏的配合条件编译宏除了版本判断还有一个很实用的用法区分调试版和发布版的行为。我在.dproj里加了一个DEBUGMODE宏代码里这样用{$IFDEF DEBUGMODE} WriteLog(进入 ProcessPacket长度 IntToStr(Len)); {$ENDIF}好处是日志代码可以随便写发布版编译时整段消失不占空间也不影响性能。比用运行时开关判断要干净因为运行时判断每帧都要多做一次比较。输出目录这块调试版和发布版我分成两个子目录bin\debug和bin\release。看起来多余但你同时开着两个版本对比行为的时候就知道这个隔离有多必要了。IDE 里通过 Build Configuration 切换.dproj里对应不同的PropertyGroup互不干扰。3.4 版本资源与清单文件让 exe 看起来像回事这套源码原来的.res文件是空的编译出来的 exe 属性里什么信息都没有。我补了一个资源文件把版本号、产品名、文件描述填上。这不是面子工程实际有用途——当你在任务管理器里看到一堆同名进程时版本信息能帮你分辨哪个是新编的。更实际的是清单文件。老的 exe 如果没有清单在高版本 Windows 上跑会被当成兼容模式程序某些 API 行为不一样。加一个requestedExecutionLevel为asInvoker的清单能避免不少奇怪问题。清单用文本文件写然后在.dpr里用{$R app.manifest}引用编译时自动嵌入。一个细节改完.res之后一定要完整重编译Build 而不是 Compile因为资源文件在增量编译里有时候不会被重新链接你会以为没生效。4. 第三方组件包从源码到安装这一步是整个过程里最容易卡住的地方因为组件的编译顺序有依赖关系顺序错了就报“找不到单元”而报错信息不会告诉你是顺序问题。4.1 包的编译顺序先编被依赖的再编依赖的Delphi 的.dpk文件里有requires子句声明它依赖哪些包。正确的做法是先画依赖图再按拓扑序编译。这套 BLUE 源码涉及的组件包我理出来的顺序是基础工具包无依赖→ 压缩库包依赖基础包→ 网络封装包依赖基础包→ 界面控件包依赖基础包 VCL→ 主工程。操作上是这样的在 IDE 里打开.dpk右键 Project → Build成功之后右键 Install。Build 和 Install 是两件事Build 只是编译出.bplInstall 才会把组件注册到 IDE 的工具面板。如果你只是要命令行编译Build 就够了如果要在设计器里拖控件必须 Install。一个实操细节安装包之前先把 IDE 关掉装完再开。因为组件注册信息是启动时读的装完不重启设计器里看不到新控件你会以为装失败了。4.2 缺单元对照表把报错翻译成人话编译中最常见的错误就是“找不到单元”。我整理了这张对照表遇到直接查报错信息关键字实际原因处理动作F1026 File not found: xxx.dcu库路径没配或包没装检查 Search Path确认包已 BuildF2063 Could not compile used unit被引用的单元本身有错先单独编译那个单元看真实报错E2003 Undeclared identifier单元版本不对函数签名变了确认加载的是工程内版本不是全局版本E2065 Unsatisfied forward实现部分缺失常见于条件编译分支检查$IFDEF是否把实现也包进去了E2202 Required package xxx not found包未安装到 IDEInstall 该包后重启 IDEE2065这个要特别提一句。老代码里经常有这种写法{$IFDEF SOMETHING} procedure Foo; forward; {$ENDIF} ... {$IFDEF SOMETHING} procedure Foo; begin ... end; {$ENDIF}如果两处的$IFDEF条件不一致比如一处是SOMETHING一处写成了SOMTHING声明有实现没有就报这个错。查的时候不要只看报错行往上翻到声明处对比。4.3 数据库与网络组件的版本匹配这套 BLUE 源码用到的数据访问组件版本差异会直接导致运行期崩溃而不是编译期报错更麻烦。我的经验是组件版本跟着 IDE 版本走XE10 就找明确标注支持 XE10 的版本不要用“应该兼容”的版本。判断方法很简单看组件包源码里有没有针对CompilerVersion的条件分支有就说明作者维护过没有就是老版本改个名字发出来的风险自负。我遇到过一个问题某个数据访问组件在 XE10 下编译完全正常但查询带中文字段时返回乱码查了两天才发现是组件内部把参数按AnsiString传的而数据库连接用的是 Unicode 字符集。这类问题编译器一点提示都不会给。网络组件的坑在端口和缓冲区大小。老代码里的硬编码值是按当年的网络环境定的直接搬到现在的环境里小包多的时候性能很差。我做的第一件事是把这些硬编码常量抽到一个配置文件里运行时可调后面调优不用重新编译。5. 编译通过之后让程序真正跑起来编译成功只是第一步这套 BLUE 源码从“编过”到“能用”还有一段路而且这段路上的问题比编译期更隐蔽。5.1 配置文件的编码与相对路径这套源码读配置用的是老的 INI 读写方式。在 XE10 下TIniFile默认按系统 ANSI 代码页读写如果配置文件是 UTF-8 存的读出来中文全是乱码。我试过三种解法一是把配置文件转成 ANSI 编码简单但不利于跨机器二是改用TMemIniFile配合手动指定编码三是最省事的——配置文件里全部用英文键值中文只出现在日志和界面里。我选了第三条。理由是老工程的配置项本来就不多用英文键名完全够用还避免了不同机器代码页不一致的问题。配置文件的路径处理上我统一用“相对于 exe 所在目录”的方式CfgPath : ExtractFilePath(ParamStr(0)) cfg\server.ini;这样无论从哪里启动都能找到配置。千万不要用GetCurrentDir因为工作目录是可以被外部改的双击启动和从 IDE 启动的工作目录完全不一样这是“IDE 里正常、双击崩溃”的头号原因。5.2 依赖 DLL 的位数与放置依赖 DLL 的排查有个固定套路我一般按这个顺序走先确认位数用系统自带的工具看或者直接看文件大小和导出表再确认放置位置exe 同目录最稳最后确认依赖链DLL 自己还依赖别的 DLL。位数不匹配的报错信息非常误导可能报“找不到模块”也可能是“不是有效的 Win32 应用程序”。判断方法很土但有效32 位 DLL 通常几百 KB 到 2 MB64 位的体积会大一截更靠谱的是看 PE 头用十六进制编辑器打开偏移0x3C处指向 PE 签名之后两字节的 Machine 字段0x014C是 32 位0x8664是 64 位。放置位置上我只信一个原则所有依赖都放 exe 同目录。不要指望系统目录不要指望 PATH因为那些地方是全局的你改了会影响别的程序而且排查时你根本想不起来自己改过。5.3 第一次启动怎么读日志程序第一次跑起来不要在界面上找问题直接去看日志文件。这套 BLUE 源码的日志格式比较原始一行一条没有级别标记我给它加了个简单的前缀约定[I]信息、[W]警告、[E]错误。加完再跑问题定位速度快了不止一倍。看日志的顺序也有讲究。先看最后一行报的什么错然后往上找第一条[E]因为后面的错误往往是第一条的连锁反应。我遇到过典型情况第一条错误是“配置项 xxx 缺失”后面跟着二十条“初始化失败”你去查那二十条全是白费力气。启动失败最常见的原因排序我的经验是配置项缺失 依赖 DLL 没加载 端口被占 数据文件路径不对。前两个占八成先查这两个。6. 报错与排查实录那些文档里不会写的东西下面这些是我这次实际操作里真实撞上的问题按发生顺序记都是能直接抄的。6.1 编译期报错速查现象排查方向我的实际解法一打开工程就报单元找不到全局库路径有旧版本清空 Library Path 里所有第三方路径只留工程级编译到一半报内存不足增量编译产物损坏删掉整个lib目录Build 全量重编编译成功但运行报错版本不对加载了系统目录里的同名 DLL把 exe 同目录的 DLL 提到最前或用依赖查看工具确认加载路径资源文件改了不生效增量编译没重链接资源用 Build 而不是 Compile中文编译报“非法字符”源文件编码是 UTF-8 带 BOM转成 ANSI 或 UTF-8 无 BOM逐个文件确认最后一条值得多说两句。老 Delphi 源文件的编码很混乱有的文件是 ANSI有的是 UTF-8混在一起时编译器会按第一个文件的编码去猜后面的结果就是某些文件里的中文注释变成乱码甚至把注释后面的代码也吞掉。我的处理办法是用脚本批量检测编码统一转成同一种然后在 IDE 里设置默认保存编码防止后面又改回去。6.2 链接期与运行时的隐蔽问题链接期最典型的是“重复定义”。原因是同一个单元被两个不同的包各引用了一份编译器认为有两个同名符号。这种情况在混用“工程内源码”和“已安装的包”时特别容易发生。解法是二选一要么全用包要么全用源码不要混。运行时最隐蔽的问题是内存。老代码里有不少手工GetMem/FreeMem的地方在单线程下没问题一上多线程就随机崩。这类问题的排查不能靠读代码要靠工具开FastMM的完整调试模式在.dpr第一行加SetHeapTraceOutput让它在退出时把泄漏和越界写出来。这套 BLUE 源码我跑了一遍抓出三处越界写全是数组下标少减了 1改完之后随机崩溃消失了。还有一个坑是TStringList的Sorted属性。老代码里把它当字典用设了Sorted : True之后用IndexOf查找性能确实好但如果两个元素的Strings[i]相同而Objects[i]不同Add的时候会被当成重复项丢掉。这类问题不会报错只会“少了几条数据”查起来非常费劲。我的习惯是凡是用TStringList做映射一律显式检查Add之后Count有没有变化。6.3 我自己的避坑清单最后把这套流程里我认为最有价值的几条经验集中列一下都是踩过才知道的。第一条永远保留一份“能编译的原始状态”。我把刚解压、未做任何修改的源码单独存一份任何改动都在副本上做。当改动累积到几十处、突然全崩的时候你可以快速二分定位是哪一批改坏的。没有这个基线你只能靠记忆而记忆在连续折腾八小时之后是不可靠的。第二条一次只改一类东西。我见过有人一次性把编码、路径、编译开关、第三方组件全换了然后编译失败完全不知道是哪个引起的。我的节奏是先让工程能在 IDE 里加载不改代码再让它能编译只改路径再让它能链接只装组件最后让它能跑只改配置。每一步成功都记一次出问题回退一步。第三条报错先看第一条别看最后一条。编译器的错误输出是有连锁的第一条往往才是根因。这条在 Delphi 上尤其明显因为一个单元找不到后面引用它的十几个单元都会报错。第四条用命令行编译做最终验证。IDE 里编译成功不代表命令行也能成功因为 IDE 会带上它自己的一组默认路径。最终交付前我一定在干净的命令行里跑一遍call D:\Dev\DelphiXE10\bin\rsvars.bat msbuild BLUE.dproj /t:Build /p:ConfigRelease /p:PlatformWin32 /v:minimalrsvars.bat会设置好环境变量msbuild走的是和 IDE 完全一致的编译引擎。这一步能过才算真的“从零到可用”。我还习惯把这条命令写进一个批处理文件配合删除lib目录的动作做成“一键全量重编”给别人交付时省掉一堆解释。第五条把配置项集中管理。这套 BLUE 源码原来的配置散落在好几个单元里有的在initialization段硬编码有的从 INI 读。我花时间把它们全抽到一个单元里统一从配置文件读读不到就给默认值并打日志。这个改动看起来和“编译”无关但它让后面所有的调试都变得可控——出问题时你能确定地知道当前生效的是哪个值。第六条别急着优化。老代码里有很多看起来“低效”的写法比如循环里频繁创建对象。编译通过、能跑之后很容易忍不住去改。我的建议是先别动把功能验证完整把日志跑通确认行为符合预期再去碰性能。因为一旦你改了逻辑又同时改了性能出了问题分不清是哪边引起的。这套流程走完我手上这份 BLUE 源码从解压到能跑总共花了大约两天其中真正编译的时间不到两小时剩下的全在处理环境、编码和依赖。第二天下午我把整个目录打包换了一台从没装过 Delphi 的机器重新走了一遍从装 IDE 到程序跑起来用了四十分钟说明前面踩的坑确实都填上了。剩下没解决的只有一件事那几个内联汇编的钩子调用在 32 位下能跑但性能瓶颈也在这儿如果哪天真的需要上 64 位那部分得整体重写成 Pascal 加外部库调用工作量不小暂时没有动的必要。