封装兼容性校验怎么做 实测三步避坑指南

本测试是在Python 3.9.7加上pip 21.3.1的环境下进行的，遇到过setuptools在打包时因依赖版本不兼容致使线上服务出现ImportError的情况，对于新手而言，只要依照步骤一步步去操作，便可轻松躲开这类常见问题。

第一步 生成精确依赖锁定文件

先在终端安装pip-tools，具体操作为使用pip install pip-tools==6.5.0。接着在项目根目录新建requirements.in，且在其中只写入像requests>=2.25.0这样的核心依赖。执行pip – compile requirements.in，将其输出文件指定为requirements.txt，并且使用，–resolver = backtracking作为参数，这个参数是最优推荐的，它能够深度解析依赖树，进而避免循环冲突。

关于【新手避坑】，存在常见报错，即“No matching distribution found for xxx”，其核心原因在于，直接通过pip freeze > requirements.txt 把子依赖版本钉死，如此一来，换环境就会出现崩溃情况。解决办法是，使用pip-compile重新生成，并且每次在打包之前，都必须运行一遍。

第二步 配置版本区间范围

不要用==锁死，否则其他库一升级就炸。

【新手需防入坑】，出现报错“ERROR: Could not find a version that satisfies”，一般状况下是区间设定得过窄。能够迅速解决的办法是：去执行pip install –dry-run 包名，以此查看可用版本，接着将下界降低至上一个稳定的小版本，举例来说，就是从>=2.26.0改回到>=2.25.0。

第三步 执行校验命令并解决报错

执行pip check ，要是输出No broken requirements found 那就通过 ，不然的话高频报错呈现这样： “xxx has requirement yyy ， 但你有的是zzz”。关于一站式解决流程，其一，要对当前环境进行备份。怎样备份？就是执行pip freeze > backup.txt这个操作。其二，要将pip升级到最新版本。具体怎么做？那就是运行pip install –upgrade pip此指令。其三，临时使用旧解析器。如何使用？即得采取pip install –use-deprecated=legacy-resolver -r requirements.txt这一行为。其四，要放宽冲突包的版本上界，之后再重新编译。

【新手需避坑】，不要直接去删除冲突包。正确的做法是，首先要新建虚拟环境，接着逐个安装核心依赖并运行pip check，以此来定位究竟具体是哪一个传递依赖出现问题。随后手动在requirements.in里锁定那个包的兼容版本。

将两种方案予以对比：方案A采用pip-tools（依循上面三步），适用于依赖数量小于或等于20个的小型项目，具备轻量且无侵入的特性。方案B运用Poetry，能够自动解决兼容性问题，不过需要迁移pyproject.toml，适用于多人协作的大型工程。对于小型项目而言选择A，若要引入CI/CD则选择B。

该方法不适用于C扩展模块的ABI兼容性校验，像numpy编译版本这种情况，或者.so文件链接冲突这种状况。替代方案是，直接借助Docker镜像固化整个系统环境，又或者换conda管理二进制包。别指望纯Python依赖工具能够搞定底层符号表问题。

你于封装项目之际，所察觉到的最为令人作呕的兼容性报错究竟是什么呢？于评论区抛出来呀，我试试看有无更为厉害的操作。若觉得颇具效用便点个赞，转发予仍在遭受依赖所折磨的队友。