Jenkins 插件找不到/装不上速查：更新中心、依赖链与离线 hpi
更新时间：2026-10-24。FAQ 速查页，面向在「系统管理 → 插件管理」里搜不到插件、或者点了安装却一直转圈/报红的同学。Jenkins 插件找不到的字面含义很朴素——控制器没拿到插件目录，或者拿到了但安装链断在中途——但背后的病因收敛在六根轴上：更新中心连不上、本地元数据过期没刷新、插件的依赖链一环缺货、插件版本和控制器版本不兼容、代理把请求拦了、以及离线环境根本没配 hpi 安装通道。顺一遍基本必中。如果你的问题是装好了插件但流水线里报
No such DSL method，那归 No such DSL method 速查 管。
本文要回答的问题
- 可选插件列表一片空白或搜什么都搜不到，是哪里断了？
- 报
There were errors checking the update sites怎么定位是网络还是证书？ - 装 A 插件时提示缺 B 插件的某个版本，依赖链怎么补？
- 离线（不出网）的机器怎么装插件？
- 升级控制器之后一堆插件标红「不兼容」怎么办？
一、报错原文与典型现象
插件类报错的原文分散在三处：插件管理页的红条、安装详情的日志、以及控制器系统日志（/var/log/jenkins/jenkins.log）。几个典型长相（控制器地址以 jenkins.example.com 占位）：
There were errors checking the update sites: SocketTimeoutException:
connect timed outjava.io.IOException: Failed to load: Git plugin (git 5.x)
- Plugin is missing: workflow-scm-step (2.13)No such plugin: workflow-aggregator
# 或：可选插件搜索框里输入后结果为空读报错先分两层：「拿不到目录」层（SocketTimeout、SSLHandshakeException、搜索结果为空）是更新中心通道的事；「拿到了装不上」层（Plugin is missing、version xxx required）是依赖与版本的事。两层修法完全不同，先定性再动手。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| 可选插件页空白、搜索无结果 | 更新中心不可达（断网/防火墙/代理） | 高级页点「立即获取」看错误详情 | 修网络/配代理；换国内镜像源 |
| 报 SocketTimeout 或 SSLHandshake | 出网被代理拦或证书链不被信任 | 控制器上 curl -I https://updates.jenkins.io | 系统管理里配 HTTP 代理；导入企业根证书 |
| 一切正常但新插件搜不到 | 本地更新中心元数据过期 | 看高级页「上次更新时间」 | 点「立即获取」强制刷新元数据 |
| 安装报 Plugin is missing: xxx | 依赖链中某个插件没装或版本不够 | 报错里点名的缺货插件逐一核对 | 先装依赖插件，再回头装目标插件 |
| 报 version xxx (or newer) required | 插件要求的 Jenkins 核心版本更高 | 对比报错里的版本与页脚控制器版本 | 升控制器，或选该插件的旧版本 |
| 离线机器无法装插件 | 无出网通道且未备 hpi 文件 | 机器是否能解析外网域名 | 有网机下载 hpi 及其依赖，高级页上传安装 |
| 升级后插件标红 Incompatible | 插件版本与新版核心不匹配 | 插件管理「已安装」页看红色警告 | 逐个点更新到兼容版本；停更插件找替代 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓住分水岭：插件管理高级页里那个「立即获取（Check now）」按钮按下去，错误详情会直接告诉你断在哪一层。超时类错误走左支查网络与代理；明确点名缺某个插件的走右支补依赖。不要还没分层就反复点安装——依赖断着，点一百次也是同一个错。
四、逐条排查展开
先让更新中心通道自己说话。 插件管理 → 高级（Advanced）页底部有「立即获取」按钮，按完页面顶部会给出每个更新站点的探测结果。SocketTimeoutException: connect timed out 是 TCP 层不通；SSLHandshakeException 是证书链的事（常见于企业代理做 TLS 拦截，Jenkins 不认代理的根证书）；Signature verification failed 则是元数据被中间设备改过。控制器所在机器上直接验证：
curl -I https://updates.jenkins.io/update-center.json不通就是网络/防火墙的事，找运维开端口或在「高级 → HTTP Proxy Configuration」里填代理并点验证；SSL 类错误需要把企业根证书导入 Jenkins 用的 JDK 信任库。
元数据过期会让人以为插件不存在。 Jenkins 把更新中心的插件目录缓存在本地，默认定期刷新；控制器长期不重启或刷新失败时，新出的插件搜不到、旧插件的新版本也看不到。看高级页显示的元数据时间戳，太旧就点「立即获取」。这不是玄学——元数据就是一份 JSON 清单，搜不到先怀疑清单过期。
依赖链断裂要按报错点名顺序补。 Plugin is missing: workflow-scm-step (2.13) 的意思是目标插件声明依赖 workflow-scm-step 的 2.13 以上版本，而你环境里没装或版本低。处置是先到「已安装」页搜这个依赖：没装就先装它（它自己可能还有依赖，一路递归）；装过但版本低就先升级它。装完所有依赖再回头装目标插件，一次成功。
版本兼容矩阵别硬闯。 报错 requires Jenkins 2.xxx or newer 说明插件新版放弃了你当前的核心版本。两条路：升级控制器（推荐，但要规划回归），或者到插件官网的 Releases 页找你核心版本兼容的历史版本，下载 hpi 走高级页「Deploy Plugin」手动上传。别反过来拿新版 hpi 硬塞，启动时会直接禁用该插件。
离线安装的完整姿势。 内网控制器不出网时，在有网机器上从插件官网（plugins.jenkins.io）下载目标插件的 .hpi 文件——注意官网页面会列出该插件的全部依赖，依赖的 hpi 也要一并下载。然后在插件管理 → 高级 → Deploy Plugin 逐个上传，顺序是先依赖后目标，全部装完重启控制器。依赖漏一个是离线安装失败的第一大原因。
镜像源与开机向导的坑。 默认更新中心对部分网络环境不友好，可在高级页把 Update Site 的 URL 换成镜像地址（例如清华镜像的 jenkins/updates 路径），保存后立即获取。另外全新安装时开机向导选「安装推荐插件」会一口气拉几十个插件，网络不稳时大片失败——此时不必重装，进插件管理把失败的逐个补装即可，向导失败清单在日志里都有记录。
升级控制器后的批量标红。 核心大版本升级后，老插件可能因 API 变更被标记 Incompatible 并被禁用。处置顺序：先把「已安装」页所有可更新的插件更到最新，重启；仍标红的逐个查插件官网的兼容性说明，长期停更的找替代插件。升级前先导出插件清单（脚本控制台或系统信息页）是个好习惯，回滚有据。
五、规范做法与预防
- 镜像源与代理配置进部署文档：新控制器搭好第一件事固化这两项，别让下一个值班人重新踩。
- 插件清单纳入版本管理：用脚本定期导出已装插件及版本，升级前 diff。
- 升级流程化：先在测试控制器升核心 + 全量更新插件，跑回归流水线绿了再动生产。
- 离线环境建 hpi 仓库：常用插件及其依赖的 hpi 文件集中归档，标注兼容的核心版本区间。
- 少即是多：插件装得越少，依赖链断裂面和升级冲突面越小；只用得到一步的插件别常驻。
- 盯「立即获取」结果：把更新中心探测失败纳入监控告警，别等装插件那天才发现通道早断了。
这一篇在知识体系里的位置
本篇是 Jenkins 排错速查簇的插件安装入口篇，定位「插件装不上」：装好了但流水线里步骤不认识看 No such DSL method 速查；构建排队或报没有可用节点看 Jenkins 节点离线速查。「立即获取 → 错误分层 → 补依赖/修通道」这条主线对一切插件类问题通用。
一句话总结
Jenkins 插件找不到先在插件管理高级页点「立即获取」看错误详情分层：超时/SSL 类是更新中心通道问题——curl 验证连通性、配代理或换镜像源、SSL 类导入企业根证书；明确点名 Plugin is missing 或版本要求的是依赖与兼容问题——按报错顺序补依赖链，核心版本不够就升控制器或选插件的旧版 hpi 手动上传；离线环境在有网机下载 hpi 连同全部依赖，高级页逐个上传后重启。镜像源、代理配置与插件清单进部署文档和版本管理，这类问题基本绝迹。