如何编写Jenkins Pipeline_Jenkinsfile基础语法说明

jenkinsfile 是 jenkins pipeline 的唯一权威定义文件，必须放在项目根目录下，用 groovy 语法编写，支持版本控制与审计；不用它则 ci/cd 流程不可复现、不可迁移。

什么是 Jenkinsfile，为什么必须用它而不是 Web ui 配置

Jenkinsfile 是 Jenkins Pipeline 的唯一权威定义文件，本质是一个文本脚本，必须放在项目根目录下（或指定路径），Jenkins 通过 SCM（如 git）拉取后执行。不用它，所有构建逻辑都锁死在 Jenkins Web 界面里，无法版本控制、无法 Code Review、无法复现环境——这直接导致 CI/CD 流程不可审计、不可迁移。

常见错误现象：pipeline 块没写、agent 缺失、缩进用空格混 Tab，导致 WorkflowScript: 1: Expected a step @ line 1, column 1. 这类语法错误。

• 必须用 Groovy 语法（但不是完整 Groovy，是 Jenkins 定制的受限子集）
• 文件名严格为 Jenkinsfile（大小写敏感，不能是 jenkinsfile 或 JenkinsFile）
• 推荐使用 agent any 起步；若用 agent none，则每个 stage 必须显式声明 agent
• 所有 stage 内的步骤必须包裹在 steps 块中，漏写会报 Expected a step

如何写一个可运行的最小 pipeline：从 checkout 到 echo

最简可用的 Jenkinsfile 只需三要素：pipeline 块、agent、一个含 steps 的 stage。它不依赖任何插件，纯内置能力就能跑通。

示例：

pipeline {     agent any     stages {         stage('Checkout') {             steps {                 checkout scm             }         }         stage('Echo') {             steps {                 echo 'Hello from Jenkinsfile'             }         }     } }

• checkout scm 自动检出当前 Pipeline 所绑定的 Git 仓库（前提是 Job 配置了 SCM）
• 不要手动写 sh 'git clone ...' —— 这绕过 Jenkins 的 workspace 管理，后续 archiveArtifacts 或 junit 会找不到路径
• 所有 echo、sh、bat 都是内置步骤，无需额外安装插件
• windows 节点用 bat，linux/macos 用 sh；混用会导致 hudson.AbortException: script returned exit code 1

如何安全地读取敏感信息：credentials() 和 withCredentials()

硬编码密码、Token、私钥到 Jenkinsfile 是严重安全风险，且违反 Jenkins 最佳实践。Jenkins 提供 credentials ID 绑定机制，配合 withCredentials 步骤注入环境变量或文件。

常见错误现象：Cannot retrieve credentials（ID 拼错）、java.lang.NullPointerException（credentialsId 为空）、未在 Jenkins 系统凭据中提前添加对应凭据。

• 凭据必须在 Jenkins 管理界面预先创建，类型选 Secret text（API Token）、Username with password（ssh 密码登录）、SSH Username with private key（密钥对）
• 在 Jenkinsfile 中引用时，用 credentialsId: 'my-api-token-id'，ID 是你在凭据页面看到的「ID」列值，不是描述名
• 推荐用 String 类型凭据 + withCredentials([string(credentialsId: 'my-token', variable: 'API_TOKEN')]) 注入为环境变量
• 避免用 environment 块全局注入凭据——它会在日志中明文打印变量值（即使加了 maskPassword 也不可靠）

为什么 stage 内嵌 if 判断总失败？Groovy 表达式和 Jenkins 步骤的边界在哪

Jenkins Pipeline 不是纯 Groovy 脚本，它是“声明式”或“脚本式”两层结构。在 steps 块内，你只能调用 Jenkins 步骤（如 sh、echo），不能直接写 if (env.BRANCH_NAME == 'main') —— 这会报 Expected a step，因为 Groovy 控制流语句不是“步骤”。

正确做法分两种场景：

• 简单分支判断：用 when { branch 'main' } 声明式语法（仅限声明式 Pipeline）
• 复杂逻辑（比如根据文件是否存在决定是否构建）：改用脚本式 Pipeline，在 script 步骤里写 Groovy，例如：script { if (fileExists('pom.xml')) { sh 'mvn test' } }
• env 是只读映射，修改它（如 env.MY_VAR = 'x'）只在当前 stage 生效，跨 stage 无效；要用 params 或 withEnv 显式传递
• 所有 sh 命令默认在子 shell 执行，变量不会透出；需要跨命令共享值，得用 readFile/writeFile 或 sh(returnStdout: true) 捕获输出

真正容易被忽略的是：Pipeline DSL 对 Groovy 的支持是“按需解析”的——Jenkins 先做语法校验再执行，所以看似合法的 Groovy（比如闭包嵌套太深、用了未导出的类）可能在预编译阶段就失败，而不是运行时报错。