Jenkins Share Library教程 —— 企业级 Jenkins Shared Library 实战示例

写在前面

好久不见～最近状态稍缓，更新也慢了些，这篇文章同样让大家等了挺久，先跟大家说声抱歉。

如果你认真读了前面几篇，还跟着实践了，那到这里，咱们就要正式开启真正的 “进阶阶段” 啦！

确实，大多数公司内部的 Jenkins Shared Library 不只是简单的“封装几个 stage”而已，它们往往包含：

• workspace 清理机制（避免磁盘爆满）
• 缓存/依赖重用逻辑
• 多分支/多环境配置
• 动态参数和条件逻辑
• 流水线钩子（pre/post hooks）
• 高级通知系统（Slack、邮件、飞书、Teams）

下面，我们可以一起写一个更“企业级”的案例，会让你看懂为什么公司那套 Shared Library 那么复杂了。

目标：构建一个带 workspace 清理、缓存管理、错误恢复、通知系统的可复用 CI Pipeline。

一、项目结构

jenkins-shared-lib-enterprise/
├── vars/
│   ├── enterprisePipeline.groovy       # 主入口 Pipeline
│   ├── workspaceManager.groovy         # 清理与准备工作区
│   ├── notifyManager.groovy            # 通知模块
│   ├── gitHelper.groovy                # Git 拉取与分支操作
├── src/org/company/
│   ├── Utils.groovy                    # 工具类（时间戳、日志、重试等）
│   └── ConfigLoader.groovy             # YAML/JSON 配置读取器
└── resources/templates/└── notifyTemplate.txt

二、清理函数

📄 vars/cleanWorkspace.groovy

