直接说结论如果你还在用自由风格JobFreeStyle Project来维护部署任务还在靠“构建后操作”里的Shell脚本堆流程那你迟早会被越来越复杂的发布逻辑拖垮。Jenkins Pipeline用代码来定义整个持续集成/持续部署流程把“点击按钮配置”变成“写脚本管理”这不仅是把配置迁到代码里更是把原本散落在各处的构建步骤、分支判断、失败处理、并发策略统一收拢到一个文件里。这篇文章就围绕Jenkins Pipeline的语法示例展开从最基础的声明式骨架讲起结合拉取代码、构建、Docker部署等真实场景把声明式Pipeline里最常用的指令、参数化构建、环境变量、条件判断和常见排坑经验一次讲清楚适合刚开始从Freestyle迁移到Pipeline的运维和开发同学参考。1. 为什么建议你现在就切到Pipeline脚本我见过很多团队Jenkins用了好几年Job数量一大把但每次上线部署流程改动都得很小心地去勾界面选项。Freestyle Project最大的问题是“配置不可见、变更不可查”谁改了哪个Job的哪个步骤没有代码Review没有版本记录改错了只能凭记忆回退。Pipeline等于把整个构建流程变成一份文本文件通常是Jenkinsfile它有几个好处是实际操作下来立刻能感受到的流程可以入库。Jenkinsfile直接放在项目仓库根目录和代码一起提交、一起Review任何改动都有迹可循。逻辑表达能力更强。有了when条件、parallel并行、post收尾这些语法复杂流程写起来很清楚不像在Shell脚本里各种if套娃。天然支持多分支。在Multibranch Pipeline里新建分支会自动创建对应的任务Pull Request也能触发预验证。当然切换到Pipeline也有学习成本尤其是第一次接触声明式语法时很容易被stage和steps的缩进层级搞晕。这篇我会尽量把每个关键字的位置、意义说透再配合能直接抄的示例少走点弯路。2. Pipeline脚本的骨架声明式语法核心结构2.1 从最小可运行脚本开始先看一个能跑的最小示例不用管具体干什么先把结构记住pipeline { agent any stages { stage(Build) { steps { echo Hello, Pipeline } } } }这个脚本虽然简单但它包含了声明式Pipeline最核心的五个层级我按嵌套顺序拆开讲pipeline最外层所有Pipeline内容都包在这里整份文件必须由它开头。agent指定在哪个执行节点上运行任务。any表示任意可用节点实际项目中通常指定标签或容器。stages存放所有stage的容器不能直接在这里写逻辑。stage一个阶段比如Build、Test、Deploy逻辑上把任务切块。steps每个stage内部具体的执行步骤可以是一条或多条命令、脚本。我个人建议刚开始写Jenkinsfile时先只打印echo信息跑通最基础骨架再逐步往里面加步骤这样报错原因很容易定位。2.2 agent的常用形态agent的位置在pipeline块内、stages外层它决定了整个Pipeline运行在什么环境里。除了最直接的agent any还有几种常见写法// 指定标签上有标签的节点 agent { label build-slave } // 使用Docker容器作为执行环境 agent { docker { image maven:3.8.7-jdk-11 args -v /etc/hosts:/etc/hosts } } // 每个阶段使用不同agent stage(Test) { agent { docker node:16-alpine } steps { sh npm test } }agent这块我踩过最大的坑就是标签写错时任务会一直卡在等待节点。Jenkins不会立刻告诉你“找不到机器”而是持续等待。排查方法可以打开任务控制台看“Agent”段里面会列出可用标签和实际分配结果。2.3 options里值得关注的几个配置options指令放在agent之后、stages之前用来对Pipeline整体行为做约束。我常用的就几个pipeline { agent any options { timestamps() // 控制台输出加上时间戳 timeout(time: 1, unit: HOURS) // 整条Pipeline总超时时间 disableConcurrentBuilds() // 同一Job禁止并发执行 buildDiscarder(logRotator(numToKeepStr: 10)) // 只保留最近10次构建记录 } stages { // ... } }提个建议timeout和buildDiscarder几乎是每个正式环境Job必配的。不然极端情况下某次构建挂起后面的构建会全部排队历史记录不清理Jenkins主机的磁盘会被构建产物和日志逐渐堆满。3. 环境变量、参数与凭据的用法控制任务的三个入口3.1 环境变量区分环境差异在Pipeline里设置环境变量有两个地方一个是全局的environment块作用于所有stage另一个是某个stage内部的environment块只对该阶段生效。实际用的最多的就是配置不同环境的后端地址、镜像仓库地址等。pipeline { agent any environment { IMAGE_REPO registry.example.com/app STAGE dev } stages { stage(Deploy) { environment { API_BASE https://api.dev.example.com } steps { sh echo $STAGE $API_BASE $IMAGE_REPO } } } }这里注意一个小细节在sh步骤中如果要引用Pipeline里定义的环境变量推荐使用$变量名如果用${变量名}也支持但为了和Shell里的变量区分最好统一风格。另外environment块里的值支持动态生成比如environment { // 动态读取构建时的Git提交号 GIT_COMMIT sh(script: git rev-parse --short HEAD, returnStdout: true).trim() }这个写法很实用能拿到当前提交号后拼进镜像标签。3.2 parameters构建参数让Jenkinsfile接受外部输入Jenkins Pipeline里最常见的构建触发方式是“参数化构建”比如部署时选择目标环境、填写版本号。声明式Pipeline提供parameters指令pipeline { agent any parameters { string(name: ENV, defaultValue: dev, description: 目标环境) choice(name: DEPLOY_MODE, choices: [rolling, recreate], description: 部署方式) booleanParam(name: SKIP_TEST, defaultValue: false, description: 是否跳过测试) } stages { stage(Print) { steps { echo ENV${params.ENV}, DEPLOY_MODE${params.DEPLOY_MODE} echo SKIP_TEST${params.SKIP_TEST} } } } }构建时界面上会多出对应的输入框、下拉框和勾选框。脚本里读取参数的统一方式是params.参数名这一点和environment取变量的方式不一样容易混。参数化构建还有个容易踩的坑如果你改了parameters块中某个参数的名字或类型老旧的构建队列里还带着旧参数新的一次构建可能会报No such property之类的问题。我一般会顺手清理掉老旧的排队任务再触发新构建。3.3 credentials凭据不要在脚本里写死密码部署环节往往要访问远程服务器、镜像仓库、云平台这些账号密码不应该直接写在Jenkinsfile里。Pipeline应对方案是把凭据放在Jenkins凭据管理中然后在脚本里引用。pipeline { agent any stages { stage(Login Registry) { steps { withCredentials([usernamePassword(credentialsId: docker-registry-auth, usernameVariable: REG_USER, passwordVariable: REG_PASS)]) { sh docker login registry.example.com -u $REG_USER -p $REG_PASS } } } } }withCredentials会在块内临时注入环境变量块外读不到避免密钥被打印到日志。如果要打印日志排查问题也尽量打掩码信息不要把真实密码echo出来。4. Stage内部逻辑条件判断、并行执行和收尾操作4.1 when条件控制阶段是否执行很多场景需要根据分支名、参数值或环境变量决定某个stage是否运行声明式Pipeline里标准做法是when指令。我列几个高频用法stage(Deploy Prod) { when { branch main } steps { sh ./deploy.sh --prod } } stage(Skip Test) { when { expression { !params.SKIP_TEST } } steps { sh mvn test } } stage(Notify) { when { allOf { branch main environment name: STAGE, value: prod } } steps { sh curl -X POST http://alert.example.com/api/notify } }when里可以嵌套多个条件常用组合包括branch、expression、environment、allOf、anyOf、not。我的经验是能用when解决的问题尽量不要用if包在steps里因为when的判断在日志里看得更清楚而且可以精准控制整个stage被跳过而不进入其steps。4.2 parallel并行把耗时阶段压一压测试多模块或部署多节点时串行执行往往很浪费时间声明式Pipeline支持在stage内声明parallel子块stage(Test Multi Module) { parallel { stage(Module A) { steps { sh mvn test -pl module-a } } stage(Module B) { steps { sh mvn test -pl module-b } } } }并行时要注意一点并行分支共享同一个工作区如果各分支都要写同一个文件会出现相互覆盖。我通常会在各分支内部单独建子目录来隔离输出物或者用stash和unstash把构建产物在不同stage之间传递。4.3 post执行收尾构建成功后、失败后分别做什么post指令贴在stages外层或某个stage内部用来做构建结束后的统一处理比如发通知、清理临时文件、更新时间戳。条件一般用success、failure、always和unstablepipeline { agent any stages { stage(Build) { steps { sh make build } post { success { echo 构建成功 } failure { echo 构建失败 } always { cleanWs() } } } } post { failure { // 发企业微信通知、邮件通知等 sh curl -X POST http://notify.example.com/jenkins/fail } } }有个值得养成的习惯cleanWs()这种清理工作区命令放到always块里而不是只在成功或失败时执行否则长时间跑下来工作区会堆积大量没有清理的临时文件导致磁盘空间告警。5. 实战片段拉代码、构建、Docker部署三件套5.1 SCM拉取代码的正确姿势在声明式Pipeline里拉取代码通常直接用checkout步骤即可它会根据Jenkins Job配置里的“源码管理”自动拉取对应分支或Commit。示例pipeline { agent any stages { stage(Checkout) { steps { checkout scm } } } }但更多情况下我们会在Jenkinsfile里明确指定Git地址和分支而不是依赖Job配置这样Jenkinsfile的可移植性更强stage(Checkout) { steps { checkout([ $class: GitSCM, branches: [[name: env.BRANCH_NAME]], extensions: [[$class: CleanBeforeCheckout]], userRemoteConfigs: [[url: gitgithub.com:example/app.git]] ]) } }CleanBeforeCheckout这个扩展点很重要它会在拉取前清空工作区里可能残留的旧文件和构建产物避免新旧内容混杂引发幽灵问题。补充一个脚本拉代码的常见场景如果你的仓库需要通过凭据访问可以在userRemoteConfigs里加credentialsId或者在Job配置里设置好。我自己习惯把checkout scm和显式GitSCM混合用仓库地址统一的写在Jenkinsfile里凭据统一在Job配置里指定这样既方便改分支路径又不用把账号信息写进代码库。5.2 构建产物与镜像标签生成构建阶段最常见的坑是镜像标签不唯一。如果固定写latest后一次构建会覆盖前一次回滚时找不到对应镜像。所以我一般会组合生成镜像标签pipeline { agent any environment { IMAGE_REPO registry.example.com/app } stages { stage(Build JAR) { steps { sh mvn clean package -DskipTeststrue } } stage(Build Image) { steps { script { def shortCommit sh(script: git rev-parse --short HEAD, returnStdout: true).trim() env.IMAGE_TAG ${shortCommit}-${BUILD_NUMBER} } sh docker build -t ${IMAGE_REPO}:${env.IMAGE_TAG} . sh docker push ${IMAGE_REPO}:${env.IMAGE_TAG} } } } }这里用了script块包了一小段Groovy代码在声明式Pipeline里需要动态赋值给环境变量时script块是比较体面的做法。你也可以直接在environment块里动态生成变量但涉及多个变量拼接时放在script里更容易调试我自己排查问题时更爱看这里的log。5.3 部署阶段把镜像发布到目标服务器部署时常见做法是用sshPublisher插件或者直接调用ssh命令。这里给一份相对完整的声明式示例包含参数化部署目标环境pipeline { agent any parameters { choice(name: TARGET_ENV, choices: [dev, staging, prod], description: 选择部署环境) } environment { // 注意密钥内容不应该写死在仓库里 DEV_HOST root10.0.0.11 STAGING_HOST root10.0.0.12 PROD_HOST root10.0.0.13 } stages { stage(Choose Host) { steps { script { if (params.TARGET_ENV dev) { env.TARGET_HOST env.DEV_HOST } else if (params.TARGET_ENV staging) { env.TARGET_HOST env.STAGING_HOST } else if (params.TARGET_ENV prod) { env.TARGET_HOST env.PROD_HOST } } } } stage(Deploy) { steps { sshagent(credentials: [ssh-deploy-key]) { sh ssh -o StrictHostKeyCheckingno ${env.TARGET_HOST} \ docker pull registry.example.com/app:${env.IMAGE_TAG} \ docker rm -f app || true \ docker run -d --name app -p 8080:8080 registry.example.com/app:${env.IMAGE_TAG} } } } } }这段逻辑并不复杂但却是很多团队把部署流程Pipeline化的第一步先能通过Jenkins自动把镜像推到远端并启动容器后续再做滚动发布、健康检查、回滚操作。6. Jenkins Pipeline踩坑记录容器内Docker、国内镜像和调试技巧6.1 在Jenkins容器里使用宿主机Docker命令不少团队把Jenkins本身跑在Docker容器里然后要让Pipeline执行docker build和docker push。直接在Jenkins容器内装Docker是笨办法常见做法是把宿主机的/var/run/docker.sock挂载进Jenkins容器这样容器里的客户端可以操纵宿主机的Docker守护进程。# docker-compose示例省略了其他配置 version: 3 services: jenkins: image: jenkins/jenkins:lts volumes: - /var/run/docker.sock:/var/run/docker.sock - /usr/bin/docker:/usr/bin/docker - jenkins_home:/var/jenkins_home注意挂载/usr/bin/docker只是简单方案如果宿主机和容器操作系统不同比如宿主CentOS、容器基于Ubuntu二进制可能因为动态库缺失而无法运行。更推荐的做法是在容器内安装与宿主机版本兼容的Docker客户端或者用DinDDocker in Docker方式单独起一个Docker daemon。我实际维护中比较稳的方案宿主机装好DockerJenkins容器挂载socketdocker命令直接使用宿主机二进制。实在不行再考虑在agent { docker ... }上做文章。6.2 国内镜像加速问题如果构建机网络环境拉取境外镜像很慢Pipeline中处理有两种思路一种是在Jenkins全局设置里配置镜像加速器进入“Manage Jenkins - Manage Plugin - Advanced”可以找到镜像地址配置这里主要影响插件更新对docker pull来说关键是配置/etc/docker/daemon.json里的registry-mirrors但这个修改通常需要重启Docker daemon。另一种更灵活的方式是在Pipeline里显式指定镜像源。比如原来的镜像地址是maven:3.8.7-jdk-11在Docker加速场景下可以换成国内可访问的镜像地址或者在dockeragent配置里使用带加速器前缀的镜像agent { docker { image docker.mirrors.internal/maven:3.8.7-jdk-11 } }我碰到过比较隐蔽的问题是宿主机Docker配置了镜像加速但Jenkins容器内部执行docker build时使用了不同的Docker上下文导致FROM指令拉取的镜像没走加速构建极慢。后来我统一了宿主机/etc/docker/daemon.json的配置并确保Jenkins容器内使用的Docker客户端读取同一个配置问题才稳定解决。6.3 Pipeline调试的常用手法写Pipeline脚本时语法错误几乎不可避免。声明式Pipeline报错信息有时比较含糊我的调试经验按优先级排序如下在agent any的最小Job里先跑通一句echo确认Pipeline骨架没毛病。利用options { timestamps() }给日志加时间戳方便定位卡在哪个阶段。在可疑阶段加sh pwd ls -la先确认当前工作目录和工作区内容。动态变量相关逻辑尽量放在script块里临时输出用echo带到日志中。另外我经常使用Declarative: Pipeline Syntax工具这个页面在任意Pipeline Job的“流水线语法”链接里能打开它会把常用的steps、when、credentials等配置可视化地生成对应代码。这个东西是初学Pipeline时最被低估的帮手很多人宁可手写猜语法也不愿意花一分钟点几下生成。最后聊一个不好查的问题Pipeline里sh步骤默认使用/bin/sh -xe执行命令只要任意一条命令返回非零状态整个步骤就会失败。若你有命令预期会返回非零比如zcat a.gz /dev/null在某些情况会返回1必须在命令末尾加|| true或者在sh步骤中设置returnStatus: true来自行处理返回值。7. Multibranch Pipeline与Jenkinsfile入库后的团队协作习惯Pipeline天然适配“分支即环境”的开发流程Multibranch Pipeline会在检测到仓库新分支或Pull Request时自动创建并触发布建任务。Jenkinsfile放在仓库根目录后团队协作可以形成几个我强烈推荐的约定每次都从main出发布分支发布分支的Jenkinsfile里置为只跑测试和构建不自动部署生产。部署生产环境的stage强制要求手动触发用input指令实现“人工确认后再执行”。代码Review时Jenkinsfile也必须Review尤其是environment、credentialsId、script块里动态拼接的命令Review重点看是否存在敏感信息泄露和命令注入风险。举一个需要input的生产部署门禁示例stage(Deploy to Prod) { when { branch main } steps { input message: 确认部署到生产环境, ok: 开始部署 sh ./deploy.sh --prod } }加入input后Pipeline运行到这一步会暂停必须点击确认按钮才继续。这对生产环境来说是非常值得加的“人工保险丝”。8. 从Freestyle迁移到Pipeline我自己的顺序建议接触了一些团队后我发现直接要求“把所有Job都改成Jenkinsfile”往往会遇到阻力毕竟老Job步骤又多又杂。我的建议是分四步走挑一个最简单的构建Job把它改写成只有checkout、build、archiveArtifacts的Pipeline体验一下语法和日志格式的变化。把带参数构建的Job迁移过去重点处理params在when和environment中的使用方式。再迁移带发布环节的Job尤其是有Docker镜像推送、远程部署、多环境切换的。最后统一管理凭据和共享库。多个Job共用一段部署逻辑时把公共函数抽到共享库Shared Library里每个Jenkinsfile只保留自己特有的业务流程。我在第1步到第2步之间最容易遇到的问题是Freestyle里“构建环境”里勾选的项比如“Delete workspace before build starts”、“Add timestamps to the Console Output”在Pipeline里分别对应CleanBeforeCheckout扩展点、timestamps()。不提前梳理对照关系迁移时容易漏掉原本依赖于构建环境的隐性行为。各步骤对应关系可以简单列个表Freestyle选项Pipeline写法源码管理里的Git地址和分支checkout scm或显式GitSCM配置构建触发器里的参数化构建parameters指令构建环境里的Delete workspaceCleanBeforeCheckout扩展点或cleanWs()构建环境里的Add timestampsoptions { timestamps() }构建后操作里的Archive artifactsarchiveArtifacts artifacts: build/libs/*.jar构建后操作里的Email Notificationpost { failure { mail to: teamexample.com } }这样对照着改比对着Freestyle界面硬翻译Pipeline语法要稳得多也能避免迁完发现某些行为不对的返工。9. 几个容易被忽略但影响很大的细节Pipeline坑有时候不在语法本身而在周边环境。我挑几个真实影响过我的细节说一下。workspace目录权限问题。Pipeline在部分受管节点上执行时工作区目录可能是共享的不同Job如果同名很容易互相干扰。建议把每个团队的Job命名加上前缀或用options { workspace $JOB_NAME }这种方式隔离工作目录。如果没有明确命名排查问题时两个Job共用文件导致的结果异常非常费劲。stash和unstash的坑。很多人在一个stage里构建出了产物想在后面stage用但不同stage在不同agent上运行时工作区内容并不会自动共享此时必须用stash把文件暂存到Jenkins大师节点后续unstash取出来。注意stash不支持特别大的文件动辄几个GB的安装包不太适合stash建议走制品仓库或共享存储。环境变量大小写敏感。声明式Pipeline里environment定义的变量名和params里的参数名都区分大小写写错一个字母经常导致取到空值而不是报错。比如env.Image_Tag和env.IMAGE_TAG如果混用可能导致镜像标签错误。遇到镜像拉取失败或Docplier找不到镜像的情况先看下环境变量打印是否和预期一致。最后说下日志乱码的坑。Pipeline里sh执行的命令如果输出中文且节点上默认字符集不是UTF-8日志可能出现乱码。可以在environment里加一行environment { LC_ALL C.UTF-8 }或者在节点上设置LANGen_US.UTF-8。这个问题在中文团队里尤其常见日志乱码虽然不影响构建结果但排查问题时看乱码输出非常痛苦提前设置一下能省很多事。
