如何将Cython的engine.so库配置到test虚拟环境供Python调用

前置匹配检查 #

Cython编译的二进制扩展和Python版本、系统架构强绑定，不匹配的话任何配置方法都无法生效，必须先完成以下检查：

• 激活名为test的虚拟环境，执行python --version，确认输出为Python 3.7.x系列版本，该so文件仅支持Python3.7，3.6/3.8及以上版本均无法加载
• 执行uname -m，确认输出为x86_64，该so仅支持64位x86架构的Linux系统，ARM架构（如苹果M系列芯片、国产ARM服务器）、Windows/macOS系统均无法直接使用

方案1：项目本地快速测试（无需修改虚拟环境文件） #

适合临时跑test.py验证功能，步骤如下：

• 激活test虚拟环境后，通过cd命令切换到存放engine.cpython-37m-x86_64-linux-gnu.so和test.py的工作目录，执行ls确认两个文件都在当前路径下
• 直接执行python test.py即可，默认Python会把当前执行命令的工作目录加入模块搜索路径，正常情况下就能识别到engine模块
• 如果依然提示找不到模块，就在test.py的最开头（在from engine import authenticate之前）加入以下代码，手动把脚本所在目录加入搜索路径：

import sys
import os
sys.path.append(os.path.dirname(os.path.abspath(__file__)))

方案2：安装到虚拟环境全局生效 #

配置完成后，只要激活test虚拟环境，在任意目录下的Python脚本都可以正常导入engine模块：

• 激活test虚拟环境，执行以下命令获取虚拟环境的第三方包存放路径：

python -c "import site; print(site.getsitepackages()[0])"

• 命令执行后会输出类似/home/yourname/.virtualenvs/test/lib/python3.7/site-packages的绝对路径
• 把当前目录下的engine.cpython-37m-x86_64-linux-gnu.so文件复制到上述输出的site-packages目录下，示例命令：

cp engine.cpython-37m-x86_64-linux-gnu.so /上一步输出的site-packages绝对路径/

• 复制完成后直接运行脚本即可，无需额外配置路径。

常见报错排查 #

• 报ModuleNotFoundError: No module named 'engine'：先检查Python版本是否为3.7、so文件名是否被修改（必须保留完整的cpython-37m-x86_64-linux-gnu.so后缀，不能重命名成engine.so）、so文件是否放在了Python搜索路径覆盖的目录下
• 报libxxx.so: cannot open shared object file：说明engine依赖的系统动态库缺失，对照原Docker镜像内安装的系统依赖，用apt等包管理器安装对应缺失的库即可
• 报invalid ELF header：so文件和当前系统架构不匹配，比如把ARM架构编译的so拿到x86机器上使用，需要重新获取对应架构的编译文件

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