Jenkins流水线Miniconda虚拟环境中跨文件夹导入Python工具脚本的最优方案

针对你在Jenkins流水线的Miniconda虚拟环境里遇到的模块导入问题，结合你的文件夹结构（main_folder下包含pyscripts1/2/3和utils子文件夹），这里有几个适配场景的最优方案：

1. 使用相对导入（最干净的无路径修改方案） #

如果你的脚本是作为包的一部分被调用（而非直接执行单个脚本），相对导入是最优雅的选择。比如在pyscripts1/script11.py中：

# 从上级目录的utils模块导入指定脚本
from ..utils import utils1, utils2

⚠️ 注意：直接运行python pyscripts1/script11.py会触发ValueError: attempted relative import beyond top-level package错误。你需要在main_folder的上级目录（或把main_folder当作包根目录），用模块方式运行脚本：

# 假设当前处于main_folder所在的目录
python -m main_folder.pyscripts1.script11

这种方式让Python自动识别包结构，不需要手动修改路径，非常适合规范的项目结构。

2. 动态添加相对路径到sys.path（兼容直接运行脚本） #

如果需要保留直接执行单个脚本的方式，可以通过脚本自身的位置动态计算根目录，添加到sys.path中，避免硬编码绝对路径。在每个pyscripts下的脚本开头添加：

import os
import sys

# 获取当前脚本所在的目录
current_script_dir = os.path.dirname(os.path.abspath(__file__))
# 推导main_folder目录（当前脚本目录的父目录）
main_folder_dir = os.path.dirname(current_script_dir)
# 将main_folder加入Python的模块搜索路径
sys.path.append(main_folder_dir)

# 现在可以直接导入utils模块中的脚本
from utils import utils1

这个方法的优势是完全不依赖固定路径，只要你的文件夹结构不变，不管Jenkins工作区的路径怎么变化，脚本都能正确找到utils模块。

3. 在Jenkins流水线中临时设置PYTHONPATH（无需修改脚本） #

虽然Conda默认不依赖PYTHONPATH，但你可以在Jenkins的流水线步骤中，激活环境后临时设置这个环境变量，指向main_folder。比如在Jenkinsfile的shell步骤里：

# 激活你的Miniconda虚拟环境
conda activate your_conda_env
# 将main_folder添加到PYTHONPATH（WORKSPACE是Jenkins自带的工作区路径变量）
export PYTHONPATH="${WORKSPACE}/main_folder:$PYTHONPATH"
# 执行目标脚本
python "${WORKSPACE}/main_folder/pyscripts1/script11.py"

这样脚本里不需要任何路径修改，直接写import utils.utils1即可。这个方案适合不想修改现有脚本代码的场景，利用Jenkins的环境变量来动态适配工作区路径。

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