VSCode Remote-Containers devcontainer未转发SSH Agent作为Git凭证如何排查

排查步骤 #

1. 本地侧校验 #

macOS系统存在SSH代理与钥匙串同步异常的已知特性，先在本地终端执行命令：
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
手动将密钥加载到当前运行的SSH代理进程中，执行后再次确认本地ssh-add -l输出正常。
同时确认本地VS Code的Remote-Containers扩展已升级到最新版本，旧版本存在macOS下SSH代理转发失效的已知问题。

2. devcontainer配置校验 #

检查项目根目录下.devcontainer/devcontainer.json文件：

• 确认未显式禁用SSH代理转发，即没有配置"remote.forwardSSHAgent": false，该配置默认值为true
• 确认remoteUser配置和你进入容器后的登录用户一致：如果你设置了非root的普通用户作为remoteUser，需要切换到对应用户后再执行ssh-add -l查看结果，当前你默认以root用户进入容器，若配置了其他remoteUser会无法读取转发的代理套接字

3. 容器侧挂载校验 #

进入容器后执行命令：
mount | grep ssh
查看输出是否存在/tmp/vscode-ssh-auth-*.sock相关的挂载记录：

• 无挂载记录：属于VS Code扩展未触发转发逻辑，排除本地配置问题后可判定为扩展bug
• 有挂载记录：执行ls -al /tmp/vscode-ssh-auth-*.sock查看套接字文件权限，确认当前登录用户有读写权限

4. 旁路验证 #

可以通过手动挂载本地SSH目录的方式排除密钥本身的配置问题：在devcontainer.json的mounts配置项中添加：
"source=${localEnv:HOME}/.ssh,target=/root/.ssh,type=bind,consistency=cached"
重建容器后若SSH操作可正常执行，说明密钥配置无问题，故障出在代理转发链路。

故障判定规则 #

• 本地密钥、devcontainer配置、套接字权限全部校验正常的情况下，转发依然失效，属于Remote-Containers扩展的bug
• 手动挂载密钥后可正常使用，配置调整后转发恢复，属于本地/项目配置错误

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