VS Code 如何把远程 Dev Container 会话接入 SSH 项目

要把 VS Code 的 Dev Container 接到 SSH 项目，顺序不能反：先用 Remote-SSH: Connect to Host 进入远程主机，打开远程项目目录，再执行 Dev Containers: Reopen in Container。这样源码仍在 SSH 主机上，Docker 和开发工具链运行在远程容器里，本地不需要安装 Docker 客户端。

官方地址：https://code.visualstudio.com/

一、先准备本地扩展和远程条件

本地 VS Code 至少安装 Remote - SSH 与 Dev Containers。如果希望一次安装远程开发组件，也可以安装 Remote Development 扩展包。远程端需要是 Linux 或 macOS SSH 主机，并且 Docker 命令可用；这个任务不是把本地目录上传到容器，而是让远程主机上的项目在容器内运行。

先在本地终端验证最小 SSH 链路：

# 只验证 SSH 身份和主机可达性，不在这里启动容器
ssh devuser@devbox.example
# 连接成功后退出远程 shell，回到 VS Code 操作
exit

如果团队使用 SSH 配置文件，可以把主机别名写成这样，便于 Remote-SSH 复用：

# 远程开发主机的可读别名
Host devbox
    HostName devbox.example
    User devuser
    IdentityFile ~/.ssh/id_ed25519  # 使用本地 SSH 客户端的密钥路径

二、先用 Remote-SSH 进入项目所在主机

按 F1（Windows/Linux 为 Ctrl+Shift+P） 打开命令面板，执行 Remote-SSH: Connect to Host...，选择刚才的 devbox 或输入 devuser@devbox.example。首次连接时，VS Code 可能让你选择远程平台；选定后会在远程系统部署 VS Code Server。

成功信号有两个：窗口左下角状态栏显示 SSH 主机名，且 Remote - SSH 输出通道不再持续报连接错误。此时执行 File > Open Folder...，选择远程主机上的项目目录，例如 /workspaces/sample-service。不要在本地窗口中打开同名项目，否则后续的 Reopen in Container 会作用到错误的环境。

三、从远程项目切换到 Dev Container

保持当前窗口仍处于 SSH 主机上下文，按 F1 执行 Dev Containers: Reopen in Container。如果项目里有 .devcontainer/devcontainer.json，VS Code 会使用它创建或启动容器；若存在多个配置，选择与当前项目工具链对应的一项。

切换过程中窗口会重新加载。完成后打开 Terminal > New Terminal，此终端应进入容器，而不是本地 macOS、Windows 或远程主机的普通 shell。Remote-SSH 和 Dev Containers 是两层连接：前者确定远程主机，后者把工作区再放进容器。

四、用状态检查确认“真的进了容器”

不要只看窗口重新加载就认为完成。按下面清单检查，尤其关注扩展安装位置：

如果只需要编辑远程主机文件，不需要容器，就停留在 Remote-SSH 窗口；只有工具链需要隔离、版本需要固定或项目已有容器配置时，才继续 Reopen in Container。

五、按三层顺序排查常见失败

SSH 层：先确认命令行能连接、用户名和主机别名正确，再看 Remote - SSH 输出。Docker 层：确认 Docker 安装在远程主机并可由当前用户使用；本地没有 Docker 客户端并不妨碍这条模式。容器配置层：最后检查 devcontainer.json 的镜像、构建上下文、挂载路径和扩展列表。

若窗口卡在“Reopening in Container”，不要立刻循环点击。先回到 SSH 窗口确认远程项目仍能打开，再单独确认远程 Docker，最后查看 Dev Containers 的日志。完成工作后选择 File > Close Remote Connection 断开远程连接。

相关问题

本地需要安装 Docker Desktop 吗？

使用“Remote-SSH 主机 + Dev Container”这一模式时，Docker 运行在远程主机，本地只需要 VS Code、Remote-SSH 和 Dev Containers 扩展。

为什么 Reopen in Container 找不到项目配置？

通常是因为当前窗口打开的是本地目录，或远程项目没有可识别的 .devcontainer/devcontainer.json。先确认左下角是 SSH 主机，再从远程目录重新打开项目。

扩展装好了但语言服务仍然报错怎么办？

在 Extensions 视图检查扩展归属。需要访问容器内编译器、解释器或文件系统的扩展，应安装到容器侧，而不是只安装在 Local - Installed。