Jenkins构建时workspace路径@被转码为%402引发Maven构建失败的修复方法

核心根因：Jenkins默认的工作区规则在并发检出源码时，会自动在基础工作区路径后追加@<序号>生成独立源码目录；部分组件在传递路径参数时会触发URL编码逻辑，将@转义为%40，最终导致Java程序读写测试资源文件时匹配不到真实物理路径，抛出文件找不到异常。

方案1：从根源规避带@后缀的路径 #

• @后缀目录是Jenkins为支持并行构建自动生成的目录，只要不触发该规则，就不会出现转码问题
• 操作步骤：
  • 进入目标Jenkins任务的配置页面
  • 找到「高级项目选项」下的「自定义工作区」配置
  • 将Java源码的检出根目录指定为完全自定义的固定路径，比如c:\jenkins\workspace\my_build_src，替代Jenkins默认生成的my_build@2动态路径
• 如需支持任务并发执行，可在自定义路径后拼接构建编号、分支名作为后缀，比如c:\jenkins\workspace\my_build_${BUILD_ID}，全程不使用@字符作为路径分隔标识

方案2：关闭Maven侧的路径URL转码逻辑 #

• 从调试日志看到的@转%40行为，多数是Maven Surefire插件在传递测试工作目录时触发的URL编码规则，可通过插件参数关闭该逻辑
• 项目pom.xml中调整maven-surefire-plugin配置，示例片段：

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
      <workingDirectory>${project.basedir}</workingDirectory>
      <!-- 强制指定文件编码，关闭路径自动转码 -->
      <argLine>-Dfile.encoding=UTF-8 -Dtests.urldecode=false</argLine>
    </configuration>
  </plugin>
  

• 临时快速验证：在Jenkins执行mvn命令时直接追加关闭转码的参数，跑一次构建确认效果，比如执行：
  mvn clean install -Dorg.apache.maven.shared.utils.io.PathEncoder.ENABLED=false

方案3：在Jenkinsfile中显式传递正确路径 #

• 如果Jenkinsfile内部没有显式指定构建根目录，Maven会自动识别当前工作路径，容易拿到被转码后的异常路径，可在流水线步骤中显式指定绝对路径传给Maven，覆盖自动识别的值
• 调整后的Jenkinsfile示例片段：

  // 固定源码检出目录，不使用Jenkins自动生成的@后缀路径
  dir('c:/jenkins/workspace/my_build_src') {
    checkout scm
    // 显式传入项目根目录，避免路径自动转码
    bat 'mvn clean install -Dproject.basedir="c:/jenkins/workspace/my_build_src"'
  }
  

• 优化细节：Windows平台下路径尽量用正斜杠/替代反斜杠\，可进一步降低路径解析异常的概率

修复效果验证 #

• 保留mvn的-X调试参数跑一次构建，查看日志中打印的项目根路径，确认不存在%40转义字符
• 在Maven执行前插入命令打印当前工作路径，比如执行bat 'echo 当前路径：%cd%'，核对打印的路径和Maven读取测试资源文件使用的路径完全一致

内容的提问来源于stack exchange，提问作者user3847894