Jenkins共享库需按vars/src/resources规范组织，通过后台配置Git仓库并加载，在Jenkinsfile中用@Library调用vars脚本或实例化src类。
在 Jenkins 中用 Groovy 编写共享库，核心是把重复的流水线逻辑（比如构建、打包、推送镜像、发通知）抽出来，存到 Git 仓库里，再通过 Jenkins 配置加载，最后在 Jenkinsfile 里调用。它不是写个脚本扔进去就行，而是有约定结构、加载方式和调用规范的一套机制。
共享库的目录结构必须规范
共享库本质是一个 Git 项目，根目录下需包含三个关键子目录：
-
vars/：放全局可调用的 Groovy 脚本，文件名即变量名（如
deploy.groovy），里面必须定义call方法，才能在 Pipeline 中直接写deploy(...) -
src/：按 Java 包结构组织类（如
src/com/example/Utils.groovy），适合封装复杂逻辑、复用工具类，需用new com.example.Utils()实例化调用 -
resources/：存放 JSON、YAML、模板等静态资源，可通过
libraryResource('path/to/file.json')加载
这三个目录可以空着启动，但一旦要用某类功能，就得按对应位置放文件。比如只用简单函数，vars/ 就够了；要做类型封装或引入第三方库，就得走 src/。
在 Jenkins 后台配置共享库
进入 Manage Jenkins → Configure System → Global Pipeline Libraries，点击 “Add” 添加一个库：
-
Name：起个简短名字（如
mylib），后续在@Library中引用 -
Default version：填分支名（如
main）或标签（如v1.2），决定默认加载哪个版本 - Retrieval method：选 “Modern SCM”，然后配置 Git URL 和凭据
-
Load implicitly：勾选后，所有 Pipeline 自动可用该库，无需显式声明；不勾选则每次都要加
@Library
配置保存后，Jenkins 会在下次 Pipeline 执行前自动拉取并缓存代码。注意：修改共享库后，已运行的 Pipeline 不会自动更新，需手动触发或等待缓存刷新（默认 1 小时）。
在 Jenkinsfile 中调用共享库
调用方式分两种，推荐用第一种：
-
@Library 注解（静态加载）：写在
Jenkinsfile最顶部，编译期就绑定版本，安全稳定@Library('mylib@main') _pipeline { ... steps { script { deploy(appName: 'web') } } } -
library 步骤（动态加载）：运行时调用，适合根据参数切换不同库版本
steps { script { library identifier: 'mylib@feature-branch', retriever: modernSCM([ ... ]) } }
vars 下的脚本会自动变成全局变量，直接调用即可；src 下的类需显式 import 或 new 实例；resources 需配合 libraryResource 使用，不能直接读文件路径。
写一个可用的 vars 脚本示例
以 vars/notify.groovy 为例：
def call(Map args = [:]) {
def title = args.title ?: 'Pipeline Notification'
def message = args.message ?: 'Build completed.'
echo "Sending notification: ${title}"
// 实际可集成企业微信、邮件或 Slack
sh "echo '${message}' | mail -s '${title}' admin@example.com"
}
在 Jenkinsfile 中就能这样用：
@Library('mylib') _
pipeline {
agent any
stages {
stage('Notify') {
steps {
notify(title: 'Deploy Success', message: 'v1.0.5 deployed to staging')
}
}
}
}
不需要 import，不关心路径，只要名字对、结构对、配置对，就能跑起来。
