shared library 必须显式声明或全局配置才能生效：全局路径为「manage jenkins」→「system configuration」→「global pipeline libraries」，填入 scm 地址、分支及加载策略；pipeline 内可用 library 或 @library 注解（需置顶）；src/ 放需 import 的 groovy 类，vars/ 放自动注入的全局函数；调用 jenkins dsl 必须通过传入的 script 参数中转；本地调试不可靠，应使用 jenkins 临时 pipeline 验证。
Shared Library 在 Jenkins 中怎么加载才生效
不配置对的加载方式，写再好的脚本也根本不会被 Pipeline 调用到。Jenkins 默认不自动加载 Shared Library，必须在 Pipeline 里显式声明或全局配置绑定。
- 全局配置路径：「Manage Jenkins」→「System Configuration」→「Global Pipeline Libraries」，填入 SCM 地址（如 Git 仓库 URL）、默认分支（通常是
main或master）、加载策略（推荐Load implicitly仅限可信库） - Pipeline 内显式加载更可控：
library 'my-shared-library' version: 'v1.2'
，前提是该库名已在全局注册；否则会报错Library not found - 如果用
@Library('xxx') _注解，注意它只对当前 Pipeline 文件生效，且必须放在文件最顶部，空行或注释都不能在它前面
脚本放 src/ 还是 vars/？区别在哪
目录结构决定调用方式和作用域，放错位置会导致函数找不到或参数传不进去。
-
src/下放通用 Groovy 类，比如src/com/example/Deployer.groovy，需手动import后实例化使用：import com.example.Deployer<br>def deployer = new Deployer()
-
vars/下放全局可调用函数，文件名即函数名（如vars/deploy.groovy），自动注入 Pipeline 上下文，直接写deploy env: 'prod'就行 -
vars/文件里不能直接写class定义；想封装逻辑又需要状态管理，得用src/+ 构造函数传this（即 Pipeline 实例）
如何在 Shared Library 里安全访问 Jenkins 内置对象
直接用 sh、node、env 等会报 MissingMethodException，因为 Shared Library 默认运行在 sandbox 外、无上下文代理。
- 所有 Jenkins DSL 调用必须通过传入的
script参数中转，这是最稳妥的做法：def call(Map params) {<br> def script = params.script<br> script.sh 'echo hello'<br> script.env.BUILD_NUMBER<br>} - 不要在
src/类里硬编码sh，而应把script当依赖注入；否则单元测试没法 mock，上线后也容易因权限或沙盒失败 - 若用了
@Grab或外部 jar，记得在 Jenkins 全局配置里启用「In-process Script Approval」并批准对应签名，否则会卡在RejectedAccessException
为什么本地调试总和 Jenkins 行为不一致
Shared Library 没有官方本地运行环境，直接用 groovy xxx.groovy 会缺 script、env、currentBuild 等关键对象，结果不可信。
- 最小验证法：在 Jenkins 新建一个临时 Pipeline，用
@Library引入后直接调函数，比本地跑 Groovy 更真实 - 模拟
script对象可用org.jenkinsci.plugins.workflow.cps.CpsScript，但太重；简单场景建议用binding.setVariable('script', [:])手动塞 stub 方法 - 常见坑：本地用
File.exists()判断路径，但在 Jenkins agent 上路径是容器内路径，实际应统一走script.sh(returnStdout: true, 'pwd')动态获取
真正难的不是写逻辑，而是让逻辑在 Jenkins 的执行生命周期里稳稳接住每一次 node 分配、每一次 checkout、每一次凭据注入——这些细节不提前对齐，复用就只是多了一层出错路径。
