1. 为什么需要共享库？
复制粘贴 Jenkinsfile 的坏处是指数级的：一处改安全策略要改一百个仓库；通知渠道、制品上传、质量门禁各自分叉。 共享库把共性抽到 Groovy 组件里，业务仓库只保留差异参数（语言版本、artifact 名、环境列表）。 代价是：你维护的是内部平台产品，需要版本语义、发布说明与向后兼容策略。
图 1：共享库是“上游依赖”；业务仓是“调用方”——心态上要当内部开源项目维护。
2. 目录结构：vars/、src/、resources/
- vars/：每个 *.groovy 暴露为全局步骤，需实现 call 方法（可带参数）。适合团队自定义 standardPipeline() 这类入口。
- src/：标准 Groovy 包结构（如 org/team/PipelineBuilder.groovy），承载复杂类逻辑，由 vars 或 Pipeline 脚本 import 使用。
- resources/：非 Groovy 资源文件（模板、脚本片段），运行时通过 libraryResource 读取。
// vars/standardPipeline.groovy — simplified
def call(Map cfg) {
pipeline {
agent { label cfg.agentLabel ?: 'linux' }
stages {
stage('Build') {
steps { sh cfg.buildCommand ?: './mvnw -B package' }
}
}
}
}
// Jenkinsfile in an application repo
@Library('team-pipeline-lib@2.3.0') _
standardPipeline(
agentLabel: 'docker && jdk17',
buildCommand: './mvnw -B -DskipTests package'
)
注意：@Library('name@ref') 的 ref 可以是分支、tag 或 commit；
生产建议钉死 tag或经测试的分支，避免“共享库 main 一推送，全员流水线语义突变”。
3. 在 Jenkins 中注册：Global Pipeline Libraries
管理员在 Manage Jenkins → System → Global Pipeline Libraries 添加：名称（供 @Library 引用）、默认版本、SCM、凭据。 可勾选 Allow default version to be overridden、以及是否信任库（影响沙箱与加载行为，详见官方文档）。 团队应把库名、推荐版本、升级流程写进内部文档。
图 2：每次构建按需解析库版本——把“依赖升级”当成发布事件。
4. 版本治理：语义化与渐进 rollout
推荐对共享库打 Git tag（vMAJOR.MINOR.PATCH）：破坏性变更升主版本；新 stage 默认向后兼容。 可先让少数仓库在 @Library('lib@feature-xyz') 验证，再推广默认版本。 维护 CHANGELOG 与迁移指南，比口头通知可靠一个数量级。
5. 测试共享库
- 单元测试：使用社区工具（如 Jenkins Pipeline Unit 等）在 JVM 上模拟步骤；适合纯 Groovy 逻辑。
- 集成验证：专用“金丝雀”任务绑定候选 tag，跑真实 agent / credentials（缩小范围）。
- 代码评审：库变更必须双人 approve；禁止直接推默认分支。
图 3：像发布 SDK 一样发布共享库—— waves 降低“周五下午全员爆红”。
6. 反模式与风险
| 反模式 | 后果 |
|---|---|
| 默认跟踪 main 且不钉版本 | 上游小改引发大规模流水线失败 |
| 在库里藏环境特定 IP / 密钥 | 泄露面扩大；应走凭据与配置注入 |
| 巨型上帝步骤（几千行 call） | 难测难改；应拆类 + 资源文件 |
| 跳过评审直接推库 | 供应链风险；与“信任库”设置冲突 |
图 4：vars 像门面；复杂逻辑下沉到 src，资源外置——测试与复用都更轻松。
7. 本章清单
- 新建 Git 仓库，按 vars/ + src/ 搭骨架，提交最小可调用步骤。
- 在 Jenkins 注册 Global Pipeline Library，用 @Library 从试验项目引用 tag。
- 写 CHANGELOG 与升级策略；破坏性变更走 major 版本。
- 配置评审分支保护与只读默认权限；敏感操作走双人批准。
- 预告下一章：共享库跑在哪种 agent 上——容器与 Kubernetes 弹性。