VS Code dev containers 怎样让容器复用宿主机 SSH agent

如果项目使用 SSH 地址拉取 Git 仓库，最省事的做法不是把私钥复制进 Dev Container，而是让容器复用宿主机正在运行的 SSH agent。VS Code Dev Containers 对这种场景提供了自动转发支持：宿主机的 agent 持有密钥，容器只通过转发套接字发起认证。

官方地址：https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials

完整路径可以记成“宿主机启动 agent并加载密钥 → VS Code 连接 Dev Container → 重建或重新连接 → 在容器内用 Git 检查”。下面的界面都是原创操作说明图，不是 VS Code 截图。

准备宿主机：先确认 SSH agent 真的可用

先在宿主机打开系统终端，确认 agent 已经运行，并且至少加载了一把用于访问代码托管平台的密钥。不要把私钥文件路径写进 devcontainer.json，也不要把私钥复制到镜像层。

# 查看 agent 当前已经加载的公钥指纹；没有输出通常表示尚未加载密钥
ssh-add -l

# 按需加载指定密钥，路径只在宿主机命令中出现
ssh-add "$HOME/.ssh/id_ed25519"

如果 ssh-add -l 提示无法连接 agent，先按当前系统启动它，再重新执行上面的命令。macOS 通常已经有可用 agent；Linux 可以在当前 shell 中执行 eval "$(ssh-agent -s)"；Windows OpenSSH 则检查 ssh-agent 服务是否正在运行。

选择入口：从 VS Code 打开 Dev Container 项目

项目根目录需要有 Dev Container 配置，通常是 .devcontainer/devcontainer.json 或对应的 Docker Compose 配置。打开 VS Code 后，按 F1 调出命令面板，选择 Dev Containers: Reopen in Container；首次使用时也可以选择 Dev Containers: Open Folder in Container...。

连接前确认当前窗口确实是目标项目，而不是只打开了宿主机上的同名目录。窗口左下角的远程连接标识、资源管理器中的工作区路径和扩展运行位置，都是后续排查的重要线索。

重建容器：让连接上下文重新拿到 agent

Dev Containers 会在容器启动或连接阶段处理本地 Git 凭据。修改了宿主机 agent、切换了密钥，或者第一次连接时 agent 尚未运行，建议重新打开命令面板并选择 Dev Containers: Rebuild Container。这一步会重新创建容器环境，但不会把宿主机私钥复制进去。

如果项目需要把配置写进 devcontainer.json，只保留与工具链相关的声明，不手工挂载私钥：

{
  // 使用项目自己的开发容器配置，凭据由宿主机 agent 提供
  "name": "project-dev",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  // 让容器安装 Git 工具，认证仍由 SSH agent 处理
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  }
}

这里的 JSONC 注释说明配置意图；实际是否需要增加 feature，取决于基础镜像。关键点是不要增加 ~/.ssh/id_ed25519 的 bind mount，也不要把密钥内容写入环境变量。

核对结果：在容器内用 Git 远程地址验证

容器连接完成后，在 VS Code 集成终端中检查环境变量和 Git 远程地址。下面的命令只读取认证通道与远程地址，不打印私钥内容：

# 确认容器里存在 agent 套接字路径；这里只检查路径，不读取私钥
printf 'SSH_AUTH_SOCK=%s\n' "$SSH_AUTH_SOCK"

# 确认当前项目使用 SSH 形式的远程地址
git remote -v

# 用目标代码托管平台的主机名测试认证通道；首次连接可能询问主机指纹
ssh -T git@github.com

判断时不要要求命令一定返回“登录成功”的固定文本，不同代码托管平台的提示不同。只要容器中的 SSH 客户端能通过 agent 完成公钥认证，并且 Git 远程地址是 SSH 形式，就达到了本文目标。

排查失败：按三层边界处理

如果你使用的是远程 Docker 主机或 Remote-SSH 窗口，还要先确认 VS Code 的连接层级：本地窗口、SSH 远程主机和容器内工作区并不是同一个 agent 运行环境。先把连接路径拆开，再判断是哪一层没有提供 agent。

常见问题

需要把私钥挂载到容器里吗？

通常不需要。目标是让容器调用宿主机 SSH agent，而不是读取私钥文件。手工挂载私钥会扩大泄露面，也会让镜像和容器生命周期管理更复杂。

重建容器后为什么又认证失败？

先回到宿主机重新执行 ssh-add -l，确认 agent 仍在运行并且密钥仍已加载，然后再次 Rebuild Container。若窗口实际连接的是远程主机，还要检查 agent 是否存在于正确的远程上下文。

这个方法能解决所有 Git 凭据问题吗？

不能。它主要适用于 SSH 密钥由 agent 管理的场景；HTTPS credential helper、GPG 签名和远程 Docker 主机各有独立配置，不应混为同一条排查路径。

总结

VS Code Dev Containers 复用宿主机 SSH agent 的核心是“密钥留在宿主机，容器只使用 agent 通道”。先确认宿主机 agent 和密钥，再从正确的 Dev Containers 入口连接或重建，最后在容器内核对 SSH_AUTH_SOCK、Git 远程地址与 SSH 认证结果，就能定位大多数连接问题。