options { timeout(...) } 实现刚性熔断，即不可绕过的全局执行时限，超时后 jenkins 强制中止整个构建流程并标记为 aborted，覆盖所有步骤且无法被 try-catch 忽略。
在 Jenkins Pipeline 中，用 options { timeout(...) } 实现“刚性熔断”，本质是设置**不可绕过的全局执行时限**，一旦超时，Jenkins 会强制中止整个构建流程（包括所有 stage、step 和子进程），不依赖外部服务响应或脚本内部逻辑——这正是应对第三方接口卡死最直接有效的手段。
明确 timeout 的作用层级与刚性特征
options { timeout(...) } 是声明式 Pipeline 的顶层控制选项，它作用于整条流水线的生命周期。和 stage 内部的 timeout{...} 不同，它：
- 覆盖所有 agent 上的执行步骤，包括 shell、script、input、waitUntil 等
- 由 Jenkins Controller 主动监控并强制终止，不等待进程自然退出
- 触发时抛出
org.jenkinsci.plugins.workflow.steps.FlowInterruptedException，构建状态标记为 ABORTED（非 FAILURE），便于区分“主动熔断”和“业务失败” - 无法被 try-catch 捕获并忽略，真正实现“刚性”——这是它区别于代码级超时（如 curl -m）的核心优势
典型卡死场景与配置建议
第三方接口卡死常出现在以下环节，需按风险等级设定合理 timeout：
-
Git 拉取阶段：网络抖动或仓库响应慢。建议设为
timeout(time: 15, unit: 'MINUTES')，配合 JVM 级 Git 超时参数（-Dorg.jenkinsci.plugins.gitclient.Git.timeOut=15）双保险 -
部署/调用外部 API 阶段：如调用云平台 SDK、数据库迁移工具、认证中心等。若正常耗时约 2–5 分钟，应设为
timeout(time: 8, unit: 'MINUTES')，留出缓冲但杜绝长挂 -
健康检查循环等待：如轮询第三方服务就绪状态。必须禁用无限 while 循环，改用带 timeout 包裹的 waitUntil + 最大重试次数，例如：
timeout(time: 10, unit: 'MINUTES') { waitUntil { sh(script: 'curl -s http://thirdparty/ready | grep ok', returnStatus: true) == 0 } }
避免常见失效陷阱
即使写了 options { timeout }，仍可能“不生效”，关键原因有：
-
agent 未正确分配：若使用
agent none或动态 label 匹配失败，Pipeline 可能卡在“等待 agent”阶段——该阶段 不受 options.timeout 管控。务必确保agent any或具体 label 可稳定获取节点 - 插件或 step 自身阻塞 Controller：极少数老旧插件（如某些自定义 build-step）在执行中不响应中断信号。升级插件至最新版，优先选用 Jenkins 官方维护的 step
-
timeout 单位写错或遗漏引号：必须是
unit: 'MINUTES'（单引号 + 大写），写成unit: MINUTES或unit: "minutes"将导致语法错误或静默忽略 -
与 stage 级 timeout 嵌套冲突：全局 timeout 若短于 stage 内 timeout，以更严格的为准；但若 stage 内用了
timeout{...}且未加 error handling，可能掩盖真实卡点。建议只保留一层，优先用全局 option
配套可观测性增强刚性效果
单纯熔断不够，还需快速定位“谁卡住了”。可在 Pipeline 开头添加：
options {<br>
timeout(time: 2, unit: 'HOURS')<br>
buildDiscarder(logRotator(numToKeepStr: '20'))<br>
}<br>
environment {<br>
JENKINS_DEBUG = 'true'<br>
}<br>
stages {<br>
stage('Debug Info') {<br>
steps {<br>
sh 'ps auxf | head -30'<br>
sh 'date; echo "Build started at $(date)" >> build.log'<br>
}<br>
}
这样一旦超时中止，日志里能清晰看到最后活跃的进程树和时间戳，大幅缩短故障归因时间。
