Jenkins基于virtualenv实现作业独立环境的执行异常排查

首先得明确核心问题：Jenkins的每个sh步骤都是独立的子shell进程，哪怕你配置了登录shell，每个sh执行时都是全新的进程，之前shell里激活的virtualenv环境不会自动继承到下一个步骤——这就是你遇到“每次sh都重新加载环境”的根源。

下面是我整理的可行解决方案，基于共享库脚本实现作业级的virtualenv环境管理，确保环境在流水线步骤中持续生效：

1. 重构共享库脚本 vars/activateEnvironment.groovy #

这个脚本的核心是把virtualenv的环境变量注入到Jenkins全局env对象中，让后续所有sh步骤自动继承这些变量；同时生成一个便捷的激活脚本，方便需要显式激活的场景：

def call(String venvDir = './venv') {
    // 1. 创建virtualenv（如果不存在）
    sh "python3 -m venv ${venvDir}"

    // 2. 提取virtualenv激活后的关键环境变量，注入Jenkins env
    def venvEnvOutput = sh(
        script: "source ${venvDir}/bin/activate && env | grep -E '^(VIRTUAL_ENV|PATH|PYTHONPATH)'",
        returnStdout: true
    ).trim()

    venvEnvOutput.split('\n').each { line ->
        def (envKey, envValue) = line.split('=', 2)
        env[envKey] = envValue
        echo "Set Jenkins env var: ${envKey}=${envValue}"
    }

    // 3. 生成便捷激活脚本，供需要显式source的场景使用
    sh """
        echo '#!/bin/bash' > ${venvDir}/jenkins-activate.sh
        echo 'source ${venvDir}/bin/activate' >> ${venvDir}/jenkins-activate.sh
        chmod +x ${venvDir}/jenkins-activate.sh
    """

    echo "✅ Virtualenv environment setup completed: ${env.VIRTUAL_ENV}"
}

2. 流水线中使用的正确姿势 #

在你的Jenkinsfile中调用这个共享库脚本后，有两种方式确保环境生效：

方式1：依赖Jenkins env自动传递（推荐） #

因为我们已经把PATH等关键变量注入到Jenkinsenv中，后续的sh步骤会自动使用virtualenv里的Python/Pip：

@Library('virtualenv-scripts') _

pipeline {
    agent any
    stages {
        stage('Initialize Env') {
            steps {
                activateEnvironment('./my-project-venv')
            }
        }
        stage('Install Dependencies') {
            steps {
                // 直接使用pip，会自动调用virtualenv里的版本
                sh 'pip install --upgrade pip'
                sh 'pip install -r requirements.txt'
            }
        }
        stage('Run Tests & Build') {
            steps {
                sh 'python -m pytest tests/'
                sh 'python setup.py build'
            }
        }
    }
}

方式2：显式source激活脚本 #

如果某些场景下需要确保环境完全一致（比如涉及到其他环境变量），可以直接source我们生成的便捷脚本：

stage('Run Custom Script') {
    steps {
        sh './my-project-venv/jenkins-activate.sh && ./my-custom-script.sh'
    }
}

3. 额外注意事项 #

• 跨平台兼容：如果你的Jenkins agent包含Windows节点，需要在脚本中判断操作系统，替换激活脚本路径（Windows下是${venvDir}/Scripts/activate.bat或Activate.ps1）
• Python版本一致性：确保Jenkins agent使用的Python3版本和你创建virtualenv的版本一致，避免出现奇怪的兼容性问题
• 避免重复创建：可以在脚本中加入判断逻辑，比如检查${venvDir}/bin/python是否存在，跳过重复创建virtualenv的步骤

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