macOS 10.15.5下GitLab Runner（VirtualBox执行器）vboxmanage路径问题求助

我之前也踩过这个坑！这个报错的核心原因很明确：GitLab Runner在macOS上是以系统服务（LaunchDaemon）的身份运行的，它使用的是系统级的PATH环境变量，和你平时在终端里用的用户PATH完全不是一回事——哪怕你在终端里敲vboxmanage能正常运行，Runner服务就是找不到它。

下面是亲测有效的修复步骤：

1. 先定位vboxmanage的完整路径 #

打开终端，输入这条命令找到它的位置：

which vboxmanage

常见的输出有两种：要么是/usr/local/bin/vboxmanage（这是软链接），要么是VirtualBox安装目录下的原文件/Applications/VirtualBox.app/Contents/MacOS/VBoxManage（注意大小写，实际二进制是VBoxManage）。

2. 修改GitLab Runner的配置文件 #

Runner的默认配置文件在/etc/gitlab-runner/config.toml，用编辑器打开它（需要sudo权限）：

sudo vim /etc/gitlab-runner/config.toml

找到你那个VirtualBox执行器的配置块，添加environment字段，把vboxmanage所在的目录加到PATH里：

[[runners]]
  name = "你的Runner名称"
  url = "你的GitLab项目URL"
  token = "你的Runner令牌"
  executor = "virtualbox"
  # 重点加这行，把路径换成你查到的目录
  environment = ["PATH=/usr/local/bin:/usr/bin:/bin:/Applications/VirtualBox.app/Contents/MacOS"]
  # 保留其他原有配置...

如果你的vboxmanage在/usr/local/bin，那只需要确保这个目录在PATH里就行；如果是在VirtualBox的安装目录，就把那个目录加进去。

3. 重启GitLab Runner服务 #

保存配置后，重启Runner让新配置生效：

sudo gitlab-runner restart

额外排查小技巧 #

要是还是不行，你可以检查一下Runner的运行环境：

1. 先看Runner是以哪个用户运行的：

ps aux | grep gitlab-runner

一般是root用户。
2. 切换到这个用户，看看它的PATH是什么：

sudo su - root
echo $PATH

确认vboxmanage所在的目录在这个PATH里。如果不在，除了上面修改Runner配置的方法，也可以手动给vboxmanage加个软链接到系统默认的PATH目录里：

sudo ln -s /Applications/VirtualBox.app/Contents/MacOS/VBoxManage /usr/local/bin/vboxmanage

这样系统级的环境就能找到它了。

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