Delphi 12.3与Lazarus共用UniDAC源码：跨IDE数据库访问方案

简介一份基于 Delphi 12.3 的 UniDAC 与 FPC 数据库访问控件合集面向需要在 Object Pascal 环境中实现跨平台数据库连接与开发的程序员尤其适合使用 Rad Studio 12.3 或 Lazarus/FPC 进行项目构建的中高级开发者。压缩包共收录 2000 个文件整体约 85.73MB核心为 996 个 ppu 编译单元与 923 个 o 目标文件可满足直接链接调用需求另有 17 个 sql 脚本、54 个 rsj 资源映射文件及 html/pdf/txt 文档便于查阅接口用法与工程结构。包内预览可见历史记录、帮助说明与库文件列表说明这份资料既提供可编译链接的预构建产物也保留了必要的文档索引。已有 125 人学习浏览适合正在搭建数据库访问层、需要离线控件单元来加速工程编译的 Delphi 开发者可明显减少手动适配与查找接口的时间成本。1. Delphi 12.3 下的 unidacfpc.zip 是什么一份源码同时喂给两套 IDEDelphi 12.3 的开发者第一次看到 unidacfpc.zip 时通常会愣一下fpc 不是 Lazarus 那边的东西吗跟 Delphi 有什么关系实际工作中我同时维护一个 Delphi 12.3 写的 Windows 服务端和一个 Lazarus 编译的客户端工具两边都要访问 MySQL 和 SQLite数据库访问逻辑如果各写一套改一个字段名就要同步两处。unidacfpc.zip 的价值恰好在这里它装的是 UniDAC 的源码版核心组件仍然是 TUniConnection、TUniQuery、TUniScript 这一套但包工程同时带了 .dpkDelphi 用和 .lpkLazarus 用。也就是说连接参数、事务代码、SQL 文本可以跨两套 IDE 保持一致。适合手里正好有 Delphi 12.3 和新老 FPC 项目、想把数据访问层统一起来的人。这篇笔记按安装、连接配置、交叉编译、排错的顺序写照着走完本机就能跑起最小示例。2. 把 unidacfpc.zip 装进 Delphi 12.3解压、Library 路径与包注册2.1 为什么 Delphi 12.3 要源码版而不是预编译版UniDAC 在 Devart 官网提供两种形态安装程序版和源码 zip 版。unidacfpc.zip 从命名看属于后者并且带了 fpc 后缀说明它额外保留了 Lazarus 包工程。这里有个关键选择Delphi 12.3 的 RAD Studio 对 BPL 包的版本检查很严格预编译版里附带的 DCU/BPL 是针对特定 Delphi 版本生成的直接拿来 Add 进 12.3很容易碰到 “Package ... was compiled with a different version of ...” 这类错误。源码版拿到手的是 .pas、.dpk、.lpk没有字节码兼容性问题遇到新 IDE 自己重编一遍即可。我一般不建议在 Delphi 12.3 里强行安装给旧 Delphi 做的预编译安装包。源码版多花两分钟编译换来的是路径可控、可查、回退方便。这个 zip 里既有 .lpk 又有 .dpk意味着 Lazarus/FPC 和 Delphi 12.3 共用同一批 Source 下的 .pas 文件业务层代码不会因为 IDE 不同而分叉这是它比安装程序版更适合跨平台团队的核心原因。2.2 解压后的目录结构和 Library 路径配置把 zip 解压后先别急着打开 IDE花两分钟看清目录结构。常见布局是四块目录作用安装时怎么用Source核心单元例如 UniDAC.pas、UniConnect.pas加入 Delphi 的 Library path 和 Browsing pathPackages按 IDE 分放的 .dpk / .lpk 工程Delphi 编译 .dpkLazarus 编译 .lpkDemos各种数据库的示例工程对照学习连接参数排错时抄配置Docs参数说明文档查 SpecificOptions 各驱动支持项下一步是把 Source 路径告诉 Delphi 12.3。打开 IDE 后进入 Tools Options Environment Options Delphi Options Library把解压目录下的 Source 完整路径加到 Library path。这一步的细节决定后面会不会花一小时找错路径写到...\unidacfpc\Source这一层就够不用再往下钻到子目录另外把同一路径也加到 Browsing path否则编辑器跳转和代码提示不认编译时报的却是 “Unit not found: UniDAC”。提示Library path 管编译期查找单元Browsing path 管编辑器导航。两条都填后面少折腾。2.3 编译并注册 .dpk 到组件栏路径配好后执行 Component Install Packages Add定位到 Packages 目录下对应 Delphi 12.3 的 .dpk 文件。这里有一个常见分歧有人直接 Add有人先 Open 再 Build。我常用的是先把 .dpk 打开右键 Project Build确认编译零错误后再 Install。Add 之后再编译一旦报错IDE 会进入半注册状态反而难收拾。编译时如果提示缺某个 unit九成是 2.2 的 Library path 没配好回到那里检查如果提示某某符号重名通常是本机以前装过其他版本的 UniDAC残留的 BPL/DCP 还在路径里后面第 5 章会专门讲。注册成功后Tool Palette 里搜 TUni能看到 TUniConnection、TUniQuery、TUniScript、TUniSQLMonitor 等组件到这一步安装就算完成了。2.4 最小连接测试用 SQLite 验证整条链路装完组件不能只看图标跑一个最小连接最稳。我习惯先用 SQLite 做验证因为它不需要任何外部客户端库环境问题最少。放一个按钮写这段代码procedure TForm1.ButtonConnectClick(Sender: TObject); var DB: TUniConnection; begin DB : TUniConnection.Create(nil); try DB.ProviderName : SQLite; DB.Database : C:\temp\test.db; DB.SpecificOptions.Values[Direct] : True; DB.Connect; ShowMessage(连接成功版本 DB.ServerVersion); finally DB.Free; end; end;这段代码主要做三层验证其一ProviderName 能不能被 IDE 正确识别如果包没注册好这里会直接编译报错其二SpecificOptions 的键值写法对不对UniDAC 用这种方式传驱动独立参数不是每个属性都有可视化编辑器其三ServerVersion 在连接成功后才有效出现异常说明连接链路本身有问题。拿 SQLite 跑通后再切 MySQL 或 PostgreSQL后续的排错范围就小很多。3. 连接配置的落地参数ProviderName、直连模式和字符集怎么设3.1 ProviderName 先选对连接信息才有意义UniDAC 的连接入口有两条路一条是 TUniConnection 上独立的 Server、Port、Database、Username、Password 属性另一条是 ConnectString 字符串。两条路最终都汇到 ProviderName 决定的驱动上。实际落地时我建议先设置 ProviderName原因很直接设计期下拉框、属性编辑器、SpecificOptions 的提示列表都依赖这个值ProviderName 选错后面所有参数提示都会跟着错位。ProviderName 的取值和驱动对应关系常用的列一张表ProviderName对应数据库Direct 模式注意事项SQLiteSQLite 3无需外部 DLL最省事MySQLMySQL / MariaDBDirectTrue 仍需 libmysql.dll 或 libmariadb.dllPostgreSQLPostgreSQLDirectTrue 一般需要 libpq.dllOracleOracle多数环境需要 OCI 相关库注意 32/64 位匹配SQL ServerMicrosoft SQL Server通常走 OLEDB/ODBC 桥接按目标机位数配置FirebirdFirebird / InterBase通常需要 fbclient.dll这里有个容易踩的命名坑UniDAC 里 SQL Server 的 ProviderName 写成SQL Server不是常见的MSSQL或Microsoft SQL Server。写错时 IDE 不报错运行时才提示找不到 Provider属于典型的黑匣子问题。连接字符串写法与属性赋值不同属性用 Server字符串里用 Data Source。我常用的写法是UniConnection1.ProviderName : MySQL; UniConnection1.ConnectString : Provider NameMySQL;Data Source127.0.0.1;Port3306; Databaseinventory;User IDdev;Passworddev123;Charsetutf8mb4;这段代码里 ConnectString 是一个分号分隔的键值串键名和 TUniConnection 的属性名不完全一致Data Source 对应 Server 属性User ID 对应 Username 属性。新手往往照属性名去写结果驱动识别不出来。我一般把 ConnectString 用于配置文件持久化把属性赋值用于设计期快速切换两种方式混用时要确认最终以哪份为准避免代码里赋值一套、配置文件里又一套。3.2 直连模式什么时候开什么时候关UniDAC 的 Direct 模式是它区别于很多数据库组件的卖点但这个词经常被误解成“免装客户端”。Direct 模式只是在库层面绕过了厂商的中间层底层 C 库该加载还是会加载。以 MySQL 为例把 SpecificOptions 里的 Direct 设成 True连接时仍然需要 libmysql.dll 或 libmariadb.dll 在场否则初始化直接失败。UniConnection1.ProviderName : PostgreSQL; UniConnection1.Server : 10.0.0.8; UniConnection1.Port : 5432; UniConnection1.Database : erp; UniConnection1.Username : app; UniConnection1.Password : app123; UniConnection1.SpecificOptions.Values[Direct] : True; UniConnection1.Connect;为什么常见做法是保留 Direct 开关而不是让它常开因为在正式内网环境里很多团队已经部署了厂商客户端并维护了 tnsnames.ora、pg_hba.conf 等配置这时候走客户端库的连接名解析比在每台机器上手工指定主机端口更省力。Direct 模式适合的场景是临时测试、交付给不带客户端的现场、以及 CI 环境里跑自动化用例。这里有个血泪经验现场机器如果位数是 32 位而 exe 是 64 位DLL 加载失败是必然的后面第 5 章再展开。3.3 字符集、UseUnicode 与事务边界UniDAC 连接里的文字乱码大多数不是控件坏了而是字符集参数没有对齐。Delphi 12.3 的 string 是 UnicodeStringUniDAC 在内部会把字符串转成目标数据库客户端库期望的编码。如果连接串里不指定 CharsetMySQL 默认按 latin1 走中文读写就变成问号和乱码。我在连接串里固定写Charsetutf8mb4MySQL 8 以上尤其要坚持时不时的编码玄学基本就此消失。事务边界同样属于连接级参数。TUniConnection 默认 AutoCommit 为 True简单查询无所谓但有写入操作时我建议显式关掉UniConnection1.AutoCommit : False; try UniConnection1.StartTransaction; UniQuery1.SQL.Text : insert into orders(id, amount) values(:id, :amount); UniQuery1.ParamByName(id).AsInteger : 1001; UniQuery1.ParamByName(amount).AsFloat : 299.9; UniQuery1.ExecSQL; UniConnection1.Commit; except UniConnection1.Rollback; end;AutoCommit 设为 False 后连接上的写操作会进入未提交状态直到 Commit 或 Rollback。这个行为在 Delphi 12.3 和 FPC 侧是一致的恰好符合“一份源码两套 IDE 共用”的初衷。事务与字符集参数都建议在连接建立前一次配完不要指望连接已经打开后再改UniDAC 对运行中的参数变更支持有限改完经常要重连才生效。4. 在 FPC/Lazarus 侧复用同一份源码两组编译参数与代码分支4.1 用 .lpk 安装与命令行编译的路径参数前面装的是 Delphi 12.3 侧这一节说 Lazarus/FPC 侧怎么接手同一份源码。Lazarus 的包管理与 Delphi 不同走的是菜单 Package Open Package File文件类型选 *.lpk在 unidacfpc 的 Packages 目录下找到对应版本后打开先 Compile 再 Install。安装成功后新建工程时检查 Project Project Options Paths Other unit files 里是否自动加入了 Source 路径。Lazarus 有时不会自动追加没有就手动加这一步漏掉的话FPC 编译器找不到 UniDAC 的单元。如果你习惯用命令行编译最小命令大致长这样fpc -MObjFPC -g -O1 \ -FuE:\dev\unidacfpc\Source \ -FuE:\lazarus\lcl\units\x86_64-win64 \ uniTest.dpr-Fu 是 FPC 的单元搜索路径参数可以多次出现路径含空格时用双引号包起来。-MObjFPC 指定的是 Object Pascal 语法模式Lazarus 默认用这个模式编译不加的话遇到带 class 关键字和异常处理的代码会报语法错误。-g 生成调试信息-O1 开基础优化。路径里的 x86_64-win64 取决于 Lazarus 配置的目标 CPU32 位工具链对应的是 i386-win32。这条命令的作用是验证 unidacfpc 的单元能被 FPC 正确找到编译输出一致后再回到 IDE 里做后续开发。常见做法是先用 .lpk 在 IDE 里跑通再用命令行做持续集成。命令行编译对路径顺序敏感如果本机同时装了多个版本的 Lazarus-Fu 的顺序必须是 unidacfpc 在前、LCL 在后避免编译器取到旧的 DCU。4.2 Delphi 12.3 与 FPC 的字符串差异写分支而不是写两套函数Delphi 12.3 的 string 默认是 UnicodeStringFPC 在多数模式下默认是 AnsiString。两边处理同一段中文字段时会出现一侧正常、一侧乱码的现象而且问题不一定出在 UniDAC而是 string 类型语义不同。我在共享源码里用条件编译直接切分var S: string; begin {$IFDEF FPC} S : UTF8ToAnsi(Trim(qry.FieldByName(name).AsString)); {$ELSE} S : Trim(qry.FieldByName(name).AsString); {$ENDIF} end;这段代码的意义在于FPC 分支里显式把 UTF-8 转成 AnsiDelphi 分支保留原生 UnicodeString。不要在两边都写AnsiString强转Delphi 12.3 下强转会丢字符FPC 下不转又可能乱码。{$IFDEF FPC} 是 FPC 预定义的条件编译符号Delphi 编译器会忽略 FPC 分支里的代码两边互不干扰。类似的差异还体现在字符串拼接和 Chr 函数上凡是和外部系统交换数据的入口我都用独立函数封装中间加一个条件编译分支不要散落在业务代码里。4.3 FetchAll 和游标取舍报表与在线浏览是两种玩法TUniQuery 的 FetchAll 属性是 UniDAC 在结果集处理上的一个关键开关。默认情况下查询是边取边用的流式游标对大结果集内存友好但如果把 TUniQuery 直接绑给 DBGrid或者在一次遍历里又去执行别的 SQL游标状态会变得微妙偶发异常时很难一眼定位。我的习惯是两种场景分开处理报表、导出、批量计算这种“一次全取”的任务把 FetchAll 设成 True行为确定遍历多少行就是多少行在线分页浏览则设 False配合 SQL 层的 Limit/Offset 做物理分页不要让一个连接长期挂着一个大结果集不释放。FetchAll 的设置直接写在 TUniQuery 上UniQuery1.FetchAll : True; UniQuery1.SQL.Text : select id, name, created_at from orders where created_at :d1; UniQuery1.ParamByName(d1).AsDateTime : IncDay(Now, -7); UniQuery1.Open;这段代码先决定 FetchAll 再执行 SQL是因为 FetchAll 在 Open 之前设置才生效。参数用 ParamByName 绑定而不是拼 SQL 字符串既避开日期格式坑也让 FPC 和 Delphi 两侧的代码保持一模一样。Delphi 12.3 和 FPC 对这个属性的行为一致跨 IDE 切换时不产生额外维护成本。5. unidacfpc 的常见坑与排查从重复安装到 DLL 缺失的 5 个实录5.1 安装期重复注册、路径残留与编译错乱坑 1重装或升级后 IDE 报 TUniConnection 已注册。现象打开包管理器看到同类组件出现两条记录把新包 Add 进去时 IDE 直接拒绝提示组件名已存在。原因旧版本的 BPL/DCP 文件残留在 IDE 的库目录里Delphi 12.3 在启动时把这些旧包也加载了新包的同类组件注册时发生名称冲突。解决先到 Component Install Packages 里移除所有 UniDAC 相关项关闭 IDE删除%LocalAppData%\Embarcadero\BPL或对应版本目录下的旧 BPL/DCP 文件再重新打开 IDE 安装新包。删除前确认只删 UniDAC 相关文件不要碰其他控件的 BPL。坑 2Library path 加了却仍然报 Unit not found: UniDAC。现象代码里 uses UniDAC编译时 IDE 提示找不到单元但回到 Tools Options 查看路径确实已经填了。原因路径填到了 Browsing path 那一行或者填对了行但 Source 路径写到子目录层级不对。Library path 才是编译期查找单元的地方Browsing path 只服务编辑器和代码提示。解决打开 Tools Options Environment Options Delphi Options Library把...\unidacfpc\Source完整路径放进 Library path 输入框而不是 Browsing path。补好后先关闭再重开工程IDE 对 Library path 的缓存有时不会立刻刷新。5.2 运行期DLL 缺失、位数错配、字符集乱码坑 3MySQL 连接初始化失败报找不到 libmysql.dll 或 libmariadb.dll。现象ProviderName 设为 MySQLSpecificOptions 里 DirectTrue连接时抛异常错误信息指向某个 DLL 文件不存在。原因Direct 模式只是绕过客户端中间层仍然需要调用 MySQL 的 C 客户端库而且 DLL 的位数必须和 exe 一致Delphi 12.3 编译出的 64 位程序配 32 位 DLL加载必然失败。解决把对应版本的 libmysql.dll 或 libmariadb.dll 放到 exe 同目录或加入系统 Path。先确认 exe 是 64 位还是 32 位再选同位数 DLL。经验是优先和线上 MySQL 版本匹配不要为省事从网上下个来路不明的 DLL运行期诡异问题多半出在这里。坑 4插入的中文变成问号或乱码查询结果也对不上。现象界面录入中文提交到 MySQL 后库里存的是 ???重新读出来也是乱码。原因连接字符集没有对齐。MySQL 默认连接字符集可能是 latin1Delphi 12.3 侧传的是 UnicodeString两边转换没有统一到 utf8mb4。解决连接串里显式加Charsetutf8mb4同时检查 UniDAC 的 UseUnicode 选项是否按项目要求打开。改完必须重连已建立的连接不会自动应用新字符集。SQLite 场景则确认数据库文件本身的编码UniDAC 侧保持一致即可。坑 5Direct 模式连不上客户端模式反而正常。现象测试环境把特定数据库的 Direct 设为 True报错提示找不到某个客户端库去掉 Direct 后连接成功。原因PostgreSQL 的 Direct 模式依赖 libpq.dllOracle 的直连依赖 OCI 相关组件这些库不是每台机器都有也不是每个版本都兼容。解决检查目标机的 C 库是否安装、位数是否匹配。如果现场环境已经部署了厂商客户端干脆保持 DirectFalse让 UniDAC 走已存在的客户端配置。交付内网环境时后者通常比临时找 DLL 更省心。排查通用手段出现上述运行期问题时我一般先开 TUniSQLMonitor把连接过程中的 SQL 和状态事件打印到日志再下结论。procedure TForm1.UniSQLMonitor1SQL(Sender: TObject; Text: string); begin Memo1.Lines.Add(FormatDateTime(hh:nn:ss, Now) Text); end;TUniSQLMonitor 是 UniDAC 自带的事件型追踪组件OnSQL 事件在驱动层执行 SQL 时触发Text 参数里能看到实际下发的语句和错误上下文。把这段日志和上面几个坑对照通常几分钟就能定位到 DLL、字符集还是事务边界的问题。6. 进阶调试用 TUniSQLMonitor 给连接过程留一份可回放日志前面第 5 章已经提了 TUniSQLMonitor 的基础用法这里再往前推一步把它做成一个按天轮转的日志文件让现场问题有据可查。用 UniDAC 连数据库的服务最怕用户报一句“连不上”但又说不出完整报错。给程序加一个可开关的日志记录接上 monitor 事件现场就能留下一份可回放的连接时间线。procedure TForm1.LogSQL(Sender: TObject; Text: string); var F: TextFile; LogName: string; begin LogName : unidac- FormatDateTime(yyyymmdd, Now) .log; AssignFile(F, LogName); if FileExists(LogName) then Append(F) else Rewrite(F); try WriteLn(F, FormatDateTime(hh:nn:ss.zzz, Now) | Text); finally CloseFile(F); end; end;这个片段把日志文件按天切分同一天内走追加跨天自动换新文件。yyyy-mm-dd 格式直接体现日期小时分钟带上毫秒排错时能精确对应到某一次连接动作。正式发布时我给界面留一个注册表开关控制日志开关现场出问题让对方把 unidac-日期.log 发回来多数时候填好感再对照日志里最后的失败动作问题就落到具体参数上。这个习惯我保留了很多项目比现场远程调试省力得多。希望帮到你。本文还有配套的精品资源点击获取