Jenkins 工作空间路径不存在速查：自定义目录被清、跨系统路径与节点差异

更新时间：2026-10-24。FAQ 速查页，面向构建刚起步就报 No such file or directory、或流水线 dir() 步骤/ws() 步骤指了一个节点上并不存在的目录的同学。Jenkins 工作空间路径不存在的本质只有一句话：任务期望的目录与 agent 节点上真实存在的目录对不上。但「对不上」有六种典型剧本：自定义工作空间（customWorkspace）被清理任务或人为删掉了、任务把 Unix 风格路径写死了却排到了 Windows 节点（或反过来）、同一任务在不同节点上工作空间根目录不一样、并发构建互相清理对方目录、磁盘满或权限不足导致目录创建失败、以及符号链接指向的目标已失效。顺一遍基本必中。如果是 checkout 阶段因凭据或仓库地址失败而不是路径问题，转 Git 簇速查；如果是构建中途文件莫名消失伴随磁盘告警，先看磁盘空间。

本文要回答的问题

• specified custom workspace ... is not a valid directory 去哪确认目录真实状态？
• 同一个任务为什么在这台节点能跑、换台节点就报路径不存在？
• C:\proj\demo 这类写法在 Linux 节点上会报成什么样？
• 并发构建时工作空间为什么会莫名消失？
• 报路径不存在，但登录节点看目录明明在，是什么坑？

一、报错原文与典型现象

路径类报错集中在构建日志开头的「分配工作空间」阶段（控制器地址以 jenkins.example.com 占位，路径以 /proj/demo 占位）：

# 自定义工作空间不可用
ERROR: Specified custom workspace /proj/demo/work
is not a valid directory: it does not exist and
could not be created

# 构建步骤里引用不存在的路径
java.nio.file.NoSuchFileException: /proj/demo/work/target/app.jar
# 或 shell 步骤
/proj/demo/work@tmp/durable-xxx/script.sh: line 3:
cd: /proj/demo/work: No such file or directory

# Unix 路径写法排到 Windows 节点
ERROR: Failed to create workspace directory \proj\demo\work
# 或 Windows 写法排到 Linux 节点
hudson.AbortException: script returned exit code 2
cd: C:\proj\demo: No such file or directory

读现象先分两层：报错在「分配工作空间」阶段（日志前几行）的是目录本身不存在或建不出来；报错在构建步骤中途（cd、NoSuchFileException）的是目录本来在、构建过程中被删了或路径写法与节点系统不匹配。两层的修法方向不同，先定性。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
custom workspace ... is not a valid directory	自定义目录被清理任务删除	登录节点确认路径是否存在	重建目录；清理策略里排除该目录
中途 No such file or directory、上次构建还在	并发构建互删 / Discard old builds 连坐	看同任务并发构建时间线	并发任务配独立 workspace 后缀
Unix 写法报错出现在 Windows 节点	路径写死与节点系统不匹配	看构建分配到的节点标签	用节点标签约束；路径用相对写法
Windows 写法（盘符）出现在 Linux 节点	同上，方向相反	同上	同上
could not be created、目录父路径存在	磁盘满或 agent 用户对父目录无写权限	节点 df -h 与 ls -ld 父目录	清磁盘；修父目录属主与权限
目录存在但内容空/构建找不到旧产物	符号链接目标失效或挂载点掉了	节点上 readlink 与 mount 核对	重挂存储；符号链接改实体路径

三、排查决策图

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

读这张图抓分水岭：报错出现在日志前几行（分配工作空间阶段）走左支，查的是「目录为什么建不出来」——磁盘、权限、自定义目录被清；报错出现在构建步骤中途走右支，查的是「目录为什么没了或写法不对」——并发互删、跨系统路径。阶段定性错了，后面全是白忙。

四、逐条排查展开

自定义工作空间被清是最常见的剧本。 任务配置了「自定义工作空间」指向 /proj/demo/work，而节点上的磁盘清理任务（定时脚本、Docker 系统清理、甚至同事手工 rm -rf）不认识这是 Jenkins 的目录，随手就删了。下一场构建分配工作空间时发现目录不存在、且因父目录权限等原因建不出来，直接报 is not a valid directory。处置：节点上手工重建目录并给 agent 运行用户属主；长期解法是把该路径加进节点清理策略的白名单，或干脆放弃自定义工作空间、用 Jenkins 默认管理的 workspace 根（它会自己重建）。

