Jenkins从节点已配置Maven环境变量 执行流水线仍提示mvn命令未找到

你在/etc/profile.d/maven.sh里配置的环境变量，是仅针对交互式登录Shell生效的配置——只有当你通过终端、SSH手动登录系统时，Shell才会加载这个目录下的脚本。
Jenkins从节点的Agent进程，不管是通过systemd服务、JNLP连接、还是后台守护进程方式拉起，都属于非交互式、非登录的后台进程，完全不会触发/etc/profile、/etc/profile.d目录的脚本加载逻辑，所以你配的全局系统环境变量对Jenkins Agent进程没有任何作用，自然在执行构建脚本时找不到mvn命令。
你之前手动登录从节点能正常跑mvn -version，本质是手动登录的过程符合交互式登录Shell的加载规则；Freestyle里手动export环境变量就能成功、注释掉就报错，也正好印证了这个点：构建步骤继承的是Jenkins Agent进程自身的环境，和你手动登录终端的Shell环境完全独立。
你之前用Jenkins内置Maven插件、在节点属性里配置路径没生效，核心原因通常是配置完后没有在构建任务中正确引用预定义的Maven工具，导致构建脚本还是去系统PATH里找mvn，相当于配置没有实际注入到构建环境中。

从规范性和跨环境适配性从高到低，有三个可落地的方案：

方案1：使用Jenkins全局工具配置绑定Maven（最推荐） #

这种方式不依赖系统Shell的环境变量加载规则，适配多节点、不同版本Maven共存的场景，是官方推荐的使用方式：

• 进入Jenkins「Manage Jenkins」->「Global Tool Configuration」，找到Maven配置板块
• 取消「Install automatically」的勾选，设置一个好识别的工具名，比如Maven-3.6.3，在MAVEN_HOME输入框填写从节点上Maven的实际路径/opt/maven；如果是多节点环境，可以为不同操作系统/架构的节点单独配置对应路径
• 配置完成后，在具体构建任务中正确引用这个工具，不要直接硬写mvn命令：
  • Freestyle项目：把原来的「Execute shell」步骤替换为「Invoke top-level Maven targets」，在Maven版本下拉框选择刚才配置的Maven-3.6.3，目标参数填compile即可
  • 流水线项目：在脚本中通过tools语法声明引用，Jenkins会自动把对应Maven的路径注入到构建环境，示例：

    pipeline {
      agent any
      tools {
        maven 'Maven-3.6.3'
      }
      stages {
        stage('代码编译') {
          steps {
            sh 'mvn compile'
          }
        }
      }
    }
    

方案2：把环境变量配置到Jenkins Agent进程的可加载路径下 #

如果不想用Jenkins的工具配置功能，要让Agent进程本身能识别mvn命令，就需要把环境变量改到非交互式Shell会加载的配置文件中：

• 先确认Jenkins从节点Agent的运行用户，通常为jenkins
• 编辑该用户家目录下的~/.bashrc文件，把Maven的环境变量追加到文件末尾：

  export M2_HOME=/opt/maven
  export MAVEN_HOME=/opt/maven
  export PATH=${M2_HOME}/bin:${PATH}
  

  这个文件是所有非交互式bash Shell启动时都会加载的配置，不会像/etc/profile.d那样只对登录场景生效
• 配置完成后必须重启Jenkins从节点的Agent进程，正在运行的旧Agent进程不会自动读取新的环境变量配置，不重启的话问题不会解决

方案3：直接在节点属性中注入环境变量（临时快速生效） #

如果只是临时需要让当前节点的所有任务识别Maven，不需要做全局配置，可以直接修改节点配置：

• 进入从节点的配置页面，找到「Node Properties」板块，勾选「环境变量」
• 添加两个环境变量：
  • 变量名M2_HOME，值/opt/maven
  • 变量名PATH，值为系统默认路径拼接Maven bin目录：/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/maven/bin
• 保存配置后重启节点Agent即可生效，所有跑在该节点的构建任务都会自动带上这些环境变量

常见踩坑提醒：

• 不要指望/etc/profile.d下的配置能给后台守护进程传环境变量，这个路径的加载逻辑和后台进程完全不兼容
• 任何环境变量的修改，都必须重启对应的Jenkins Agent进程才能生效，未重启的旧进程会一直使用启动时的旧环境
• 在节点属性中配置了Maven工具路径但没生效，大概率是构建任务里没有主动引用这个工具，配置仅做了存储没有实际注入到构建步骤的环境中

内容的提问来源于stack exchange，提问作者BTH.S3