1. 从一条报错信息说起docker: not found 到底在说什么如果你在 Jenkins 上跑过 Pipeline大概率见过这个场景流水线跑到某个 stage日志里突然蹦出一行docker: not found然后整个构建直接挂掉。第一次遇到的人往往会愣一下——明明在服务器上敲docker ps一切正常怎么到了 Jenkins 里就找不着了这个报错的字面意思很直白Jenkins 执行构建任务的那个进程在它自己的环境变量 PATH 里找不到名为docker的可执行文件。注意这里的关键词是它自己的环境变量。很多人排查时习惯登录服务器在终端里验证 docker 命令是否可用验证通过后就觉得没问题了。但 Jenkins 的构建进程和你登录的交互式 shell环境变量往往不是一套东西这正是问题最容易藏身的地方。我先把结论摆出来docker: not found本质上不是 Docker 坏了而是执行环境与预期环境不一致。它可能发生在几个完全不同的层面——Jenkins 主节点直接执行、Jenkins 通过 SSH 连到远程节点执行、在容器化的 agent 里执行、或者 Pipeline 里用了sh步骤但 shell 类型不对。每一种情况的根因和修法都不一样所以不能看到这个报错就无脑去装 Docker。这篇内容适合三类人看一是刚接手 CI/CD 流水线、被这个报错卡住的运维或开发同学二是想把 Jenkins 和 Docker 集成做扎实、避免反复踩坑的工程师三是需要给团队搭建标准化构建环境、希望一次性把环境问题理清楚的技术负责人。我会从报错背后的执行链路讲起把几种典型场景逐一拆开给出可复现的排查步骤和修复方案最后再聊聊怎么从根上避免这类环境问题反复出现。需要提前说明的是下面涉及的所有命令和配置都是基于常见实践整理的通用做法具体路径和版本请以你自己的环境为准。不同操作系统、不同 Jenkins 部署方式裸机、容器、Kubernetes细节会有差异但排查思路是相通的。2. 先搞清楚是谁在报错Jenkins 执行链路拆解2.1 一条 Pipeline 命令的完整旅程要理解docker: not found得先知道当你在 Jenkinsfile 里写下一行sh docker build ...时背后到底发生了什么。这行命令并不是凭空执行的它要经过好几层接力。第一层是 Jenkins 控制器Controller老版本叫 Master。它负责解析 Pipeline 脚本、调度任务但真正执行sh步骤的往往不是它。第二层是 agent老版本叫 slave也就是实际干活的节点。第三层是 agent 上的 shell 进程Jenkins 会启动一个 shell 来跑你的命令。第四层才是 shell 去 PATH 里找docker这个可执行文件。docker: not found这个报错是第三层的 shell 发出来的。它意味着 shell 在自己的 PATH 环境变量所列的目录里翻遍了都没找到docker。所以问题要么出在docker 根本没装在这个节点上要么出在装了但 PATH 里没有它要么出在这个 shell 的环境变量被裁剪过。2.2 交互式 shell 和非交互式 shell 的环境差异这是最容易被忽略、也最坑人的一点。你 SSH 登录服务器时系统启动的是一个交互式登录 shell它会读取/etc/profile、~/.bash_profile、~/.bashrc这些配置文件把 PATH 设置得妥妥当当。而 Jenkins 执行sh步骤时启动的是一个非交互式、非登录 shell它通常只读取很有限的环境配置甚至什么都不读。结果就是你在终端里echo $PATH看到一长串路径包含/usr/local/bin、/usr/bin等等而 Jenkins 里echo $PATH可能只有短短几个目录。如果 Docker 恰好装在/usr/local/bin很多手动安装的场景就是这样而 Jenkins 的 PATH 里没有这个目录那docker: not found就顺理成章地出现了。提示判断是不是 PATH 问题最快的办法是在 Pipeline 里加一步sh echo $PATH和sh which docker || echo no-docker把 Jenkins 视角的环境打印出来和你终端里的对比差异一目了然。2.3 三种典型部署形态对应的不同根因同样是docker: not found在不同的 Jenkins 部署形态下根因分布差别很大。我把它整理成一张表方便你对号入座。部署形态执行命令的位置最常见的根因Jenkins 裸机部署任务跑在控制器上控制器所在主机PATH 未包含 docker 安装目录或 docker 未安装Jenkins 控制器 静态 agent 节点远程 agent 主机agent 主机没装 docker或 agent 启动方式导致 PATH 缺失Jenkins 跑在容器里agent 也是容器容器内部容器镜像里根本没装 docker 客户端使用 Kubernetes 动态 agentPod 内容器Pod 模板未挂载 docker 或未安装客户端这张表的核心信息是先定位命令到底在哪台机器、哪个容器里执行再去那台机器上查 docker。很多人一上来就在 Jenkins 控制器上折腾结果命令其实跑在另一台 agent 上方向从一开始就错了。3. 按场景逐个击破四类环境的排查与修复3.1 场景一命令跑在 Jenkins 控制器本机这是最简单也最常见的情况尤其在小团队里Jenkins 就装在一台服务器上任务也直接在这台机器上跑。如果这里报docker: not found排查路径很清晰。第一步确认 docker 到底装没装。在服务器终端执行which docker和docker --version。如果which docker没有任何输出说明要么没装要么装了但不在当前 PATH 里。这时候用find / -name docker -type f 2/dev/null全盘找一下看看是不是装在某个非标准目录。第二步如果找到了 docker 但不在 PATH 里就要判断是永久性缺失还是Jenkins 特有缺失。在终端里echo $PATH如果包含 docker 所在目录那问题就出在 Jenkins 的非交互式 shell 上。解决办法有两个方向一是把 docker 所在目录加到系统级 PATH比如在/etc/profile.d/下放一个脚本二是直接在 Pipeline 里显式指定完整路径。我个人更推荐第二种因为它不依赖系统配置可移植性更好。写法很简单pipeline { agent any stages { stage(Build Image) { steps { sh /usr/local/bin/docker build -t myapp:latest . } } } }用完整路径调用绕开 PATH 查找简单粗暴但极其有效。缺点是路径写死了换台机器可能就不对。所以更稳妥的做法是定义一个环境变量把 docker 路径集中管理pipeline { agent any environment { DOCKER_BIN /usr/local/bin/docker } stages { stage(Build Image) { steps { sh ${DOCKER_BIN} build -t myapp:latest . } } } }这样以后要改路径只改一处就行。3.2 场景二命令跑在远程静态 agent 上当 Jenkins 配置了独立的 agent 节点时docker: not found十有八九是 agent 那台机器的问题。这时候你在控制器上怎么查都没用得登录到 agent 主机上去看。排查的第一步是确认任务确实调度到了哪台 agent。在 Pipeline 日志开头通常能看到类似Running on agent-name in /home/jenkins/workspace/...的信息这里的 agent-name 就是目标节点。确认之后SSH 登录那台机器重复上一节的检查which docker、docker --version、echo $PATH。远程 agent 有个特殊之处它的启动方式会直接影响环境变量。如果 agent 是通过 SSH 方式由控制器拉起的那么它继承的是 SSH 会话的环境如果是通过java -jar agent.jar手动启动的那它继承的是启动时那个 shell 的环境。这两种情况下 PATH 都可能和你的登录 shell 不一样。一个很实用的排查技巧是在 agent 上直接模拟 Jenkins 的执行环境。你可以写一个简单的脚本用env -i清空环境后再执行看看会发生什么env -i /bin/sh -c echo $PATH; which docker如果这条命令报docker: not found而正常登录时能找到那就基本坐实了是环境变量继承的问题。修复方式是在 agent 的启动脚本里显式导出 PATH或者同样在 Pipeline 里用完整路径。注意远程 agent 上如果 docker 需要特定用户权限比如把 jenkins 用户加入 docker 组还要确认执行构建的用户有没有权限。权限不足报的通常是permission denied但有时也会因为找不到 socket 而表现得很奇怪值得一并检查。3.3 场景三Jenkins 和 agent 都跑在容器里容器化部署 Jenkins 现在很流行但这也让docker: not found变得更常见。原因很直接Jenkins 的官方镜像里默认没有 docker 客户端。你在容器里执行docker当然找不到。这种情况有两种主流解法。第一种是挂载宿主机的 dockerDocker-out-of-Docker简称 DOD。做法是把宿主机的/var/run/docker.sock挂载进 Jenkins 容器同时在容器里装上 docker 客户端。这样容器里的 docker 命令实际上是通过 socket 指挥宿主机的 docker 守护进程干活。挂载 socket 的启动命令大概长这样docker run -d \ --name jenkins \ -p 8080:8080 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v jenkins_home:/var/jenkins_home \ jenkins/jenkins:lts但光挂 socket 还不够容器里得有 docker 客户端二进制文件。可以在自定义 Dockerfile 里装FROM jenkins/jenkins:lts USER root RUN apt-get update apt-get install -y docker.io rm -rf /var/lib/apt/lists/* USER jenkins第二种是容器内独立 docker 守护进程Docker-in-Docker简称 DID就是在容器里再跑一个完整的 docker 服务。这种方式隔离性更好但配置更复杂对权限要求也更高一般场景下我更推荐第一种。这里有个容易踩的坑挂载 socket 后容器里的 jenkins 用户和宿主机上拥有 docker socket 的用户UID 可能对不上导致权限被拒。解决办法是让容器里的 jenkins 用户 UID 和宿主机 docker 组对齐或者干脆用 root 跑不推荐但省事。这个细节官方文档不会强调但实际部署时经常卡住人。3.4 场景四Kubernetes 动态 agent 的 Pod 模板用 Kubernetes 插件做动态 agent 时每个构建任务会临时起一个 Pod构建完就销毁。这种模式下docker: not found的根因几乎总是Pod 模板里用的镜像没有 docker 客户端。Kubernetes 环境里构建镜像现在更推荐的做法是用 Kaniko、Buildah 这类不需要 docker 守护进程的工具从根上绕开 docker 依赖。但如果你的流水线确实需要 docker 命令那就得在 Pod 模板的容器定义里选一个带 docker 客户端的镜像或者通过 initContainer 把客户端二进制拷进去。Pod 模板的 YAML 大致结构是这样apiVersion: v1 kind: Pod spec: containers: - name: jnlp image: jenkins/inbound-agent:latest - name: docker image: docker:24-cli command: [cat] tty: true这里的关键是加一个带 docker CLI 的 sidecar 容器然后让构建步骤在这个容器里执行。在 Jenkinsfile 里通过container(docker)指定pipeline { agent { kubernetes { yamlFile pod-template.yaml } } stages { stage(Build) { steps { container(docker) { sh docker build -t myapp:latest . } } } } }这种写法的好处是职责清晰jnlp 容器负责和 Jenkins 通信docker 容器负责执行构建命令。但要注意如果 docker 容器里没有挂载宿主机的 socket它自己是没有守护进程的docker build依然会失败——只不过报的错会从not found变成Cannot connect to the Docker daemon。这两个报错要区分开前者是找不到命令后者是找到了命令但连不上服务。4. 排查这类问题的通用套路与工具4.1 一套可复用的五步排查法踩过几次坑之后我总结出一套固定的排查顺序基本能覆盖绝大多数docker: not found场景。这套方法的核心是先定位、再验证、后修复避免盲目试错。第一步定位执行位置。看构建日志开头的Running on ...确认命令跑在哪台机器或哪个容器里。这一步决定了后面所有排查的方向。第二步打印环境。在报错的那一步之前插入sh echo $PATH和sh whoami把 Jenkins 视角的 PATH 和当前用户打出来。这一步能立刻暴露 PATH 缺失问题。第三步验证命令存在性。插入sh which docker || echo NOT_FOUND确认 docker 到底在不在 PATH 里。如果输出 NOT_FOUND继续第四步如果找到了那问题可能出在权限或守护进程上。第四步全盘搜索。在目标机器上find / -name docker -type f 2/dev/null看看 docker 是不是装在非标准路径。找到后对比 PATH就能确定是不是路径问题。第五步修复并验证。根据前面几步的结论选择用完整路径、修改 PATH、安装 docker 或调整 Pod 模板。修完再跑一次确认报错消失。这套流程看起来啰嗦但比看到报错就重装 docker高效得多。我见过太多人一上来就apt install docker结果命令其实跑在另一个容器里装了也没用。4.2 用 which、type、command -v 定位命令排查命令找不到的问题有几个工具比which更靠谱值得了解一下它们的区别。which是最常用的但它只查 PATH而且不同系统上的行为不完全一致。type是 shell 内置命令能告诉你一个名字到底是可执行文件、别名还是函数信息更全。command -v是 POSIX 标准做法可移植性最好在脚本里推荐用它。type docker # 输出可能是 docker is /usr/bin/docker command -v docker # 输出路径找不到时返回非零退出码 which docker # 传统做法但行为因系统而异在 Pipeline 里做条件判断时用command -v最稳sh if command -v docker /dev/null 21; then echo docker found at $(command -v docker) else echo docker NOT found, please check installation exit 1 fi 这样一旦 docker 缺失流水线会给出明确的提示而不是抛出一句干巴巴的not found对后来接手的人友好很多。4.3 环境变量注入的几种方式对比修复 PATH 问题有好几种注入环境变量的方式各有适用场景我整理成表格方便对比选择。方式作用范围优点缺点Pipeline 内 environment 块单个 Pipeline集中管理清晰每个 Pipeline 都要写Jenkins 全局环境变量配置所有任务一次配置全局生效不够灵活改动静默影响大agent 启动脚本 export该 agent 所有任务对任务透明需要改 agent 配置系统 profile.d 脚本整台机器一劳永逸依赖系统配置容器里不适用完整路径调用单条命令最简单直接路径写死可移植性差我的建议是临时排查用完整路径快速见效长期方案用 Pipeline 的 environment 块兼顾清晰和可移植如果是整个团队共用的 agent再考虑在 agent 启动脚本里统一 export。不要一上来就改系统级配置那样影响面太大出问题也不好回滚。5. 那些文档里不会写的踩坑经验5.1 明明装了 docker 却还是 not found这是最让人抓狂的情况你明明在服务器上docker ps跑得好好的Jenkins 里就是找不到。除了前面说的 PATH 问题还有几个隐蔽原因。一个是shell 类型差异。Jenkins 的sh步骤默认用/bin/sh而你的登录 shell 可能是/bin/bash或/bin/zsh。不同 shell 读取的配置文件不同PATH 自然可能不一样。可以在 Pipeline 里显式指定 shellsh(script: ..., ...)配合 shebang或者用bash -lc command强制走登录 shell 的配置。另一个是docker 是 snap 安装的。某些 Linux 发行版通过 snap 装 docker可执行文件在/snap/bin/docker而这个目录经常不在非交互式 shell 的 PATH 里。这种情况用完整路径/snap/bin/docker调用即可。还有一个是别名或函数。有些环境把 docker 定义成了 shell 别名比如加了--context参数别名只在交互式 shell 里生效Jenkins 的非交互式 shell 读不到于是命令不存在。这种情况要用type docker确认如果是别名就得在 Pipeline 里用真实路径。5.2 权限问题伪装成 not found有时候 docker 命令其实找到了但因为权限问题报错信息看起来像是找不到。比如 jenkins 用户不在 docker 组里执行docker ps会报permission denied while trying to connect to the Docker daemon socket。这个报错和not found不一样但如果你只看日志末尾可能会误判。排查时一定要看完整的报错信息不要只扫一眼最后一行。not found和permission denied是两码事前者是命令不存在后者是命令存在但没权限。修复方式也完全不同前者改 PATH 或装 docker后者把用户加入 docker 组usermod -aG docker jenkins然后重启 Jenkins 服务。提示把用户加入 docker 组后必须重新登录或重启相关服务才能生效因为组成员关系是在登录时确定的。很多人加完组发现还是不行就是因为没重启。5.3 容器里挂载 socket 后的 UID 陷阱前面提到过容器化场景挂载 docker socket 的 UID 问题这里展开说一下因为它真的很坑。宿主机上的/var/run/docker.sock通常属于root:docker权限是srw-rw----。容器里的 jenkins 用户默认 UID 是 1000如果宿主机 docker 组的 GID 不是 1000容器里的 jenkins 用户就不在这个组里访问 socket 会被拒。解决办法是启动容器时用--group-add把宿主机的 docker 组 GID 加进去docker run -d \ --name jenkins \ -p 8080:8080 \ -v /var/run/docker.sock:/var/run/docker.sock \ --group-add $(stat -c %g /var/run/docker.sock) \ jenkins/jenkins:ltsstat -c %g会取出 socket 文件的组 ID动态传给--group-add。这样无论宿主机 docker 组 GID 是多少容器里的用户都能访问 socket。这个技巧在跨机器部署时特别有用因为不同机器的 GID 可能不一样写死容易出错。5.4 别忽略 Jenkins 重启这个动作改完环境变量、加完用户组、装完 docker 之后很多人忘了重启 Jenkins 服务。Jenkins 的进程环境是在启动时确定的你改了系统配置但不重启它还是用旧的环境跑任务于是你会觉得改了没用。正确的顺序是改配置 → 重启 Jenkins 服务systemctl restart jenkins或重启容器→ 重新触发构建。如果是 agent 节点还要重启 agent 进程。这一步看似简单但漏掉的人真的不少。6. 从根上避免让构建环境不再薛定谔6.1 用声明式 Pipeline 固化环境依赖与其每次出问题再排查不如在 Pipeline 里就把环境依赖写清楚。声明式 Pipeline 的environment块和tools块就是干这个的。pipeline { agent any environment { DOCKER_BIN /usr/bin/docker PATH ${env.DOCKER_BIN.substring(0, env.DOCKER_BIN.lastIndexOf(/))}:${env.PATH} } stages { stage(Verify) { steps { sh command -v docker docker --version } } } }在流水线开头加一个 Verify 阶段专门检查关键命令是否存在、版本是否符合要求。这样问题会在构建最开始就暴露而不是跑到一半才挂掉排查成本低很多。6.2 构建镜像的替代方案Kaniko 与 Buildah如果你的目标只是在 CI 里构建容器镜像其实不一定非要 docker。Kaniko 和 Buildah 都是不需要 docker 守护进程的镜像构建工具特别适合容器化 CI 环境。Kaniko 以容器形式运行读取 Dockerfile 直接构建镜像并推送到仓库全程不需要 docker socket也就没有权限和 PATH 的烦恼。Buildah 则更适合在宿主机上以非 root 用户构建镜像。用这些工具docker: not found这个问题从根上就不存在了。当然如果你的流水线里除了构建镜像还要跑docker run、docker compose之类的操作那还是得老老实实把 docker 环境配好。工具选型要看实际需求不要为了绕开一个问题引入一堆新问题。6.3 给团队的环境检查清单最后分享一份我在团队里推行的环境检查清单新机器接入 Jenkins 时照着过一遍能挡掉大部分环境类问题。docker 是否已安装docker --version能否正常输出docker 可执行文件路径是否在 Jenkins 用户的 PATH 里jenkins 用户是否在 docker 组里docker ps能否免 sudo 执行Jenkins 服务重启后环境变量是否生效远程 agent 的启动脚本是否 export 了必要的 PATH容器化场景下 socket 是否正确挂载UID/GID 是否对齐Pipeline 里是否有 Verify 阶段做前置检查这份清单不复杂但坚持执行能省下大量排查时间。环境问题最烦人的地方在于它往往不是代码问题却让代码跑不起来而且每次都要重新查一遍。把它标准化、清单化才是真正的解法。我在实际维护流水线的过程中最大的体会是报错信息只是表象执行链路才是本质。docker: not found这五个字背后可能是 PATH、可能是权限、可能是容器镜像、也可能是调度到了错误的节点。养成先定位执行位置再验证环境的习惯比记住任何一条具体命令都管用。