并发构建互删工作空间。 Jenkins 对同一任务在同一节点的并发构建会分配 job、job@2、job@3 这样的后缀目录。坑在两类：一是任务里写了「构建前清理工作空间」且引用了不带后缀的公共路径，A 构建清掉了 B 构建正在用的目录；二是 Discard old builds 类插件配置了激进策略，把「旧工作空间」连同并发实例一起清。症状是构建中途莫名 No such file or directory，而上次构建时目录还在。处置：流水线用 ws() 步骤显式分配独立目录（如 ws("workspace/${env.JOB_NAME}-${env.BUILD_NUMBER}")），清理逻辑只清自己的目录。

路径写法与节点系统不匹配是混布集群的固定雷。 任务里写死 C:\proj\demo 的，一旦构建被调度到 Linux 节点，shell 步骤里的 cd C:\proj\demo 直接报路径不存在；反过来写死 /proj/demo 的排到 Windows 节点，会被解释成盘符根目录下的诡异路径，建出来的目录也不是你期望的位置。处置双管齐下：一是给任务加节点标签约束（agent { label 'linux' }），让任务只落到写法匹配的系统上；二是路径一律用相对写法或 ${WORKSPACE} 变量，让 Jenkins 按节点实际 workspace 根展开。

磁盘满与权限不足：目录「建不出来」的两个底层原因。 报错 could not be created 时登录节点看两样：df -h 看磁盘是否写满（workspace 所在分区 100% 时任何目录都建不了），ls -ld /proj/demo 看父目录属主是否包含 agent 运行用户。权限问题的典型事故：有人用 root 在节点上手工建了父目录，agent 用户写不进去。处置：清磁盘或扩容；父目录 chown 给 agent 用户。这类问题修复后建议顺手给节点接上磁盘水位告警，下一节展开。

符号链接与挂载点失效是「目录明明在却报不存在」的谜底。 自定义工作空间指向一个符号链接，链接目标在另一块盘或 NFS 挂载点上；挂载掉了之后，符号链接本身还在、ls 能看到名字，但一进入就报 No such file or directory（悬空链接）。验证：节点上 readlink -f /proj/demo/work 看最终目标是否可达、mount | grep 核对挂载点。处置：重新挂载存储；对稳定性要求高的路径，宁可用实体目录不用符号链接。

容器化 agent 的路径是「用完即焚」。 K8s pod agent 的工作空间在容器临时层里，pod 一回收路径自然不存在——这是设计行为不是故障。如果你的构建依赖跨构建复用工作空间（增量编译缓存），必须挂持久卷（PVC）并在任务里引用挂载路径；把缓存放进临时层的任务，每次构建都会「路径不存在」或从零开始，表象与本篇报错一致。

五、规范做法与预防

• 优先用默认 workspace 管理：不特殊需要就不配自定义工作空间，让 Jenkins 自己建自己清。
• 并发任务目录隔离：流水线统一 ws() 带构建号后缀；清理逻辑禁止跨目录操作。
• 路径一律相对化：脚本里只出现 ${WORKSPACE} 与相对路径，盘符与绝对路径出现在任务配置里即评审不通过。
• 节点标签钉死系统差异：任务声明 label 'linux' 或 label 'windows'，不靠运气调度。
• 清理策略登记白名单：节点上一切定时清理脚本，把 Jenkins 管理的目录列入排除清单。
• 磁盘水位告警：workspace 分区水位超阈值提前告警，别等构建报错才发现。

这一篇在知识体系里的位置

本篇是 Jenkins 排错速查簇的「路径与工作空间」入口篇：路径对了但构建因缺库跑不起来看 Jenkins 缺动态库速查；路径问题发生在 Windows 节点且伴随乱码看 Jenkins 控制台中文乱码速查；构建能分配工作空间但排不到节点看 Jenkins 节点离线速查；构建中途超时挂起的另一条平行线看 Jenkins 构建卡死速查。「先按报错出现阶段定分配失败与中途丢失两层、再逐层收敛」这条主线对一切路径类报错通用。

一句话总结

Jenkins 工作空间路径不存在先按报错出现的位置定层：分配工作空间阶段就报 is not a valid directory，查自定义目录被清理、磁盘满与父目录权限三件；构建步骤中途报 No such file or directory，查并发构建互删、路径写死与节点系统不匹配、符号链接悬空三件。处置的主旋律是让 Jenkins 管自己的 workspace——自定义目录加清理白名单、并发用 ws() 隔离、路径全用 ${WORKSPACE} 相对写法、任务用节点标签钉死操作系统。容器 agent 的工作空间用完即焚是设计行为，要跨构建复用必须挂持久卷。清理白名单与磁盘水位告警入库，路径类报错基本绝迹。