Jenkins 构建工具未安装速查：command not found、全局工具配置与容器镜像
更新时间：2026-10-24。FAQ 速查页，面向流水线跑到
mvn -v、node -v、go build这一步直接command not found的同学。command not found 的意思很直白：shell 在 PATH 里没找到这个可执行文件——工具没装、装了但不在 PATH、PATH 配了但只对交互式 shell 生效，三者在 Jenkins 里各占一方。Jenkins 的特殊性在于它有两套「装工具」的机制：节点 OS 层预装（yum/apt/手动）和全局工具配置（Global Tool Configuration 里登记 JDK/Maven/Node，由 tools 指令注入 PATH），两套机制各管各的，混着用最容易出「明明装了还是找不到」。病因收敛在六根轴上：全局工具没登记或名字拼错、tools 指令没写、自动安装下载失败（网络或版本号失效）、agent 节点 PATH 不含工具目录、Docker agent 镜像里没装、要求的版本与节点实际版本不匹配。顺一遍基本必中。如果工具找到了但跑起来版本行为不对，转 Jenkins 版本不匹配速查。
本文要回答的问题
- 节点上手动执行
mvn -v正常，流水线里为什么mvn: command not found？ - 全局工具配置里登记了 Maven，流水线不写 tools 能用吗？
- 自动安装选上了，构建时下载 JDK 失败怎么办？
- Docker agent 里第一条命令就 not found，镜像要改什么？
- 多台 agent 有的能跑有的 not found，怎么对齐？
一、报错原文与典型现象
command not found 的现场按「谁找不到」分三类：流水线步骤缺工具、自动安装环节失败、容器镜像缺依赖（控制器地址以 jenkins.example.com 占位，路径以 /proj/demo 占位）：
# 现场一：sh 步骤直接找不到命令
+ mvn clean package
/proj/demo@tmp/durable-xxx/script.sh: line 1: mvn: command not found
# 现场二：自动安装阶段失败（tools 指令触发的下载）
Unpacking https://archive.apache.org/dist/maven/maven-3/3.9.6/...
ERROR: Failed to download ... (HTTP 404)
Tool installation failed: Maven 3.9.6# 现场三：Docker agent 里连基础命令都没有
+ node -v
/proj/demo@tmp/durable-xxx/script.sh: line 1: node: command not found三类现场的修法不同：现场一补 PATH 或补 tools 声明，现场二修下载源或改手动安装，现场三换镜像或 Dockerfile 里补装。先对号入座。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| mvn/java not found | 全局工具未登记或流水线没写 tools | 看 Jenkinsfile 有没有 tools 块 | 全局工具登记同名，pipeline 加 tools |
| tools 写了仍 not found | tools 里的 name 与登记名不一致 | 对比两处拼写含大小写 | 改成完全一致的名字 |
| 安装阶段 HTTP 404/超时 | 自动安装下载源失效或网络不通 | 节点上 curl 下载地址 | 换镜像源或改手动安装目录 |
| 节点手动能跑流水线不能 | 工具在交互 PATH 里而不在 Jenkins PATH | 流水线里 echo $PATH 对比 | 用 tools 注入或在节点属性配 PATH |
| Docker agent 内 not found | 镜像没装该工具 | docker run --rm <镜像> which xxx | 换带工具的镜像或自建镜像 |
| 这台 agent 能跑那台不能 | 节点间环境不齐 | 两节点分别 which mvn | 用 label 绑定有工具的节点并统一装机 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓分水岭：第一步判工具来源——流水线里写了 tools { maven 'maven-3.9' } 走 Jenkins 工具注入路线，没写就是依赖节点预装或镜像自带，两条路线的排查面板完全不同。第二步节点路线查 PATH、容器路线查镜像，用「流水线里 echo PATH + which」这条最便宜的确诊命令。
四、逐条排查展开
全局工具登记与 tools 指令是一对，缺一半就 not found。 在「全局工具配置」里登记了 Maven 3.9.6、起了个名字叫 maven-3.9，这只是告诉 Jenkins「这个工具有个家」；流水线里不写 tools { maven 'maven-3.9' }，Jenkins 不会把它的 bin 目录注入 PATH。反过来 tools 写了但全局配置里没登记同名条目，构建会在启动阶段就报工具不存在。名字是字符串精确匹配，Maven-3.9 与 maven-3.9 是两个工具——大小写不一致是高频拼写事故。
自动安装失败多半是下载源问题。 全局工具里勾了「自动安装」，Jenkins 会在首次使用时从 Apache/Oracle 官方地址下载——官方归档站对老版本会挪路径（404），公司网络出境也可能超时。验证：把日志里的下载 URL 抄出来在节点上 curl 一遍。处置：下载器换成内部镜像源（Install from 自定义 URL），或者干脆关掉自动安装、在节点上手动装好并把「安装目录」指过去——手动安装可控性远高于自动下载。
节点预装工具找不到，九成是 PATH 作用域。 你在节点上用 SSH 登录、mvn -v 正常，是因为 /etc/profile.d/ 或 ~/.bashrc 给交互式 shell 加了 PATH；Jenkins 的 agent 进程不读这些文件，它只继承启动时的环境。确诊：流水线里加一步 sh 'echo $PATH && which mvn || true' 对比登录 shell 的结果。处置：优先用 tools 机制统一管理；必须在节点层解决的，在节点配置的「环境变量」里显式加 PATH+TOOLS=/opt/maven/bin，不要依赖 shell rc 文件。
Docker agent 的 not found 是镜像问题，与节点无关。 agent { docker { image 'maven:3.9-eclipse-temurin-21' } } 里第一条 node -v not found，是因为这个镜像只有 Maven 和 JDK——镜像即环境，容器里没有就是没有。验证：docker run --rm <镜像> sh -c "which node"。处置：换更全的官方镜像，或维护一个团队基础镜像的 Dockerfile（FROM maven:... + RUN apt-get install -y nodejs ...），推到内部仓库统一引用。镜像选型一次到位，比在流水线里现装省时且可复现。
多 agent 环境不齐靠 label 收敛。 「agent-1 能跑、agent-2 not found」说明节点间工具不齐。短期：给装了工具的节点打 label（如 has-maven），流水线 agent { label 'has-maven' } 只调度到可用节点；长期：节点装机用同一套 Ansible/初始化脚本，工具版本与路径写进基线，新节点上线先跑一条「工具自检流水线」再接入构建池。
版本不匹配是 not found 的邻居，别混诊。 command not found 是没有这个命令；命令在但版本不对（mvn 跑起来了、编译报 invalid target release: 21）是另一个病位——那是 JDK 版本问题，走 Jenkins 版本不匹配速查 的口径。两类症状在日志里一眼可分：前者 shell 报错、后者工具自己报错。
五、规范做法与预防
- 工具走 tools 机制：能用全局工具配置的就不在节点上手装，声明式
tools {}写进 Jenkinsfile 模板。 - 命名规范：工具名统一
<名称>-<主版本>小写（maven-3.9、jdk-21、node-20），改名走评审。 - 自动安装慎用：生产环境优先手动安装或内部镜像源，官方下载地址变动不该影响构建。
- 镜像即环境：Docker agent 用团队维护的基础镜像，Dockerfile 进版本库，换镜像即换环境的显式变更。
- 节点上线门禁：新 agent 接入前跑工具自检（java/mvn/node 版本输出进日志），不齐不放行。
- 版本号落日志：每条流水线第一 stage 打印
java -version && mvn -v等版本信息，出问题时免去复现成本。
这一篇在知识体系里的位置
本篇是 Jenkins 排错速查簇的「工具环境」入口：工具在但版本不对看 Jenkins 版本不匹配速查；装好了但权限不让执行看 Jenkins 权限不足速查；依赖仓库连不上导致自动安装失败看 Jenkins 连接被拒速查；路径写错类问题看 Jenkins 路径不存在速查；同簇还有 Jenkins 命令找不到速查、Jenkins 节点离线速查。「先判工具来源是 tools 注入还是节点预装，再分 PATH 与镜像两侧查」这条主线对一切 CI Agent 环境类问题通用。
一句话总结
Jenkins command not found 先判工具来源：走全局工具的，确认「登记同名 + Jenkinsfile 写 tools」成对存在，自动安装失败就换内部源或改手动安装指安装目录；走节点预装的，用流水线 echo PATH 对比登录 shell 确诊 PATH 作用域问题，在节点环境变量里显式补；Docker agent 的 not found 一律是镜像问题，换镜像或维护团队基础镜像。多 agent 不齐用 label 绑定加装机基线收敛，工具清单与版本号落日志后这类问题基本绝迹。