如何编写Jenkins Pipeline_Jenkinsfile基础语法说明-Golang-PHP中文网

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

如何编写jenkins pipeline_jenkinsfile基础语法说明

什么是 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 步骤注入环境变量或文件。

Jenkins

通过 REST API 与 Jenkins CI/CD 服务器交互。适用于触发构建、查询状态、查看控制台输出、管理任务或监控 Jenkins...

下载

常见错误现象：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) 捕获输出