关键在于对齐库结构、加载方式、调用路径和上下文传递：Shared Library须为标准Git仓库（含vars/、src/、resources/），全局配置或@Library显式声明生效，vars中通过script参数调用DSL，调试必须在Jenkins临时Pipeline中验证。
在 Linux 环境下用 Jenkins Pipeline 的 Shared Library 实现跨项目自动化逻辑复用，关键不是“装插件”或“写脚本”，而是把库结构、加载方式、调用路径和上下文传递这四件事对齐。Jenkins 本身运行在 Linux 上，所以整个流程天然适配，但容易卡在权限、路径或沙盒限制上。
共享库必须按标准 Git 仓库组织
Shared Library 本质是一个独立的 Git 仓库（如 git@gitlab.example.com:ci/shared-lib.git），不是 Jenkins 本地目录。它必须包含以下结构：
-
vars/：放可直接在 Jenkinsfile 中调用的函数，文件名即函数名（如 deploy.groovy），内容需定义
call方法； - src/：放 Groovy 类（如 src/com/example/BuildHelper.groovy），需手动 import 并 new 实例，适合封装带状态或复杂逻辑；
-
resources/（可选）：放 JSON 模板、YAML 配置等非代码资源，用
libraryResource读取。
注意：仓库根目录不能有 Jenkinsfile；首次推送后，确保 Jenkins 能通过 SSH 或 HTTPS 拉取该仓库（Linux 上建议用 SSH Key 认证，并在 Jenkins 主机的 ~/.ssh/ 下配置好私钥）。
全局注册或显式声明，二者选一且必须生效
Shared Library 不会自动加载，必须明确告诉 Jenkins “从哪来、用哪个分支、怎么用”：
-
全局配置（推荐用于团队统一规范）：进入 Manage Jenkins → System Configuration → Global Pipeline Libraries，点击 Add，填入：
– Library Name（如 common-ci，后续 pipeline 中引用时用这个名字）
– Default Version（如 main）
– Retrieval Method 选 Modern SCM → Git → 填写仓库 URL 和凭据； -
Pipeline 内显式加载（更灵活，适合灰度验证）：
在 Jenkinsfile 开头第一行（不能有空行或注释）写：@Library('common-ci@v1.3') _
或在 script 内动态加载：library identifier: 'common-ci@v1.3', retriever: modernSCM(...)。
若提示 Library not found，先确认 Library Name 是否与全局配置完全一致（大小写敏感），再检查 Jenkins 日志中 SCM 拉取是否成功（常见于 Linux 主机没配 Git 凭据或 SSH key 权限不对）。
在 Jenkinsfile 中安全调用，避免沙盒报错
Shared Library 默认运行在 Jenkins 沙盒外，但不能直接使用 sh、node、env 等 Pipeline DSL —— 必须通过传入的 script 参数中转：
- 在 vars/deploy.groovy 中：
def call(Map config = [:]) {<br> def script = this<br> script.sh "echo deploying to ${config.env}"<br> script.echo "Done."<br>} - 在 Jenkinsfile 中调用：
deploy env: 'staging'
而不是sh 'xxx'直接写在 vars 文件里。
如果用了 @Grab 引入外部 jar，需在 Jenkins 全局配置中启用 In-process Script Approval 并批准对应签名，否则抛 RejectedAccessException（Linux 上该配置位于 Manage Jenkins → Script Approval）。
调试要贴近真实环境，别信本地 groovy 命令
在 Linux 终端执行 groovy deploy.groovy 是无效的 —— 它没有 script、env、currentBuild 等对象，结果不可信。正确做法是：
- 新建一个临时 Pipeline 任务；
- 选择 Pipeline script，粘贴最小可复现代码，例如：
@Library('common-ci') _<br>pipeline { agent any<br> stages { stage('Test') { steps { deploy env: 'dev' } } } }； - 直接构建并看控制台输出，这是唯一可靠的验证方式。
遇到问题时，打开 Jenkins 系统日志（Manage Jenkins → System Log），过滤关键词 shared-library 或 scm，能快速定位拉取失败、解析异常或权限拒绝等 Linux 特定问题。
