environment 是什么
environment 块在流水线或阶段级集中声明环境变量，withEnv 在块内做临时覆盖、块结束即恢复；两者常与凭据绑定配合，把密钥和配置注入构建。作用域规则简单但容易踩坑：变量名与内置变量冲突、引号与转义处理不当，都会带来难查的问题。
基本信息
| 声明式 | environment { KEY = 'value' } |
|---|---|
| 临时覆盖 | withEnv(["K=V"]) { ... }，块结束恢复 |
| 凭据 | credentials('id') 注入到变量，日志自动掩码，优先用它而非明文 |
| 作用域 | environment 随声明块生效；withEnv 只作用于闭包内 |
| 内置变量 | env.BUILD_NUMBER、env.BRANCH_NAME 等可直接引用 |
| 注意 | 变量名不要与内置变量重名 |
| 跨平台 | sh 与 bat 的变量展开规则不同，别依赖单一写法 |
变量与临时覆盖
变量与临时覆盖
pipeline {
agent any
environment {
REGISTRY = 'registry.example.com' // 全局注入
}
stages {
stage('push') {
steps {
withEnv(["TAG=${env.BUILD_NUMBER}"]) { // 临时覆盖
sh 'docker push "$REGISTRY/app:$TAG"' // 块内生效
}
}
}
}
}典型使用场景
- 镜像仓库地址：多阶段共用同一 registry 前缀
- 凭据注入：把账号密码以变量形式传给构建步骤
- 临时覆盖：单个阶段用不同版本号或环境标识
- 分支差异化：按分支设置不同的目标环境变量
- 共享库封装：用 withEnv 包装通用步骤、隐藏细节
- 调试排查：打印变量值验证作用域是否符合预期
- 跨平台适配：同一变量在 Linux 与 Windows 步骤中分别引用
方式与作用域
| 方式 | 生效范围 | 典型用途 |
|---|---|---|
| environment 流水线级 | 全流水线 | 公共配置如镜像仓库 |
| environment 阶段级 | 单个阶段 | 阶段专用参数 |
| withEnv | 闭包内 | 临时覆盖、精确控制 |
| credentials() | 声明的变量 | 密钥注入与日志掩码 |
| 内置 env.* | 全流水线 | 构建号、分支等元数据 |
把构建编号拼进镜像标签是常见做法：env.BUILD_NUMBER 等内置变量可直接引用，无需额外声明。
变量名与内置变量冲突：覆盖内置值引发难查问题，命名加项目前缀规避。
字符串引号边界出错在共享库中尤其难查：先在本地小流水线验证再进共享库。
环境变量在 sh 与 bat 中的展开规则不同：跨平台流水线避免依赖某一种 shell 的语法。