编辑“︁Jenkins环境变量注入”︁

{{DISPLAYTITLE:Jenkins环境变量注入}}  
'''Jenkins环境变量注入'''是持续集成流程中管理动态配置的核心技术，通过将键值对注入到构建环境中，实现参数化构建和跨阶段数据共享。本文将从基础原理到高级应用全面解析该机制。  

== 概述 ==  
环境变量是操作系统或应用程序运行时定义的动态键值对，Jenkins通过多种方式注入这些变量：  
* '''全局变量'''：Jenkins内置或通过插件预定义的变量（如<code>JENKINS_URL</code>）  
* '''项目级变量'''：在Pipeline或Job配置中手动定义  
* '''动态注入'''：通过脚本或外部工具（如<code>withEnv</code>）实时生成  

=== 核心作用 ===  
* **参数化构建**：动态传递构建参数（如版本号、部署目标）  
* **跨阶段共享数据**：在Pipeline的不同阶段传递状态信息  
* **安全隔离**：通过凭证变量避免敏感信息硬编码  

== 注入方法 ==  

=== 1. 全局变量 ===  
Jenkins自动提供的环境变量，可通过<code>env</code>对象访问：  

<syntaxhighlight lang="groovy">  
// 打印所有环境变量  
pipeline {  
    agent any  
    stages {  
        stage('Example') {  
            steps {  
                sh 'printenv | sort'  // Linux/Mac  
                bat 'set'             // Windows  
            }  
        }  
    }  
}  
</syntaxhighlight>  

常见内置变量：  
* <code>BUILD_NUMBER</code>：当前构建编号  
* <code>JOB_NAME</code>：任务名称  
* <code>WORKSPACE</code>：工作目录路径  

=== 2. 项目级变量配置 ===  
在Jenkins任务配置页面的"环境变量"部分添加：  

<mermaid>  
flowchart LR  
    A[Job配置] --> B[勾选"This project is parameterized"]  
    B --> C[添加String/Boolean/Choice参数]  
    C --> D[在Pipeline中通过params.NAME访问]  
</mermaid>  

示例：注入自定义变量  
<syntaxhighlight lang="groovy">  
pipeline {  
    agent any  
    environment {  
        DEPLOY_ENV = "production"  
        API_KEY = credentials('aws-key')  // 从Jenkins凭证库读取  
    }  
    stages {  
        stage('Deploy') {  
            steps {  
                echo "Deploying to ${env.DEPLOY_ENV}"  
                sh 'deploy.sh ${API_KEY}'  
            }  
        }  
    }  
}  
</syntaxhighlight>  

=== 3. 动态注入（withEnv） ===  
在特定步骤中临时覆盖环境变量：  
<syntaxhighlight lang="groovy">  
stage('Test') {  
    steps {  
        withEnv(['TEST_VERBOSE=1']) {  
            sh 'run_tests.sh'  // 此步骤中TEST_VERBOSE=1  
        }  
        sh 'echo $TEST_VERBOSE'  // 变量已失效  
    }  
}  
</syntaxhighlight>  

== 高级技巧 ==  

=== 变量作用域控制 ===  
Jenkins环境变量遵循以下优先级（从高到低）：  
1. <code>withEnv</code>临时变量  
2. <code>environment{}</code>块定义的变量  
3. 全局环境变量  

数学表达：  
<math>  
\text{EffectiveValue} = \begin{cases}  
withEnv & \text{if exists} \\  
environment & \text{else if exists} \\  
global & \text{otherwise}  
\end{cases}  
</math>  

=== 跨节点变量传递 ===  
在分布式构建中，需通过<code>env</code>对象显式传递：  
<syntaxhighlight lang="groovy">  
stage('Build') {  
    agent { label 'builder' }  
    steps {  
        script {  
            env.ARTIFACT_PATH = "build/output.zip"  
        }  
    }  
}  
stage('Deploy') {  
    agent { label 'deployer' }  
    steps {  
        echo "Artifact: ${env.ARTIFACT_PATH}"  // 需要Workspace同步或存档  
    }  
}  
</syntaxhighlight>  

== 实战案例 ==  

=== 场景：多环境部署 ===  
通过变量切换部署目标：  
<syntaxhighlight lang="groovy">  
pipeline {  
    parameters {  
        choice(name: 'ENV', choices: ['dev', 'staging', 'prod'], description: 'Target environment')  
    }  
    environment {  
        DEPLOY_CONFIG = "${params.ENV}_config.yaml"  
    }  
    stages {  
        stage('Prepare') {  
            steps {  
                sh "cp configs/${DEPLOY_CONFIG} ./deploy.yaml"  
            }  
        }  
    }  
}  
</syntaxhighlight>  

=== 故障排查 ===  
* '''变量未生效'''：检查拼写错误和作用域生命周期  
* '''权限问题'''：确保凭证变量已被正确绑定  
* '''特殊字符处理'''：对含空格的值使用双引号包裹  

== 最佳实践 ==  
1. '''命名规范'''：使用大写字母和下划线（如<code>DB_HOST</code>）  
2. '''敏感信息'''：始终通过<code>credentials()</code>管理  
3. '''文档化'''：在Pipeline顶部注释所有自定义变量的用途  

通过系统化的环境变量管理，可以显著提升Jenkins Pipeline的灵活性和可维护性。

[[Category:集成部署]]
[[Category:Jenkins]]
[[Category:Jenkins与配置管理]]