如何解决Mac下Git每次操作需手动ssh-add的GitHub认证问题

问题本质 #

macOS 自带 SSH 服务默认不会把手动添加的私钥做持久化存储，每次重启系统、新开终端会话时，ssh-agent 暂存的密钥会被清空，因此需要重复执行认证命令。这与 Windows 环境下 Git 内置 ssh-agent 默认关联持久化存储的逻辑有差异。

操作步骤 #

• 配置 SSH 客户端自动加载密钥、关联系统钥匙串
  1. 打开~/.ssh/config文件，不存在则手动新建
  2. 在文件内写入以下配置：

     Host *
       AddKeysToAgent yes
       UseKeychain yes
       IdentityFile ~/.ssh/id_rsa
     

• 单次将密钥永久写入系统钥匙串
  1. 执行命令：ssh-add --apple-use-keychain ~/.ssh/id_rsa
  2. 注：macOS Ventura 之前的旧版本系统，使用参数-K替换--apple-use-keychain执行即可
  3. 按提示输入SSH私钥的设置密码（无密码则直接回车），这一步仅需执行一次
• 配置 shell 自动拉起 ssh-agent
  1. 打开当前使用的 shell 对应配置文件：zsh 默认是~/.zshrc，bash 默认是~/.bash_profile
  2. 在文件末尾追加以下逻辑，避免新开终端时 ssh-agent 未启动导致密钥加载失败：

     if ! pgrep -q ssh-agent; then
       eval "$(ssh-agent -s)"
     fi
     

  3. 执行source ~/.zshrc（替换为实际的 shell 配置文件路径）让配置立即生效

排查项 #

• 校验文件权限符合SSH要求：私钥权限需设置为600，执行chmod 600 ~/.ssh/id_rsa；公钥权限需设置为644，执行chmod 644 ~/.ssh/id_rsa.pub。权限不符时ssh-agent会拒绝自动加载对应密钥
• 若系统终端配置正常但VSCode内置终端仍需重复添加密钥，检查VSCode终端使用的shell路径是否与系统默认shell一致，同时确认VSCode未拦截终端启动时的自动脚本执行
• 公共仓库使用SSH格式地址拉取时需要认证属于正常逻辑，HTTPS格式的公共仓库拉取流程无需SSH参与，不属于配置故障

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