def call(Map config = [:]) {def cleanBeforeBuild = config.get('clean', true)def keepPatterns = config.get('keep', ['.git', '.gradle'])if (!cleanBeforeBuild) {echo "⏭️ Skipping workspace cleanup."echo "✅ Workspace ready at: ${pwd()}"return}echo "🧹 Cleaning workspace, preserving: ${keepPatterns}"def os = getOS()if (os == 'Windows') {cleanWindows(keepPatterns)} else {cleanUnix(keepPatterns)}echo "✅ Workspace ready at: ${pwd()}"
}// 判断操作系统
private String getOS() {def osName = System.getProperty('os.name').toLowerCase()return osName.contains('windows') ? 'Windows' : 'Unix'
}// Unix/Linux/macOS 清理方式
private void cleanUnix(List keepPatterns) {def patternStr = keepPatterns.join('|')sh """echo "Running on Unix/Linux..."ls -A1 | grep -v -E '^(${patternStr})\$' | xargs rm -rf || true"""
}// Windows 清理方式（使用 cmd 或 PowerShell）
private void cleanWindows(List keepPatterns) {// 转成小写用于比较def keepSet = keepPatterns.collect { it.toLowerCase() } as Set// 获取当前目录下所有文件/目录（包括隐藏）def files = new File(pwd()).listFiles()if (!files) returnfiles.each { file ->def name = file.name.toLowerCase()if (!keepSet.contains(name)) {echo "🗑️ Deleting: ${file.name}"deleteFileOrDir(file)}}
}// 安全删除文件或目录（递归）
private void deleteFileOrDir(File file) {try {if (file.directory) {file.deleteDir() // 递归删除目录} else {file.delete()}} catch (Exception e) {echo "⚠️ Failed to delete ${file.name}: ${e.message}"}
}

功能说明：

• 默认在每次构建前清理工作区（但保留 .git、.gradle 等缓存目录）

• 公司里这样做是为了避免：

  • Jenkins 节点磁盘爆满
  • 前次构建残留文件导致构建异常

Jenkinsfile 调用方式

@Library('my-shared-lib') _pipeline {agent any stages {stage('Cleanup') {steps {script {cleanWorkspace(clean: true,keep: ['.git', '.gradle', 'settings.gradle'])}}}// ... 其他阶段}
}

运行后，你会在控制台输出看到：

三、通知模块

📄 vars/notifyManager.groovy

def call(Map args = [:]) {def status = args.status ?: 'SUCCESS'def message = args.message ?: "Build completed."def color = status == 'SUCCESS' ? 'good' : (status == 'FAILURE' ? 'danger' : 'warning')def project = env.JOB_NAMEdef buildUrl = env.BUILD_URLdef fullMessage = """[${status}] ${project}${message}👉 ${buildUrl}"""echo "🔔 Notify: ${fullMessage.trim()}"
}

Jenkinsfile 调用方式

@Library('my-shared-lib') _pipeline {agent any  // 可以是 linux、windows、docker 等stages {stage('Cleanup') {steps {script {notifyManager(status: 'SUCCESS',message: 'Build completed.')}}}// ... 其他阶段}
}

运行后，你会在控制台输出看到：

四、Git 操作封装

📄 vars/gitHelper.groovy

// vars/gitCheckout.groovy
def call(Map config = [:]) {def repo = config.repodef branch = config.get('branch', 'main')def credentialsId = config.get('credentialsId', 'git-credentials')if (!repo) {error "❌ gitCheckout: 'repo' parameter is required!"}echo "🔁 Checking out ${repo} (branch: ${branch})"checkout([$class: 'GitSCM',branches: [[name: branch]],userRemoteConfigs: [[url: repo,credentialsId: credentialsId]]])
}

Jenkinsfile 调用方式

@Library('my-shared-lib') _pipeline {agent anyoptions {skipDefaultCheckout()  // 👈 关键！跳过默认的 SCM 步骤}parameters {string(name: 'GIT_REPO', defaultValue: 'your giturl', description: 'Git repository URL')string(name: 'GIT_BRANCH', defaultValue: 'master', description: 'Branch to build')}stages {stage('Checkout Code') {steps {script {def repo = params.GIT_REPOdef branch = params.GIT_BRANCHecho "🔁 开始拉取代码：${repo} (分支：${branch})"// 调用 vars/gitHelper.groovygitHelper(repo: repo,branch: branch,credentialsId: 'gitee-credentials'  // 替换为你的实际凭据 ID)}}}stage('Debug') {steps {echo "📦 当前路径：${pwd()}"bat 'git branch -a'bat 'git log --oneline -5'}}}post {failure {echo "❌ 构建失败！"}}
}

运行后，你会在控制台输出看到：

五、核心 Pipeline

📄 vars/enterprisePipeline.groovy

import com.company.Utilsdef call(Map config = [:], Closure customStages = null) {echo "repo: ${config.repo}, branch: ${config.branch}"// 初始化Utils.printHeader(this, "Initializing Pipeline")cleanWorkspace([clean: true, keep: ['.git']])gitHelper([repo: config.repo, branch: config.branch])// 构建Utils.printHeader(this, "Build Stage")try {bat config.buildCommand ?: 'mvn clean package -DskipTests'} catch (err) {notifyManager([status: 'FAILURE', message: "Build failed: ${err.message}"])error("Build failed.")}// 测试Utils.printHeader(this, "Test Stage")try {bat config.testCommand ?: 'mvn compile test'} catch (err) {notifyManager([status: 'FAILURE', message: "Tests failed: ${err.message}"])error("Tests failed.")}// 自定义阶段if (customStages != null) {Utils.printHeader(this, "Custom Stages")customStages()}// 部署if (config.deploy == true) {Utils.printHeader(this, "Deploy Stage")// bat config.deployCommand ?: './deploy.sh'notifyManager([status: 'SUCCESS', message: "Deployed successfully!"])}// 收尾def result = currentBuild.result ?: 'SUCCESS'notifyManager([status: result, message: "Pipeline finished with status: ${result}"])Utils.printHeader(this, "Cleaning workspace after build")cleanWorkspace([clean: true])
}

Jenkinsfile 调用方式

@Library('my-shared-lib') _pipeline {agent anytools {maven 'maven'}parameters {string(name: 'REPO_URL', defaultValue: 'your giturl', description: 'Git仓库地址')string(name: 'BRANCH', defaultValue: 'master', description: '分支')}stages {stage('企业流水线') {steps {script {enterprisePipeline([repo: params.REPO_URL,branch: params.BRANCH])}}}}
}

运行后，你会在控制台输出看到：

写在最后

本文以 Maven 项目为示例，核心思路可迁移至其他语言项目，后续仍有扩展空间，感兴趣者可自行探索。

感谢你的认真阅读！若文章对你有价值，欢迎文末留言交流，也请帮忙点赞转发，谢谢支持！