简介本资源是面向Delphi开发者尤其适配Delphi 12.3的Python集成开发套件解决原生Delphi调用Python解释器、双向交互及扩展开发的技术难题。Python for DelphiP4D提供低层Python C API封装与高层Delphi-Python对象互通能力支持脚本执行、模块/类型定制、DLL形式Python扩展开发等核心场景。压缩包共499个文件含137个Pas单元核心组件逻辑、53个DProj工程文件多版本兼容构建、41个DFM窗体可视化控件设计、26个Py脚本示例与测试用例及配套资源文件整体7.62MB结构完整、开箱即用。已有80人学习下载资源包含全版本构建批处理如BuildAllVersions.bat、单元测试工程VarPythUnitTest.bdsproj及大量图标与位图资源如TPYTHONENGINE.bmp便于快速理解组件功能布局与集成路径适合中高级Delphi开发者开展Python混合编程实践与二次开发。 如果你在 Delphi 项目里碰过需要调用 Python 生态库的需求大概率会在网上搜到python4delphi-master.zip这个包。它不是什么官方商业控件而是开源社区里 Python4Delphi简称 P4D的源码压缩包专门解决一个很实际的问题在 Delphi 写界面和业务逻辑但又要复用 Python 那边的 NumPy、Pandas、PIL、OpenAI SDK 或者各种现成脚本。我这次在 Delphi 12.3 环境里重新把这套控件装上并且跑通了一个完整的 Python 回调 Delphi 的 demo整个过程踩了不少坑尤其是网上那些教程大多是老版本和 Delphi 12.3 的兼容性处理有出入。这篇文章就把我实际操作的步骤、参数配置和遇到的各种问题整理出来给同样需要在 Delphi 里塞 Python 引擎的同学一点参考。1. 项目整体设计与方案选型1.1 Python4Delphi 到底解决了什么问题很多人第一次听到“Delphi 控件之 python4delphi”会觉得奇怪Delphi 和 Python 不是两门语言吗怎么还能做成控件其实 P4D 做的不是把 Python 翻译成 Pascal而是通过 Delphi 的组件封装把 Python 解释器作为动态库嵌入到 Delphi 程序里。你可以把它理解为在 Delphi 窗体上放一个TPythonEngine组件这个组件内部加载 python3xx.dll然后在运行时由你的 Delphi 程序调用 Python 的 C API执行 Python 脚本、绑定 Python 函数、传递参数和对象。举个例子你的 Delphi 程序收到了用户上传的 Excel 文件需要做复杂的数据清洗和统计分析。在纯 Delphi 环境里写这种逻辑会非常痛苦StatLib、TeeChart 等方案虽然能用但生态远不如 Python 的 Pandas 丰富。而有了 P4D你只需要在 Delphi 里执行一段 Python 脚本把 Excel 路径传过去脚本调用 Pandas 处理完再把结果返回给 Delphi。这样既保留 Delphi 在桌面端、数据库、系统底层调用方面的优势又能借用 Python 几年的库积累。另一种常见的替代方案是直接让 Delphi 程序启动一个 Python 进程做子进程通信通过标准输入输出或者 HTTP 接口交互。这种方式也能实现集成但存在几个问题进程启动开销大、数据序列化麻烦、调试不方便、状态难以共享。P4D 采用的是进程内嵌入性能好得多数据天然共享内存而且 Python 的异常可以以对象形式传到 Delphi 侧处理。1.2 为什么选择 zip 源码包而不是 GetIt 安装关于安装方式很多人会问既然 Delphi 12.3 自带的 GetIt 包管理器里也有 Python4Delphi为什么还要手动下载python4delphi-master.zip我个人的经验是GetIt 里收录的版本往往滞后于 GitHub 主线而且 GetIt 的包安装过程是自动化的不太透明。你根本不知道它把源码放在了哪个目录以后想改源码做二次开发也麻烦。手动下载 master 分支源码的好处是第一你能拿到最新代码新版本通常支持更新的 Python 版本比如 3.11、3.12 的 API 变化比较大旧版 P4D 可能加载不了新解释器第二你可以完整体验编译流程理解哪部分是运行时、哪部分是设计期对后续排错非常有帮助第三源码包里有完整的 Demos 目录这些示例是文档之外最好的学习材料。当然zip 包的方式有个坏处你需要手动处理 Python 环境的位数匹配、DLL 路径、Library Path 配置等问题这些就算老手也很容易翻车。但一旦你把环境配好了后续开发就顺畅了。1.3 Delphi 12.3 与 Python 版本的兼容性分析这里我要重点强调一个概念位数匹配。Delphi 12.3 编译出的 Win32 程序只能加载 32 位 Python DLLWin64 程序只能加载 64 位 Python DLL。这听起来是常识但我在实际操作中真的见过有人用 64 位 Delphi 编译程序然后去加载 python311.dll32位结果运行直接报“无法找到指定的模块”或者内存访问冲突。在 Python 版本选择上我用的是 Python 3.11.9 的 64 位版本。为什么不用 3.12 或 3.13因为 P4D 的主线虽然跟进得快但某些第三方扩展库比如 numpy、pandas 的预编译 wheel对最新 Python 版本的支持会滞后。用 3.11 是比较稳妥的生态成熟、P4D 支持也好。如果你要用的 Python 库要求更高版本建议先看 P4D 仓库里 README 文件描述的兼容版本表格。Delphi 12.3 对应的编译器和运行时基础库跟旧版 Delphi比如 XE8、10.4差别不小所以直接用老版本的 P4D 源码包打开很可能会编译不过。我这次用的就是 master 分支最新代码这样跟在 12.3 上编译才能顺利通过否则会遇到很多 Winapi.Windows 签名变化带来的编译错误。2. 环境准备与编译安装2.1 前置依赖清单在动手之前先把下面的工具和依赖准备好省得到时候装一半发现缺东西依赖项版本建议说明Delphi12.3 或 12.2我用的是 12.3理论上 12.x 都可以Python3.11.x与编译目标位数一致官方 python.org 安装包不是微软商店版Git最新版用于拉取源码或者直接下载 zip 包7-Zip / WinRAR最新版解压 zip 包避免 Windows 自带解压出错cmake/msbuild看实际项目部分 P4D demo 需要核心安装不需要Python 安装的时候有一个关键选项勾选“Add python.exe to PATH”不然后面配置环境变量很麻烦。另外装 Python 时它默认会安装到一个目录比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\最好把这个路径记下来后面配置DllPath要用。2.2 解压源码包与目录结构解读把python4delphi-master.zip解压到一个路径尽量不含空格和中文的目录比如D:\Components\python4delphi-master。官方推荐路径是C:\Python4Delphi或者类似原因很简单Delphi 的库路径配置如果包含空格某些老版本工具链会把它截断导致找不到 dcu 文件。解压后你会看到几个关键目录Source核心单元源码包括PythonEngine.pas、PythonVersion.pas、PythonGUIInputOutput.pas等。这块是整个控件的发动机不建议随便修改。Packages各版本 Delphi 的包工程文件。进去会看到Delphi、Delphi10、Delphi11、Delphi12等子目录每个子目录里含有设计期包和运行期包的 .dproj 文件。Demos示例项目非常实用建议全部跑一遍。Documentation官方文档有详细的 Python 与 Delphi 类型对应关系说明。Tests自动化测试项目不是必须的但可以帮你验证安装是否正确。2.3 编译安装全流程重点来了。打开 Delphi 12.3依次点击File Open Project定位到Packages\Delphi12目录。如果找不到 Delphi12 目录说明你拉的不是最新 master或者仓库结构变了现在一般叫Delphi12或者Delphi12_xx是分支号。打开后你会看到一个运行期包比如Python4Delphi_1250.dproj之类还有一个设计期包。编译顺序有讲究先编译运行期包runtime package再编译设计期包design package。选中运行期包右键Compile如果顺利的话会在输出目录生成Python4Delphi_1250.bpl和一系列.dcu文件。然后再切到设计期包同样编译。我这边编译时遇到两个问题一是某些代码用到了TStringList.LineBreak的新特征Delphi 12.3 的 RTL 已经改了默认值二是源码里有个别 DLL 导入函数声明和最新的 Windows SDK 头文件有冲突。这两个问题都比较新如果你用的版本比我新可能已经修掉了。如果还报错可以把具体错误信息贴到 P4D 的 GitHub Issues 搜索基本都能找到解决方案。编译通过后还需要把源码目录加到 Delphi 的 Library Path 里否则新建工程时 IDE 找不到这些单元。操作路径是Tools Options Environment Options Delphi Options Library在Library path里添加Source目录路径。注意要同时在 Active platform 设置为 64-bit 和 32-bit 两种配置下分别添加不然切换编译平台时还是会提示找不到PythonEngine.dcu。最后确认一下设计期包是否安装成功。在 IDE 最右侧的组件面板里找一下正常情况下会多出一个Python标签里面有TPythonEngine、TPythonModule、TPythonDelphiVar、TPythonInputOutput等组件。这是最直接的验证方式。2.4 安装验证新建项目跑第一个 P4D 程序安装成功不代表万事大吉我建议立刻新建一个 VCL 项目验证一下。窗体上放一个TPythonEngine、一个TMemo和一个TButton然后在按钮的OnClick事件里写procedure TForm1.Button1Click(Sender: TObject); begin PythonEngine1.ExecString(print(Hello from Python)); end;如果点击按钮后 Python 输出能在TMemo配合TPythonInputOutput组件里显示出来说明整条链路没问题。这里有个小技巧想让 Python 的print输出到 Delphi 的 Memo必须把TPythonInputOutput组件的Output事件里写入Memo1.Lines.Add否则 Python 的输出默认去控制台窗口了你根本看不见。我第一跑的时候就没接这个组件结果按钮点了半天没反应以为是控件坏了后来才发现是输出没接。3. 核心功能实操与代码细节3.1 初始化 Python 引擎的推荐配置TPythonEngine的属性非常多但真正影响初始化成败的其实就几个DllName、DllPath、AutoFinalize和UseLastKnownVersion。我直接说一下我最终采用的配置属性推荐值说明DllNamepython311.dll要和 Python 版本对应DllPathC:\Users...\Python311\或 Python 安装目录指向 python DLL 所在目录AutoFinalizeTrue程序结束时自动释放 Python 解释器避免内存泄漏UseLastKnownVersionFalse手动指定版本避免自动探测到错误 DLLRegSize864 位程序必须设为 832 位程序设为 4DllPath这里值得多说两句。如果你把 Python 装到了系统 PATH 里理论上可以不填 DllPath让系统去搜索。但在实际发布程序时目标用户机器上未必装了 Python所以更稳妥的做法是把 python311.dll 和必要的标准库目录一起打包到你的程序目录然后把DllPath指向你程序所在的相对路径。这样做能让你的 Delphi 程序变成一个自包含的应用不依赖目标机器预装 Python。Python 本身依赖一堆标准库文件和.pyd扩展模块python311.zip那段也要处理好。把 Python 安装目录里的Lib文件夹整体拷贝到你的程序目录并确保PythonHome属性指向程序目录。如果PythonHome配得不正确Python 解释器启动时会报ModuleNotFoundError: No module named encodings这个报错非常常见网上一搜一大把基本上都是路径没配对。3.2 执行 Python 脚本并捕获输出P4D 里执行 Python 代码有两种方式ExecString用于执行一行或一段完整脚本EvalString用于执行表达式并返回结果。前者适合过程式调用后者适合拿到返回值。要捕获 Python 的标准输出和错误输出必须用到TPythonInputOutput组件。它有几个关键事件OnSendUniDataPython 的print输出会触发传入AText参数把它追加到你的 Memo 或日志控件即可。OnReceiveUniDataDelphi 侧往 Python 标准输入写数据时触发一般用于交互式场景。OnTracebackPython 异常时触发包含 traceback 信息对调试非常重要。我建议把OnSendUniData和OnTraceback都接上分别处理常规输出和异常输出这样 Python 脚本出错时你能在界面上看到完整堆栈而不是一个孤立的神秘错误码。还有一个细节ExecString执行多行代码时必须保证代码的缩进是正确的。字符串里写多行脚本时我习惯用sLineBreak来拼接行而不是硬编码#13#10这样代码在不同操作系统和 Delphi 版本之间移植更安全。3.3 Delphi 与 Python 互相调用的三种方式P4D 的核心价值在于双向调用。我总结一下常见的三种方式方式一Delphi 执行 Python 脚本并读取变量PythonEngine1.ExecString(result 6 * 7); var LResult: Variant; LResult : PythonEngine1.EvalString(result); ShowMessage(LResult);这里要点EvalString返回的是Variant类型可以自动转成 Delphi 的整数、字符串、浮点数等基本类型。但如果 Python 变量是列表或字典直接转成 Variant 会遇到麻烦这个时候最好用TPythonDelphiVar或者 Python 侧的 json 序列化。方式二注册 Delphi 函数供 Python 调用这是最实用的场景也是我强烈推荐掌握的能力。把 Delphi 函数暴露给 Python本质上是写一个TPythonModule的OnPythonModuleInitialization事件调用Module.AddMethod注册。procedure TForm1.PythonModule1Initialization(Sender: TObject); begin PythonModule1.AddMethod(AddNumbers, procedure(aArgs: PPyObject; aResult: PPyObject) begin // 解析 Python 传入的参数做计算把结果写回 aResult end); end;参数解析和结果返回需要用到 P4D 提供的 API比如PyArg_ParseTuple和Py_BuildValue。这块代码写起来比 Delphi 常规代码要低层一些但看懂 P4D 自带的Demos\DelphiToPython例子基本就会了。方式三通过 TPythonDelphiVar 共享对象TPythonDelphiVar可以看作一个双向桥Delphi 侧给它赋值Python 脚本里同名变量就能直接读Python 脚本里改了同名变量Delphi 侧事件能感知变化。这个机制避免了每次都要EvalString的繁琐适合频繁传递状态变量的场景。3.4 实际业务场景在 Delphi 中调用 NumPy / Pandas / PIL光会 Hello World 远远不够真正的价值在于调用第三方库。我这里以一个真实案例来说明Delphi 程序读取图片路径调用 Python 的 PIL 库生成缩略图并保存然后 Delphi 侧显示新图片路径。from PIL import Image def make_thumb(src, dst, size): img Image.open(src) img.thumbnail((size, size)) img.save(dst)Delphi 侧就是组织好src、dst、size参数然后把这段脚本传给ExecString执行。这个例子里最关键的是Python 的第三方库必须安装到 P4D 能加载到的站点包目录里。如果你希望发布后不依赖目标机器可以用pip install --target.\pylibs pillow把依赖拉到程序目录然后在脚本开头加一句import sys sys.path.insert(0, r.\pylibs)这样你的程序自带库目录不污染系统环境也不会被系统环境的包冲突影响。这是我多次踩坑后总结出来的发布策略自包含目录是王道。4. 完整案例Delphi 界面 Python 数据处理回传4.1 场景设定与界面设计为了让整个流程更直观我做一个完整的例子Delphi 窗体上放一个按钮、一个 Edit输入 CSV 文件路径、一个 Memo显示 Python 返回的数据摘要、一个TPythonEngine和一个TPythonInputOutput。点击按钮后Delphi 把路径传给 PythonPython 用 Pandas 读取 CSV 文件计算行数和列数再把结果返回给 Delphi 显示。为什么选这个场景因为它覆盖了三个关键环节参数从 Delphi 传到 Python、Python 执行脚本操作文件、Python 把结果传回 Delphi。这三个环节你做会了其他复杂逻辑基本就是在这个框架里扩展。4.2 核心代码剖析先在 FormCreate 里初始化Options : [foAutoUnload]这个选项确保 Python 引擎在释放时正确卸载 DLL否则反复打开关闭窗体可能出现 DLL 无法重新加载的问题。按钮的 OnClick 事件完整代码如下procedure TForm1.Button1Click(Sender: TObject); var LScript: string; begin LScript : import sys sLineBreak sys.path.insert(0, rC:\pylibs) sLineBreak import pandas as pd sLineBreak df pd.read_csv(r Edit1.Text ) sLineBreak result frows{len(df)}, cols{len(df.columns)}, total{df.shape[0]*df.shape[1]}; PythonEngine1.ExecString(LScript); Memo1.Lines.Add(PythonEngine1.EvalString(result)); end;代码里我特意用了 f-string 和 Pandas 的read_csv这样能确保 Python 3.6 的语法特性没问题。执行ExecString时如果没有异常再用EvalString把 result 变量取回来。这里有一个很重要的细节EvalString必须放在ExecString成功之后否则 Python 命名空间里没有result变量会抛 NameError。4.3 关键属性设置表组件属性值用途TPythonEngineDllNamepython311.dll指定解释器 DLLTPythonEngineDllPathC:...\Python311\指向 DLL 目录TPythonEnginePythonHomeC:...\Python311\配合标准库路径TPythonEngineUseLastKnownVersionFalse锁定版本TPythonEngineRegSize864 位TPythonInputOutputOnSendUniDataMemo1.Lines.Add(AText)捕获 print 输出运行后如果一切正常点击按钮后 Memo 里会打印一行类似rows1000, cols15, total15000的结果。这个例子虽然简单但已经把“Delphi 发起调用 → Python 处理 → 结果回传”完整闭环跑通了。5. 常见问题与排查技巧实录5.1 “控件丢失 / IDE 里找不到组件”类问题这应该是 P4D 用户问得最多的问题尤其是新安装完打开 IDE 才发现组件面板里没有 Python 标签。我遇到过几种情况第一种是设计期包没有正确安装。只编译了运行期包是不够的必须右键设计期包执行Install命令而不是仅Compile。如果只是编译了而没安装IDE 不会注册设计期组件。第二种是 Library Path 没有配置正确。如果编译安装都成功但新建项目时pythonEngine单元找不到那就是 Library Path 漏了。这个路径必须准确指向Source目录。这里还有个容易忽略的点x64 平台和 Win32 平台的 Library Path 是分开保存的两个平台都加上才稳妥。第三种跟热词“delphi 控件版本问题 导致 每次进入ide都丢失控件需要重新放置保存后还是那样”很像。这种奇葩问题往往和 bpl 包的版本冲突有关。一个机器上可能安装了多个 Delphi 版本或者多个版本的 P4DIDE 加载组件时发现同一个类名来自不同的包就会自动停用某个包。解决办法是把旧版本的 P4D 包彻底卸载然后只保留当前版本的。控制面板里的“程序和功能”中如果能看到 Python4Delphi 相关的安装项先卸载掉再到 IDE 的Component Install Packages里确认勾选状态。5.2 Python 环境加载失败类问题这一类的报错非常典型我列一个速查表报错信息原因解决方法无法找到指定的模块DLL 路径错误或位数不匹配检查 DllPath 指向的目录下确实有这个 DLL确认 Delphi 编译的目标平台和 Python DLL 位数一致ModuleNotFoundError: No module named encodingsPythonHome 或标准库路径错误设置 PythonHome 为 Python 安装目录将 Lib 目录拷到程序目录或绝对路径正确引用Python.h 找不到编译期报错没有安装 Python 开发头文件重新运行 Python 安装包勾选“Download debugging symbols”和“Download development binaries”执行时无任何反应输出没有接入 TPythonInputOutput确认 OnSendUniData 事件写入了显示组件另外提一句如果程序里有多个 Python 库同时加载可能因为 DLL 冲突导致模块加载失败。我建议程序里只通过 P4D 加载一份 Python DLL不要再额外加载其他 Python 包否则两个不同版本的 Python DLL 在同一个进程里会打架轻则报错重则崩溃。5.3 崩溃与线程安全问题P4D 是线程不安全的准确来说 Python 解释器在有 GIL全局解释器锁的情况下并不原生支持多线程同时调用。如果你在 Delphi 的工作线程里直接调用PythonEngine.ExecString大概率会闪退或卡死。我遇到过多次这类问题安全做法是所有对TPythonEngine的调用主线程完成或者用一个专有的 TThread 加临界区保护确保同一时刻只有一个线程进入 Python API。如果确实需要异步执行耗时 Python 任务比如训练模型建议借用TThread.Queue把任务切回主线程执行或者用TTask加Semaphore控制并发。 P4D 的 Demo 里没有太多线程相关的示例这块主要靠经验我一开始直接把执行脚本放在后台线程里结果程序无响应排查了很久发现是 Python 在等 GIL而主线程又在等子线程结果形成死锁。5.4 版本迁移与升级注意事项如果你原来用的是旧版 P4D比如 2.x 或更老迁移到新 master 时要注意API 变化挺大的很多方法名、参数类型和异常类型都改了。官方提供了UPGRADE.txt文档里面列出了从旧版到新版的迁移点一定要看。还要注意Delphi 12.3 编译出的 DCU 格式跟 Delphi 11 不兼容。如果你之前用 Delphi 11 编译过 P4D 的 dcu 文件直接复制到 Delphi 12.3 环境里是行不通的必须重新编译。这也是为什么我建议从源码完整编译一次而不是拷贝别人编译好的 dcu。6. 把 P4D 变成你工具箱里的一把瑞士军刀P4D 绝不只是一个“能跑 Python”的玩具控件。我现在的很多项目都是混合架构复杂的业务规则用 Delphi 写数据分析和 AI 推理调用 Python图像处理和 OCR 也交给 Python 的库。只要第一次编译安装成功后续写代码的体验其实很顺因为 Delphi 的强类型和 Python 的灵活性刚好互补。我个人在实际使用中最喜欢的一个小技巧在开发阶段用ExecString动态调试 Python 脚本不用每次改动都重新编译 Delphi。你可以把 Python 脚本放在外部文件里运行时用TFile.ReadAllText读进来再ExecString这样调整 Python 逻辑时完全不碰 Delphi 代码热更新效率极高。还有关于发布部署的建议如果目标机器环境未知我强烈建议使用虚拟环境生成依赖清单用 pip 把依赖打包到程序子目录然后在 Python 脚本开头加sys.path.insert。这个方案我用了大半年算是 P4D 项目落地最稳妥的姿势。如果你准备入手 P4D不要一上来就想着搞多复杂的功能先把最简单的 Hello World 跑通再跑通信中的双向调用然后再逐步加入第三方库。等你把这个链路彻底摸透会发现 Delphi 和 Python 之间的边界几乎消失了——你写的也不再是“Delphi 项目”或“Python 项目”而是一个混合了两种语言优势的完整解决方案。本文还有配套的精品资源点击获取 
长河君 · 2026/8/31 15:42:16 · 阅读 1.2k Delphi集成Python实战：Python4Delphi控件安装配置与双向调用指南
简介本资源是面向Delphi开发者尤其适配Delphi 12.3的Python集成开发套件解决原生Delphi调用Python解释器、双向交互及扩展开发的技术难题。Python for DelphiP4D提供低层Python C API封装与高层Delphi-Python对象互通能力支持脚本执行、模块/类型定制、DLL形式Python扩展开发等核心场景。压缩包共499个文件含137个Pas单元核心组件逻辑、53个DProj工程文件多版本兼容构建、41个DFM窗体可视化控件设计、26个Py脚本示例与测试用例及配套资源文件整体7.62MB结构完整、开箱即用。已有80人学习下载资源包含全版本构建批处理如BuildAllVersions.bat、单元测试工程VarPythUnitTest.bdsproj及大量图标与位图资源如TPYTHONENGINE.bmp便于快速理解组件功能布局与集成路径适合中高级Delphi开发者开展Python混合编程实践与二次开发。 如果你在 Delphi 项目里碰过需要调用 Python 生态库的需求大概率会在网上搜到python4delphi-master.zip这个包。它不是什么官方商业控件而是开源社区里 Python4Delphi简称 P4D的源码压缩包专门解决一个很实际的问题在 Delphi 写界面和业务逻辑但又要复用 Python 那边的 NumPy、Pandas、PIL、OpenAI SDK 或者各种现成脚本。我这次在 Delphi 12.3 环境里重新把这套控件装上并且跑通了一个完整的 Python 回调 Delphi 的 demo整个过程踩了不少坑尤其是网上那些教程大多是老版本和 Delphi 12.3 的兼容性处理有出入。这篇文章就把我实际操作的步骤、参数配置和遇到的各种问题整理出来给同样需要在 Delphi 里塞 Python 引擎的同学一点参考。1. 项目整体设计与方案选型1.1 Python4Delphi 到底解决了什么问题很多人第一次听到“Delphi 控件之 python4delphi”会觉得奇怪Delphi 和 Python 不是两门语言吗怎么还能做成控件其实 P4D 做的不是把 Python 翻译成 Pascal而是通过 Delphi 的组件封装把 Python 解释器作为动态库嵌入到 Delphi 程序里。你可以把它理解为在 Delphi 窗体上放一个TPythonEngine组件这个组件内部加载 python3xx.dll然后在运行时由你的 Delphi 程序调用 Python 的 C API执行 Python 脚本、绑定 Python 函数、传递参数和对象。举个例子你的 Delphi 程序收到了用户上传的 Excel 文件需要做复杂的数据清洗和统计分析。在纯 Delphi 环境里写这种逻辑会非常痛苦StatLib、TeeChart 等方案虽然能用但生态远不如 Python 的 Pandas 丰富。而有了 P4D你只需要在 Delphi 里执行一段 Python 脚本把 Excel 路径传过去脚本调用 Pandas 处理完再把结果返回给 Delphi。这样既保留 Delphi 在桌面端、数据库、系统底层调用方面的优势又能借用 Python 几年的库积累。另一种常见的替代方案是直接让 Delphi 程序启动一个 Python 进程做子进程通信通过标准输入输出或者 HTTP 接口交互。这种方式也能实现集成但存在几个问题进程启动开销大、数据序列化麻烦、调试不方便、状态难以共享。P4D 采用的是进程内嵌入性能好得多数据天然共享内存而且 Python 的异常可以以对象形式传到 Delphi 侧处理。1.2 为什么选择 zip 源码包而不是 GetIt 安装关于安装方式很多人会问既然 Delphi 12.3 自带的 GetIt 包管理器里也有 Python4Delphi为什么还要手动下载python4delphi-master.zip我个人的经验是GetIt 里收录的版本往往滞后于 GitHub 主线而且 GetIt 的包安装过程是自动化的不太透明。你根本不知道它把源码放在了哪个目录以后想改源码做二次开发也麻烦。手动下载 master 分支源码的好处是第一你能拿到最新代码新版本通常支持更新的 Python 版本比如 3.11、3.12 的 API 变化比较大旧版 P4D 可能加载不了新解释器第二你可以完整体验编译流程理解哪部分是运行时、哪部分是设计期对后续排错非常有帮助第三源码包里有完整的 Demos 目录这些示例是文档之外最好的学习材料。当然zip 包的方式有个坏处你需要手动处理 Python 环境的位数匹配、DLL 路径、Library Path 配置等问题这些就算老手也很容易翻车。但一旦你把环境配好了后续开发就顺畅了。1.3 Delphi 12.3 与 Python 版本的兼容性分析这里我要重点强调一个概念位数匹配。Delphi 12.3 编译出的 Win32 程序只能加载 32 位 Python DLLWin64 程序只能加载 64 位 Python DLL。这听起来是常识但我在实际操作中真的见过有人用 64 位 Delphi 编译程序然后去加载 python311.dll32位结果运行直接报“无法找到指定的模块”或者内存访问冲突。在 Python 版本选择上我用的是 Python 3.11.9 的 64 位版本。为什么不用 3.12 或 3.13因为 P4D 的主线虽然跟进得快但某些第三方扩展库比如 numpy、pandas 的预编译 wheel对最新 Python 版本的支持会滞后。用 3.11 是比较稳妥的生态成熟、P4D 支持也好。如果你要用的 Python 库要求更高版本建议先看 P4D 仓库里 README 文件描述的兼容版本表格。Delphi 12.3 对应的编译器和运行时基础库跟旧版 Delphi比如 XE8、10.4差别不小所以直接用老版本的 P4D 源码包打开很可能会编译不过。我这次用的就是 master 分支最新代码这样跟在 12.3 上编译才能顺利通过否则会遇到很多 Winapi.Windows 签名变化带来的编译错误。2. 环境准备与编译安装2.1 前置依赖清单在动手之前先把下面的工具和依赖准备好省得到时候装一半发现缺东西依赖项版本建议说明Delphi12.3 或 12.2我用的是 12.3理论上 12.x 都可以Python3.11.x与编译目标位数一致官方 python.org 安装包不是微软商店版Git最新版用于拉取源码或者直接下载 zip 包7-Zip / WinRAR最新版解压 zip 包避免 Windows 自带解压出错cmake/msbuild看实际项目部分 P4D demo 需要核心安装不需要Python 安装的时候有一个关键选项勾选“Add python.exe to PATH”不然后面配置环境变量很麻烦。另外装 Python 时它默认会安装到一个目录比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\最好把这个路径记下来后面配置DllPath要用。2.2 解压源码包与目录结构解读把python4delphi-master.zip解压到一个路径尽量不含空格和中文的目录比如D:\Components\python4delphi-master。官方推荐路径是C:\Python4Delphi或者类似原因很简单Delphi 的库路径配置如果包含空格某些老版本工具链会把它截断导致找不到 dcu 文件。解压后你会看到几个关键目录Source核心单元源码包括PythonEngine.pas、PythonVersion.pas、PythonGUIInputOutput.pas等。这块是整个控件的发动机不建议随便修改。Packages各版本 Delphi 的包工程文件。进去会看到Delphi、Delphi10、Delphi11、Delphi12等子目录每个子目录里含有设计期包和运行期包的 .dproj 文件。Demos示例项目非常实用建议全部跑一遍。Documentation官方文档有详细的 Python 与 Delphi 类型对应关系说明。Tests自动化测试项目不是必须的但可以帮你验证安装是否正确。2.3 编译安装全流程重点来了。打开 Delphi 12.3依次点击File Open Project定位到Packages\Delphi12目录。如果找不到 Delphi12 目录说明你拉的不是最新 master或者仓库结构变了现在一般叫Delphi12或者Delphi12_xx是分支号。打开后你会看到一个运行期包比如Python4Delphi_1250.dproj之类还有一个设计期包。编译顺序有讲究先编译运行期包runtime package再编译设计期包design package。选中运行期包右键Compile如果顺利的话会在输出目录生成Python4Delphi_1250.bpl和一系列.dcu文件。然后再切到设计期包同样编译。我这边编译时遇到两个问题一是某些代码用到了TStringList.LineBreak的新特征Delphi 12.3 的 RTL 已经改了默认值二是源码里有个别 DLL 导入函数声明和最新的 Windows SDK 头文件有冲突。这两个问题都比较新如果你用的版本比我新可能已经修掉了。如果还报错可以把具体错误信息贴到 P4D 的 GitHub Issues 搜索基本都能找到解决方案。编译通过后还需要把源码目录加到 Delphi 的 Library Path 里否则新建工程时 IDE 找不到这些单元。操作路径是Tools Options Environment Options Delphi Options Library在Library path里添加Source目录路径。注意要同时在 Active platform 设置为 64-bit 和 32-bit 两种配置下分别添加不然切换编译平台时还是会提示找不到PythonEngine.dcu。最后确认一下设计期包是否安装成功。在 IDE 最右侧的组件面板里找一下正常情况下会多出一个Python标签里面有TPythonEngine、TPythonModule、TPythonDelphiVar、TPythonInputOutput等组件。这是最直接的验证方式。2.4 安装验证新建项目跑第一个 P4D 程序安装成功不代表万事大吉我建议立刻新建一个 VCL 项目验证一下。窗体上放一个TPythonEngine、一个TMemo和一个TButton然后在按钮的OnClick事件里写procedure TForm1.Button1Click(Sender: TObject); begin PythonEngine1.ExecString(print(Hello from Python)); end;如果点击按钮后 Python 输出能在TMemo配合TPythonInputOutput组件里显示出来说明整条链路没问题。这里有个小技巧想让 Python 的print输出到 Delphi 的 Memo必须把TPythonInputOutput组件的Output事件里写入Memo1.Lines.Add否则 Python 的输出默认去控制台窗口了你根本看不见。我第一跑的时候就没接这个组件结果按钮点了半天没反应以为是控件坏了后来才发现是输出没接。3. 核心功能实操与代码细节3.1 初始化 Python 引擎的推荐配置TPythonEngine的属性非常多但真正影响初始化成败的其实就几个DllName、DllPath、AutoFinalize和UseLastKnownVersion。我直接说一下我最终采用的配置属性推荐值说明DllNamepython311.dll要和 Python 版本对应DllPathC:\Users...\Python311\或 Python 安装目录指向 python DLL 所在目录AutoFinalizeTrue程序结束时自动释放 Python 解释器避免内存泄漏UseLastKnownVersionFalse手动指定版本避免自动探测到错误 DLLRegSize864 位程序必须设为 832 位程序设为 4DllPath这里值得多说两句。如果你把 Python 装到了系统 PATH 里理论上可以不填 DllPath让系统去搜索。但在实际发布程序时目标用户机器上未必装了 Python所以更稳妥的做法是把 python311.dll 和必要的标准库目录一起打包到你的程序目录然后把DllPath指向你程序所在的相对路径。这样做能让你的 Delphi 程序变成一个自包含的应用不依赖目标机器预装 Python。Python 本身依赖一堆标准库文件和.pyd扩展模块python311.zip那段也要处理好。把 Python 安装目录里的Lib文件夹整体拷贝到你的程序目录并确保PythonHome属性指向程序目录。如果PythonHome配得不正确Python 解释器启动时会报ModuleNotFoundError: No module named encodings这个报错非常常见网上一搜一大把基本上都是路径没配对。3.2 执行 Python 脚本并捕获输出P4D 里执行 Python 代码有两种方式ExecString用于执行一行或一段完整脚本EvalString用于执行表达式并返回结果。前者适合过程式调用后者适合拿到返回值。要捕获 Python 的标准输出和错误输出必须用到TPythonInputOutput组件。它有几个关键事件OnSendUniDataPython 的print输出会触发传入AText参数把它追加到你的 Memo 或日志控件即可。OnReceiveUniDataDelphi 侧往 Python 标准输入写数据时触发一般用于交互式场景。OnTracebackPython 异常时触发包含 traceback 信息对调试非常重要。我建议把OnSendUniData和OnTraceback都接上分别处理常规输出和异常输出这样 Python 脚本出错时你能在界面上看到完整堆栈而不是一个孤立的神秘错误码。还有一个细节ExecString执行多行代码时必须保证代码的缩进是正确的。字符串里写多行脚本时我习惯用sLineBreak来拼接行而不是硬编码#13#10这样代码在不同操作系统和 Delphi 版本之间移植更安全。3.3 Delphi 与 Python 互相调用的三种方式P4D 的核心价值在于双向调用。我总结一下常见的三种方式方式一Delphi 执行 Python 脚本并读取变量PythonEngine1.ExecString(result 6 * 7); var LResult: Variant; LResult : PythonEngine1.EvalString(result); ShowMessage(LResult);这里要点EvalString返回的是Variant类型可以自动转成 Delphi 的整数、字符串、浮点数等基本类型。但如果 Python 变量是列表或字典直接转成 Variant 会遇到麻烦这个时候最好用TPythonDelphiVar或者 Python 侧的 json 序列化。方式二注册 Delphi 函数供 Python 调用这是最实用的场景也是我强烈推荐掌握的能力。把 Delphi 函数暴露给 Python本质上是写一个TPythonModule的OnPythonModuleInitialization事件调用Module.AddMethod注册。procedure TForm1.PythonModule1Initialization(Sender: TObject); begin PythonModule1.AddMethod(AddNumbers, procedure(aArgs: PPyObject; aResult: PPyObject) begin // 解析 Python 传入的参数做计算把结果写回 aResult end); end;参数解析和结果返回需要用到 P4D 提供的 API比如PyArg_ParseTuple和Py_BuildValue。这块代码写起来比 Delphi 常规代码要低层一些但看懂 P4D 自带的Demos\DelphiToPython例子基本就会了。方式三通过 TPythonDelphiVar 共享对象TPythonDelphiVar可以看作一个双向桥Delphi 侧给它赋值Python 脚本里同名变量就能直接读Python 脚本里改了同名变量Delphi 侧事件能感知变化。这个机制避免了每次都要EvalString的繁琐适合频繁传递状态变量的场景。3.4 实际业务场景在 Delphi 中调用 NumPy / Pandas / PIL光会 Hello World 远远不够真正的价值在于调用第三方库。我这里以一个真实案例来说明Delphi 程序读取图片路径调用 Python 的 PIL 库生成缩略图并保存然后 Delphi 侧显示新图片路径。from PIL import Image def make_thumb(src, dst, size): img Image.open(src) img.thumbnail((size, size)) img.save(dst)Delphi 侧就是组织好src、dst、size参数然后把这段脚本传给ExecString执行。这个例子里最关键的是Python 的第三方库必须安装到 P4D 能加载到的站点包目录里。如果你希望发布后不依赖目标机器可以用pip install --target.\pylibs pillow把依赖拉到程序目录然后在脚本开头加一句import sys sys.path.insert(0, r.\pylibs)这样你的程序自带库目录不污染系统环境也不会被系统环境的包冲突影响。这是我多次踩坑后总结出来的发布策略自包含目录是王道。4. 完整案例Delphi 界面 Python 数据处理回传4.1 场景设定与界面设计为了让整个流程更直观我做一个完整的例子Delphi 窗体上放一个按钮、一个 Edit输入 CSV 文件路径、一个 Memo显示 Python 返回的数据摘要、一个TPythonEngine和一个TPythonInputOutput。点击按钮后Delphi 把路径传给 PythonPython 用 Pandas 读取 CSV 文件计算行数和列数再把结果返回给 Delphi 显示。为什么选这个场景因为它覆盖了三个关键环节参数从 Delphi 传到 Python、Python 执行脚本操作文件、Python 把结果传回 Delphi。这三个环节你做会了其他复杂逻辑基本就是在这个框架里扩展。4.2 核心代码剖析先在 FormCreate 里初始化Options : [foAutoUnload]这个选项确保 Python 引擎在释放时正确卸载 DLL否则反复打开关闭窗体可能出现 DLL 无法重新加载的问题。按钮的 OnClick 事件完整代码如下procedure TForm1.Button1Click(Sender: TObject); var LScript: string; begin LScript : import sys sLineBreak sys.path.insert(0, rC:\pylibs) sLineBreak import pandas as pd sLineBreak df pd.read_csv(r Edit1.Text ) sLineBreak result frows{len(df)}, cols{len(df.columns)}, total{df.shape[0]*df.shape[1]}; PythonEngine1.ExecString(LScript); Memo1.Lines.Add(PythonEngine1.EvalString(result)); end;代码里我特意用了 f-string 和 Pandas 的read_csv这样能确保 Python 3.6 的语法特性没问题。执行ExecString时如果没有异常再用EvalString把 result 变量取回来。这里有一个很重要的细节EvalString必须放在ExecString成功之后否则 Python 命名空间里没有result变量会抛 NameError。4.3 关键属性设置表组件属性值用途TPythonEngineDllNamepython311.dll指定解释器 DLLTPythonEngineDllPathC:...\Python311\指向 DLL 目录TPythonEnginePythonHomeC:...\Python311\配合标准库路径TPythonEngineUseLastKnownVersionFalse锁定版本TPythonEngineRegSize864 位TPythonInputOutputOnSendUniDataMemo1.Lines.Add(AText)捕获 print 输出运行后如果一切正常点击按钮后 Memo 里会打印一行类似rows1000, cols15, total15000的结果。这个例子虽然简单但已经把“Delphi 发起调用 → Python 处理 → 结果回传”完整闭环跑通了。5. 常见问题与排查技巧实录5.1 “控件丢失 / IDE 里找不到组件”类问题这应该是 P4D 用户问得最多的问题尤其是新安装完打开 IDE 才发现组件面板里没有 Python 标签。我遇到过几种情况第一种是设计期包没有正确安装。只编译了运行期包是不够的必须右键设计期包执行Install命令而不是仅Compile。如果只是编译了而没安装IDE 不会注册设计期组件。第二种是 Library Path 没有配置正确。如果编译安装都成功但新建项目时pythonEngine单元找不到那就是 Library Path 漏了。这个路径必须准确指向Source目录。这里还有个容易忽略的点x64 平台和 Win32 平台的 Library Path 是分开保存的两个平台都加上才稳妥。第三种跟热词“delphi 控件版本问题 导致 每次进入ide都丢失控件需要重新放置保存后还是那样”很像。这种奇葩问题往往和 bpl 包的版本冲突有关。一个机器上可能安装了多个 Delphi 版本或者多个版本的 P4DIDE 加载组件时发现同一个类名来自不同的包就会自动停用某个包。解决办法是把旧版本的 P4D 包彻底卸载然后只保留当前版本的。控制面板里的“程序和功能”中如果能看到 Python4Delphi 相关的安装项先卸载掉再到 IDE 的Component Install Packages里确认勾选状态。5.2 Python 环境加载失败类问题这一类的报错非常典型我列一个速查表报错信息原因解决方法无法找到指定的模块DLL 路径错误或位数不匹配检查 DllPath 指向的目录下确实有这个 DLL确认 Delphi 编译的目标平台和 Python DLL 位数一致ModuleNotFoundError: No module named encodingsPythonHome 或标准库路径错误设置 PythonHome 为 Python 安装目录将 Lib 目录拷到程序目录或绝对路径正确引用Python.h 找不到编译期报错没有安装 Python 开发头文件重新运行 Python 安装包勾选“Download debugging symbols”和“Download development binaries”执行时无任何反应输出没有接入 TPythonInputOutput确认 OnSendUniData 事件写入了显示组件另外提一句如果程序里有多个 Python 库同时加载可能因为 DLL 冲突导致模块加载失败。我建议程序里只通过 P4D 加载一份 Python DLL不要再额外加载其他 Python 包否则两个不同版本的 Python DLL 在同一个进程里会打架轻则报错重则崩溃。5.3 崩溃与线程安全问题P4D 是线程不安全的准确来说 Python 解释器在有 GIL全局解释器锁的情况下并不原生支持多线程同时调用。如果你在 Delphi 的工作线程里直接调用PythonEngine.ExecString大概率会闪退或卡死。我遇到过多次这类问题安全做法是所有对TPythonEngine的调用主线程完成或者用一个专有的 TThread 加临界区保护确保同一时刻只有一个线程进入 Python API。如果确实需要异步执行耗时 Python 任务比如训练模型建议借用TThread.Queue把任务切回主线程执行或者用TTask加Semaphore控制并发。 P4D 的 Demo 里没有太多线程相关的示例这块主要靠经验我一开始直接把执行脚本放在后台线程里结果程序无响应排查了很久发现是 Python 在等 GIL而主线程又在等子线程结果形成死锁。5.4 版本迁移与升级注意事项如果你原来用的是旧版 P4D比如 2.x 或更老迁移到新 master 时要注意API 变化挺大的很多方法名、参数类型和异常类型都改了。官方提供了UPGRADE.txt文档里面列出了从旧版到新版的迁移点一定要看。还要注意Delphi 12.3 编译出的 DCU 格式跟 Delphi 11 不兼容。如果你之前用 Delphi 11 编译过 P4D 的 dcu 文件直接复制到 Delphi 12.3 环境里是行不通的必须重新编译。这也是为什么我建议从源码完整编译一次而不是拷贝别人编译好的 dcu。6. 把 P4D 变成你工具箱里的一把瑞士军刀P4D 绝不只是一个“能跑 Python”的玩具控件。我现在的很多项目都是混合架构复杂的业务规则用 Delphi 写数据分析和 AI 推理调用 Python图像处理和 OCR 也交给 Python 的库。只要第一次编译安装成功后续写代码的体验其实很顺因为 Delphi 的强类型和 Python 的灵活性刚好互补。我个人在实际使用中最喜欢的一个小技巧在开发阶段用ExecString动态调试 Python 脚本不用每次改动都重新编译 Delphi。你可以把 Python 脚本放在外部文件里运行时用TFile.ReadAllText读进来再ExecString这样调整 Python 逻辑时完全不碰 Delphi 代码热更新效率极高。还有关于发布部署的建议如果目标机器环境未知我强烈建议使用虚拟环境生成依赖清单用 pip 把依赖打包到程序子目录然后在 Python 脚本开头加sys.path.insert。这个方案我用了大半年算是 P4D 项目落地最稳妥的姿势。如果你准备入手 P4D不要一上来就想着搞多复杂的功能先把最简单的 Hello World 跑通再跑通信中的双向调用然后再逐步加入第三方库。等你把这个链路彻底摸透会发现 Delphi 和 Python 之间的边界几乎消失了——你写的也不再是“Delphi 项目”或“Python 项目”而是一个混合了两种语言优势的完整解决方案。本文还有配套的精品资源点击获取