如何修改预构建Python安装以适配任意目录并支持pip源码编译

问题背景 #

项目附带预构建的定制Python发行版，产品安装目录不固定，示例结构如下：

/opt
├── my-program-v1
│   ├── some-files
│   ├── custom-python-3.9
├── my-program-v2
│   ├── some-files
│   ├── custom-python-3.11

直接复制Python安装目录后，使用pip安装需要编译源码的包（如ibm_db）时，会出现找不到Python.h的错误：

$ python3 -m pip install ibm_db
Collecting ibm_db
  Downloading ibm_db-3.1.4.tar.gz (1.4 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.4/1.4 MB 9.5 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error
  
  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [8 lines of output]
      Detected 64-bit Python
      Detected platform = linux, uname = x86_64
      Downloading https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/linuxx64_odbc_cli.tar.gz
       Downloading DSDriver from url =  https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/linuxx64_odbc_cli.tar.gz
      Pre-requisite check [gcc] : Passed
      
      No Python.h header file detected.
      Please install python-devel or python3-devel as instructed in "https://github.com/ibmdb/python-ibmdb/blob/master/README.md#KnownIssues" and continue with the installation
      [end of output]

常规从源码构建Python时，可通过configure --prefix指定目标目录并写入sysconfigdata，但预构建时无法预知最终安装目录，手动修改sysconfigdata（路径为lib/<python-version>/_sysconfigdata__linux_x86_64-linux-gnu.py）操作繁琐且无法融入CI流程，需要业内标准的预构建Python迁移适配方法。

业内标准解决方案 #

1. 预构建保留开发文件+设置环境变量 #

预构建Python时，务必保留include目录（包含Python.h等头文件）。部署后，通过环境变量告知编译工具链头文件位置：

• 临时生效：执行pip安装前，运行export CFLAGS="-I${PYTHON_INSTALL_DIR}/include/python${VERSION}"，其中${PYTHON_INSTALL_DIR}为当前Python安装路径，${VERSION}对应具体版本（如3.9）
• 持久生效：将上述环境变量写入Python的虚拟环境activate脚本，或产品启动脚本中，确保每次调用pip时自动加载

2. 用sysconfig动态修正配置 #

利用Python内置的sysconfig模块动态调整编译配置，在CI部署流程中添加适配脚本，复制Python完成后自动执行：

import sysconfig
import os

python_dir = os.path.dirname(sys.executable)
config_vars = sysconfig.get_config_vars()
# 修正头文件路径
config_vars['INCLUDEDIR'] = os.path.join(python_dir, 'include')
config_vars['INCLUDEPY'] = os.path.join(python_dir, 'include', f'python{sys.version_info.major}.{sys.version_info.minor}')
# 修正库文件路径
config_vars['LIBDIR'] = os.path.join(python_dir, 'lib')

无需手动修改sysconfigdata文件，即可让编译工具识别正确的依赖路径。

3. 预构建启用共享库+调整RPATH #

预构建Python时添加--enable-shared参数，并通过工具调整RPATH为相对路径：

• 构建阶段：执行./configure --enable-shared --prefix=/tmp/python-build，再运行make && make install
• 部署阶段：用patchelf工具修改Python二进制文件的RPATH：patchelf --set-rpath '$ORIGIN/../lib' ${PYTHON_INSTALL_DIR}/bin/python3
  这种方式不仅解决头文件问题，还能确保共享库路径适配，编译扩展包时会自动识别正确的依赖位置。

4. 提前预编译扩展包分发 #

在CI流程中，针对预构建的Python版本，提前编译好需要的扩展包（如ibm_db）的wheel文件，随产品一起分发。部署后直接执行pip install <local-wheel-file>，避免在目标环境编译源码，彻底绕过头文件依赖问题。

内容的提问来源于stack exchange，提问作者frans