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（比如闭包嵌套太深、用了未导出的类）可能在预编译阶段就失败，而不是运行时报错。
