Mac自托管Azure DevOps代理BuildKit报错：buildx组件缺失或损坏

• 用户上下文差异：Azure DevOps自托管代理默认以系统账户（或非你手动操作的用户）运行，而你手动在终端执行命令时用的是当前登录用户。Docker Desktop的buildx组件通常安装在用户个人目录（~/.docker/cli-plugins/），代理服务的用户无法访问该目录下的组件，导致报错。
• 环境变量不匹配：终端手动执行时的PATH、DOCKER_CONFIG等环境变量包含了buildx的路径，但代理运行的环境未继承这些变量，使得docker build找不到buildx组件。
• 权限与配置继承问题：Mac上Docker Desktop是用户级应用，系统账户运行的代理无法加载当前用户的Docker配置（包括buildx的安装信息），而手动执行时配置是完整加载的。

• 切换代理运行用户：将Azure DevOps代理服务改为使用你手动执行命令的那个用户启动。这样代理会继承该用户的Docker配置和环境变量，自然能找到buildx组件。
• 全局安装buildx组件：将docker-buildx插件复制到系统级的Docker CLI插件目录，确保所有用户均可访问：

  sudo cp ~/.docker/cli-plugins/docker-buildx /usr/local/lib/docker/cli-plugins/
  sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx
  

• 在流水线中显式配置环境变量：如果无法修改代理运行用户，可在YAML流水线中手动指定包含buildx的路径和相关环境变量：

  steps:
    - script: |
        docker build -t your-image-name .
      env:
        DOCKER_BUILDKIT: 1
        PATH: "$HOME/.docker/cli-plugins:$PATH"
        DOCKER_CONFIG: "$HOME/.docker"
  

• 验证Docker Desktop配置：确认Docker Desktop已启用BuildKit（进入设置>Features in development>勾选Use BuildKit），之后重启Azure DevOps代理服务，确保配置生效。

内容的提问来源于stack exchange，提问作者Matthew van Boheemen