CI构建中使用缓存venv运行Poetry命令触发FileNotFoundError求助

该错误由虚拟环境（venv）的默认不可移植特性导致，即使缓存文件与全新安装的文件二进制一致，也会因为路径硬编码触发报错，核心诱因有两个：

• venv的bin/目录下所有可执行脚本的首行shebang，写死了打包时环境的Python解释器绝对路径，解压后项目路径/环境路径变化时，系统无法找到对应解释器，触发os._execvpe的文件不存在错误
• venv根目录下pyvenv.cfg配置文件中的home字段，记录了打包时Python安装路径的绝对路径，构建环境与打包环境路径不一致时也会触发该问题

这也是执行poetry install提示无额外依赖需要安装，但仍然报错的原因：Poetry仅校验依赖安装状态，不会修复venv本身的路径硬编码问题。

1. 调整缓存打包逻辑（从根源解决） #

打包上传缓存前执行以下预处理操作，消除路径硬编码：

• 批量替换./.venv/bin下所有脚本的shebang为可移植写法：#!/usr/bin/env python，避免绑定绝对路径
• 清空./.venv/pyvenv.cfg中的home字段，或者替换为当前环境Python的通用路径标识
• 可选使用venv-travel等工具一键将venv转换为可迁移格式，无需手动修改文件

2. 调整缓存解压后的初始化逻辑 #

每次从缓存解压venv后，先执行以下两个低耗时操作再运行业务命令：

• 执行poetry env use ./.venv/bin/python，强制Poetry刷新本地虚拟环境的关联路径，清除Poetry内部缓存的旧路径
• 执行poetry run pip install --force-reinstall -q pip setuptools，修复基础依赖的路径硬编码，该操作仅耗时1-2秒，不会影响缓存加速效果

3. 快速排障方案 #

如果修改后仍有报错，可通过以下步骤定位具体问题：

1. 手动激活虚拟环境：source ./.venv/bin/activate
2. 执行which reorder-python-imports确认命令路径是否为当前项目下的.venv路径
3. 直接执行head -n1 ./.venv/bin/reorder-python-imports查看shebang路径是否存在，即可定位具体的硬编码问题

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