如何配置Py4Delphi使其使用指定Python虚拟环境执行脚本

前置校验 #

配置前先确认两个匹配项，不然后续操作全无效：

• Py4Delphi 绑定的Python大版本和目标虚拟环境的Python版本完全一致，比如虚拟环境是Python3.9，就不能用适配Python3.8的Py4Delphi组件
• 程序位数和Python位数匹配：32位编译目标对应32位Python创建的虚拟环境，64位编译目标对应64位Python创建的虚拟环境

核心规则 #

所有路径配置必须在TPythonEngine的Initialize方法执行前完成，不要开启组件的AutoInitialize属性，否则解释器会提前加载，后续修改参数不生效。

具体配置步骤 #

1. 先梳理目标虚拟环境的关键路径
   以Windows系统标准venv创建的虚拟环境为例，假设虚拟环境根目录为D:\venvs\my_demo_env：
   • Python动态库路径：D:\venvs\my_demo_env\Scripts\python3x.dll（x替换为实际次版本号，比如3.9对应python39.dll）
   • 第三方包路径：D:\venvs\my_demo_env\Lib\site-packages

   如果是conda创建的虚拟环境，python3x.dll直接在虚拟环境根目录下，不在Scripts文件夹内，路径不要拼错。

2. 初始化前给PythonEngine组件赋值核心参数
   • DllPath：赋值为python3x.dll所在的文件夹路径，强制Py4Delphi加载虚拟环境内的Python dll，不搜索系统PATH、注册表内的全局Python
   • DllName：赋值为准确的dll文件名（比如python39.dll），避免版本错配
   • SysPath：清空默认值后，优先添加虚拟环境的site-packages路径、Scripts路径、虚拟环境根目录，确保解释器优先加载虚拟环境内的第三方包
3. 调用Python C API设置Home路径
   直接调用Py4Delphi已封装的Py_SetPythonHome函数，入参为虚拟环境根目录字符串，这一步是实现环境隔离的核心，避免解释器加载全局Python的标准库。
4. 所有参数配置完成后，手动调用PythonEngine.Initialize完成解释器初始化。

可直接复用的代码示例 #

uses
  System.IOUtils, PythonEngine;

procedure TMainForm.FormCreate(Sender: TObject);
const
  // 替换为实际的虚拟环境根目录绝对路径
  C_VENV_ROOT = 'D:\venvs\my_demo_env';
var
  LDllPath, LSitePkgsPath, LScriptsPath: string;
begin
  // 拼接虚拟环境各路径（venv规则，conda环境直接把LDllPath设为C_VENV_ROOT即可）
  LScriptsPath := TPath.Combine(C_VENV_ROOT, 'Scripts');
  LDllPath := LScriptsPath;
  LSitePkgsPath := TPath.Combine(C_VENV_ROOT, 'Lib\site-packages');

  // 关闭自动初始化，确保配完参数再加载解释器
  PythonEngine1.AutoInitialize := False;
  // 配置dll加载路径
  PythonEngine1.DllPath := LDllPath;
  PythonEngine1.DllName := 'python39.dll'; // 替换为实际dll名

  // 配置模块搜索优先级
  PythonEngine1.SysPath.Clear;
  PythonEngine1.SysPath.Add(LSitePkgsPath);
  PythonEngine1.SysPath.Add(LScriptsPath);
  PythonEngine1.SysPath.Add(C_VENV_ROOT);

  // 设置Python Home到虚拟环境
  Py_SetPythonHome(PChar(C_VENV_ROOT));

  // 初始化解释器
  PythonEngine1.Initialize;

  // 验证配置是否生效，正常会输出你配置的虚拟环境根目录
  PythonEngine1.ExecString('import sys; print("当前激活环境:", sys.prefix)');
end;

常见问题排查 #

• 初始化报dll加载失败：先检查位数是否匹配、dll路径是否正确、dll文件名是否写对
• 运行脚本报模块找不到：打印sys.path确认虚拟环境的site-packages路径是否在列表最前，有没有拼写错误
• 加载了虚拟环境的dll但还是调用全局包：确认Py_SetPythonHome是在Initialize之前调用的，不要漏这一步
• 打包发布后路径失效：不要用相对路径指定虚拟环境目录，程序启动时先把路径转为绝对路径再赋值

内容的提问来源于stack exchange，提问作者Sean B. Durkin