jenkins pipeline 中 retry 指令必须嵌套在 script 或 steps 内部，仅对抛出异常的操作生效，retry(n) 表示最多执行 n 次（含首次），需配合非零退出码触发，建议网络类任务设 2–3 次并手动加 sleep 实现退避，避免全局包裹 parallel，推荐单分支独立配置并结合 try-catch 控制失败流程。
Jenkins Pipeline 中实现失败后自动重试，核心是用 retry 指令包裹易出错的步骤，但必须放在正确的执行上下文中——它只对抛出异常的操作生效，且作用范围仅限于其直接包裹的代码块。
重试必须包裹在 script 或 steps 内部
retry 不是 stage 或 pipeline 级别的关键字，不能直接写在 stage 外层。它必须嵌套在 script 块或支持 Groovy 执行的 steps 中，否则会被忽略。
- ✅ 正确写法：在
script块里调用retry(3) { sh '...' } - ❌ 错误写法：把
retry(3)直接写在steps下，不加script包裹 - ⚠️ 注意：shell 命令需返回非零退出码（如
exit 1），Jenkins 才会识别为失败并触发重试
重试次数与失败判定逻辑
retry(n) 表示最多尝试 n 次（含首次执行），不是“额外重试 n 次”。例如 retry(3) 总共最多运行 3 次，第 1 次失败后自动重试第 2 次，再失败则重试第 3 次；第 3 次仍失败，整个 retry 块才报错退出。
- 建议根据任务特性设值：网络请求类常用 2–3 次，编译类一般不重试（失败多为真实问题）
- 重试之间无默认间隔，若需退避策略，需手动加
sleep，例如：retry(3) { sh 'curl -s http://api'; sleep(5) }
避免重试放大问题：配合 try-catch 控制流程
单纯用 retry 可能掩盖真正错误，尤其当失败由数据状态污染或前置步骤残留导致时。推荐在外层加 try-catch，便于记录日志、标记构建结果或跳过后续依赖步骤。
- 例如：重试失败后设置
currentBuild.result = 'UNSTABLE'，而非直接让整条流水线失败 - 也可在 catch 中调用
echo "Stage X failed after retries"，方便定位问题环节 - 注意：catch 到的异常是 retry 块整体失败后的抛出，不是每次重试的中间异常
并行任务中慎用全局 retry
在 parallel 块内对单个分支使用 retry 是安全的，但不要把 retry 放在整个 parallel 结构外——这会导致全部并行分支重复执行，浪费资源且可能引发竞态。
- ✅ 推荐：每个子 stage 内独立配置 retry，如
stage('API Test') { steps { script { retry(2) { sh './test-api.sh' } } } } - ❌ 避免：
retry(2) { parallel { ... } }—— 这会让整组并行任务重复跑两次 - 进阶可结合
catchError实现“部分失败不中断”，再配合 retry 提升单任务韧性
