macOS Big Sur系统下SSH代理无法成功转发至Docker容器问题求解

云上老周

2026-10-4

问题核心原因

你遇到的报错核心是macOS版Docker Desktop的运行机制和Linux不同：Docker for Mac会在自身内置的Linux虚拟机中提供SSH代理socket路径/run/host-services/ssh-auth.sock，该路径是虚拟机内部路径，不需要你macOS本机存在/run目录，你的误区就是误以为这个路径需要对应macOS本机的文件系统。

前置检查

先在macOS本地终端执行ssh-add -l，确认你本地的SSH代理已经加载了对应的Git密钥，如果返回无密钥，执行ssh-add --apple-use-keychain ~/.ssh/你的私钥文件（默认是~/.ssh/id_rsa）加载密钥到系统代理。
确认Docker Desktop版本≥2.4.0，该版本开始默认支持SSH代理socket转发功能。

解决方案

方案1：仅macOS环境使用

直接修改docker-compose配置，替换挂载路径即可：

services:
  the_service:
    ...
    environment:
      SSH_AUTH_SOCK: /ssh-agent
    volumes:
      # 此处路径为Docker内置虚拟机的路径，无需macOS本机存在对应目录
      - /run/host-services/ssh-auth.sock:/ssh-agent
      - ./fe:/app
    ...

方案2：兼容Linux + macOS多环境开发

可以通过环境变量适配不同系统，不需要修改docker-compose主配置：

在项目根目录创建.env文件，加入如下内容：
- macOS用户写入：SSH_AUTH_SOCK_PATH=/run/host-services/ssh-auth.sock
- Linux用户写入：SSH_AUTH_SOCK_PATH=${SSH_AUTH_SOCK}

修改docker-compose配置，统一使用变量：

services:
  the_service:
    ...
    environment:
      SSH_AUTH_SOCK: /ssh-agent
    volumes:
      - ${SSH_AUTH_SOCK_PATH}:/ssh-agent
      - ./fe:/app
    ...