Jenkins构建执行sqlplus命令提示command not found如何解决

• 先验证本地交互环境的sqlplus可用性：打开日常使用的Mac终端，直接执行which sqlplus。
  • 如果返回具体路径（Apple Silicon芯片Mac通常是/opt/homebrew/bin/sqlplus，Intel芯片Mac通常是/usr/local/bin/sqlplus），说明Homebrew安装的sqlplus本身正常，问题出在Jenkins运行环境的PATH变量未包含Homebrew二进制目录。
  • 如果终端同样返回command not found，说明sqlplus未正确安装，执行brew install instantclient-sqlplus完成安装后再重新验证路径。
• 确认Jenkins运行环境的PATH值：在出问题的Jenkins构建任务里，新增一个临时构建步骤执行echo $PATH，看输出的路径列表里有没有上一步查到的sqlplus所在目录。Mac上Jenkins不管是pkg安装还是brew services启动，默认都不会加载当前登录用户的shell配置（.zshrc/.bash_profile等），默认PATH仅包含/usr/bin:/bin:/usr/sbin:/sbin系统路径，Homebrew安装的命令默认不在这个路径列表里。
• 排除路径误判问题：确认报错不是sql文件路径不存在导致的连带错误，单独在构建步骤里执行ls -l <上一步查到的sqlplus绝对路径>，确认Jenkins执行用户有权限读取、执行该二进制文件。

• 方案1（最稳定，无额外配置依赖）：构建命令中直接使用sqlplus的绝对路径，不依赖PATH变量匹配。把原构建命令替换为如下格式（路径替换成你自己which sqlplus查到的实际路径）：

/opt/homebrew/bin/sqlplus -S ${db_user}/${db_password}@${db_host}:1521/${db_sid} @${WORKSPACE}/${FIX_VERSION}/${sql_file}

• 方案2（全局生效，适合所有Jenkins任务都要用到sqlplus的场景）：修改Jenkins进程的环境变量配置，把Homebrew的bin目录追加到PATH中。如果是brew services启动的Jenkins，修改对应的launchd配置文件，在EnvironmentVariables字段中补充PATH值；如果是官方pkg安装的Jenkins，修改Jenkins对应的launchd plist配置，追加PATH后重启Jenkins服务即可生效。
• 方案3（单任务/单步骤生效，配置成本最低）：在执行sqlplus的构建步骤最开头，临时注入PATH变量，后续命令就能正常找到sqlplus：
  • Apple Silicon芯片Mac添加：

  export PATH="/opt/homebrew/bin:$PATH"
  

  • Intel芯片Mac添加：

  export PATH="/usr/local/bin:$PATH"
  

  加完这行再执行原来的sqlplus命令即可。

注意：Jenkins执行构建时默认使用非交互非登录shell，不会主动加载个人用户目录下的.zshrc/.bash_profile等配置文件，不要靠source个人配置文件的方式加载环境变量，容易触发权限类异常。

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