企业官网建设流程全解析

• 文档
• 教程

本文围绕 Visual Studio Code 官方文档仓库（vscode-docs）中的 Remote Development using SSH 展开，系统讲解 Remote - SSH 扩展的完整使用链路：从"远程服务器 + 本地客户端"的架构模型、系统要求与主机初始化，到首次连接、SSH 配置文件管理、扩展安装位置、端口转发、远程调试，再到已知限制与高频问题的排查方案。读完本文，你将具备在任何运行 SSH 服务的远程机器、虚拟机或容器上搭建本地级开发体验（IntelliSense、代码导航、调试）的完整实战能力。

Remote - SSH 是什么：架构与工作原理

Remote - SSH扩展允许你打开任意一台运行 SSH 服务器的远程机器、虚拟机或容器上的文件夹，并享用 Visual Studio Code 的完整功能集。连接成功后，你可以与远程文件系统上任意位置的文件和文件夹进行交互。

这一能力的关键在于代码无需存放在本地：扩展直接在远程机器上执行命令并运行其他扩展。首次连接时，扩展会把VS Code Server安装到远程操作系统上，该服务器独立于远程系统上任何已有的 VS Code 安装，由本地 VS Code 客户端负责安装、启动、更新与停止（生命周期完全由客户端托管，见 FAQ 中对 Server 的介绍）。

从架构看，本地 UI/客户端通过经过认证的安全 SSH 隧道与远程 VS Code Server 通信（区别于 Dev Containers 的docker exec通道和 WSL 的本地随机端口通道）。这套机制让 VS Code 能提供本地质量的开发体验——包括完整的 IntelliSense（补全）、代码导航与调试——而无论你的代码托管在何处。

系统要求：本地客户端与远程 SSH 主机

本地（Local）侧要求

本地机器必须安装受支持的 OpenSSH 兼容 SSH 客户端。Windows 10 1803+ / Server 2016/2019（1803+）可使用 Windows OpenSSH Client；更早的 Windows 可安装 Git for Windows；macOS 自带；Debian/Ubuntu 运行sudo apt-get install openssh-client；RHEL/Fedora/CentOS 运行sudo yum install openssh-clients。VS Code 会在 PATH 中查找ssh命令，Windows 下若找不到，会尝试默认 Git for Windows 安装路径；也可以通过remote.SSH.path属性在settings.json中显式指定 SSH 客户端位置（详见 troubleshooting）。

远程 SSH 主机（Remote SSH host）要求

内存方面：远程主机至少需要 1 GB RAM，推荐 2 GB RAM 与双核 CPU。其他基于glibc的 x86_64、ARMv7l、ARMv8l Linux 发行版，只要满足前置条件也可工作；社区支持的发行版准备细节参见 Remote Development with Linux。

注意：虽然支持 ARMv7l / ARMv8l，但由于扩展内可能携带 x86 原生代码，部分安装在这些设备上的扩展可能无法正常工作。

安装与 SSH 主机初始化

安装步骤

1. 安装OpenSSH 兼容的 SSH 客户端（若尚未安装）。
2. 安装 Visual Studio Code 或 Insiders 版本。
3. 安装Remote-SSH 扩展（扩展 ID：ms-vscode-remote.remote-ssh）。若计划配合其他远程扩展一起使用，可直接安装 Remote Development 扩展包。

SSH 主机初始化

1. 若尚无 SSH 主机，按操作系统搭建：Linux 安装openssh-server并启动服务；Windows 10/Server（1803+）安装官方 OpenSSH Server；macOS 开启 Remote Login（troubleshooting 中有分系统安装命令）。
2. 可选——多用户服务器安全加固：如果 Linux/macOS SSH 主机将被多个用户同时访问，可在 VS Code 用户设置中开启Remote.SSH: Remote Server Listen On Socket。默认情况下服务器监听localhost上的随机 TCP 端口再转发到本地；开启后改用锁定到特定用户的 Unix socket 进行转发，安全性更高。注意该设置会禁用连接多路复用，因此建议配合公钥认证使用（详见 troubleshooting 的多用户服务器安全章节）。
3. 可选——推荐配置基于密钥的认证。虽然支持密码认证，但密码与 token 不会被保存（troubleshooting 的密钥认证配置章节给出了完整的ssh-keygen、ssh-copy-id、Windowsauthorized_keys写入等操作）。

连接远程主机

首次连接按以下步骤操作：

1. 在终端 / PowerShell 中验证可连通 SSH 主机（按需替换user@hostname）：

ssh user@hostname # Windows 下使用域 / AAD 账户时 ssh user@domain@hostname

2. 在 VS Code 中，从命令面板（F1/Ctrl+Shift+P）选择Remote-SSH: Connect to Host...，输入与第 1 步相同的user@hostname。

3. 若 VS Code 无法自动识别目标服务器的类型，会提示手动选择平台。选择后该平台会存入 VS Code 设置的remote.SSH.remotePlatform属性中，随时可修改。
4. 片刻后 VS Code 会连接 SSH 服务器并完成自身初始化，进度通过通知呈现，详细日志可在Remote - SSH输出通道查看。连接挂起或失败时，可参考 troubleshooting 的挂起/失败连接排查；遇到 SSH 文件权限错误则参见 修复 SSH 文件权限错误。
5. 连接成功后进入空窗口，状态栏会显示当前所连主机；点击状态栏项可呼出远程命令列表。
6. 通过File > Open...或File > Open Workspace...像本地一样打开远程机器上的任意文件夹或工作区。

提示：连接过程实际上会建立两条 SSH 连接——第一条安装/启动（或寻找已运行实例）VS Code Server，第二条创建端口隧道。某些按连接动态分配节点的集群系统可能把第二条连接路由到不同机器导致失败，可用 OpenSSH 的ControlMaster选项将两条连接复用为同一条（详见 troubleshooting）。

在远程 SSH 主机的容器中打开文件夹

若使用 Linux 或 macOS SSH 主机，可将 Remote - SSH 与 Dev Containers 扩展配合：在远程主机上安装 Docker（本地无需 Docker 客户端），通过 SSH 连接主机并打开文件夹后，执行Dev Containers: Reopen in Container命令即可。其余流程与 Dev Containers 快速开始一致；其他远程 Docker 主机方案参见 Develop on a remote Docker host。

断开远程连接

编辑完成后，选择File > Close Remote Connection断开连接（该命令默认无快捷键），直接退出 VS Code 也可关闭远程连接。

记忆主机与 SSH 配置文件

若有一组常用主机，或需要带附加选项连接主机，可将它们加入遵循 SSH config 文件格式的本地文件。扩展提供了免手改文件的引导流程：

1. 在命令面板执行Remote-SSH: Add New SSH Host...，或点击 Activity Bar 中 SSH Remote Explorer 的Add New图标。
2. 输入连接信息：既可以直接输入主机名，也可以输入完整的ssh命令行。
3. 选择要写入的配置文件。若想用列表之外的配置文件，可在用户settings.json中设置"remote.SSH.configFile"属性。

例如，输入ssh -i ~/.ssh/id_rsa-remote-ssh yourname@remotehost.yourcompany.com会生成如下条目：

Host remotehost.yourcompany.com User yourname HostName another-host-fqdn-or-ip-goes-here IdentityFile ~/.ssh/id_rsa-remote-ssh

此后该主机会出现在Remote-SSH: Connect to Host...的列表中，以及 Remote Explorer 的SSH Targets部分。Remote Explorer 既支持在远程主机上打开新的空窗口，也支持直接打开此前打开过的文件夹。

管理扩展：本地还是远程运行

VS Code 扩展在两个位置之一运行：本地（UI/客户端侧）或远程（SSH 主机上）。影响 UI 的扩展（如主题、代码片段）安装在本地，而绝大多数扩展位于 SSH 主机上——这保证了流畅体验，也允许你在不同机器上无缝衔接同一套扩展环境。

从扩展视图安装扩展时会自动安装到正确位置；已安装扩展可通过分类分组判断位置：远程 SSH 主机对应一个远程分类，另有Local - Installed分类。本地分类中实际需要在远程运行的扩展会以变暗禁用状态呈现，点击Install即可安装到远程主机。

也可以在扩展视图的Local - Installed标题栏右侧云按钮中，选择Install Local Extensions in SSH: {Hostname}，将部分或全部本地扩展批量安装到 SSH 主机。

"始终安装"扩展

希望在任何 SSH 主机上都自动安装的扩展，可用remote.SSH.defaultExtensions属性指定扩展 ID，例如：

"remote.SSH.defaultExtensions": [ "eamodio.gitlens", "mutantdino.resourcemonitor" ]

高级：强制扩展在本地 / 远程运行

扩展通常只针对本地或远程之一设计和测试。若扩展支持，可在settings.json中强制其运行位置。例如下面设置强制 Container Tools 在本地运行、Remote - SSH: Editing Configuration Files 在远程运行：

"remote.extensionKind": { "ms-azuretools.vscode-containers": [ "ui" ], "ms-vscode-remote.remote-ssh-edit": [ "workspace" ] }

"ui"表示强制在本地 UI/客户端侧运行，"workspace"表示在远程运行。除非扩展文档另有说明，这通常仅用于测试——可能破坏扩展。扩展作者应参阅 Supporting Remote Development。

端口转发与 SSH 隧道

开发中有时需要访问远程机器上未公开暴露的端口，可通过 SSH 隧道把远程端口"转发"到本地。VS Code 提供两种方式。

临时转发端口

连接主机后，若需在本次会话期间临时转发新端口：在命令面板选择Forward a Port，或点击 Ports 视图（底部面板，也可用Ports: Focus on Ports View命令调出）中的Add Port按钮，输入要转发的端口并为其命名。完成后会有通知告知应使用的本地 localhost 端口——例如远程 HTTP 服务器监听 3000，若本地 3000 已被占用，通知会提示映射到 4123，此时用http://localhost:4123即可访问该远程服务。同一信息也可在 Remote Explorer 的Forwarded Ports部分随时查看。

如需 VS Code 记住转发过的端口，可在设置编辑器中勾选Remote: Restore Forwarded Ports，或在settings.json中设置"remote.restoreForwardedPorts": true。

修改隧道的本地端口

若希望隧道本地端口与远程服务器端口不同，可在Forwarded Ports面板中右键目标隧道，选择Change Local Address Port。

永久转发端口

希望始终转发的端口，可在"记忆主机"所用的 SSH 配置文件中使用LocalForward指令。例如转发 3000 和 27017：

Host remote-linux-machine User myuser HostName remote-linux-machine.mydomain LocalForward 127.0.0.1:3000 127.0.0.1:3000 LocalForward 127.0.0.1:27017 127.0.0.1:27017

在远程主机上打开终端与调试

远程终端与 code CLI

连接后，VS Code 中打开的任意终端窗口（Terminal > New Terminal）都会自动运行在远程主机而非本地。在同一终端中还可使用code命令行执行多种操作（如打开远程主机上的文件或文件夹），输入code --help可查看全部命令行选项。连接配置完成后，也可直接从本地终端传入远程 URI 打开远程窗口，例如code --remote ssh-remote+remote_server /code/my_project（详见 troubleshooting 的终端连接章节）。

远程调试

连接远程主机后，调试器用法与本地完全一致：在launch.json中选择启动配置并开始调试，应用会在远程主机上启动、调试器随即附加。调试配置细节参见 debugging 文档。

SSH 主机特定设置

VS Code 的本地用户设置会在连接 SSH 主机时复用，以保持体验一致。若希望某些设置在本地与各主机之间有所差异，可在连接后执行Preferences: Open Remote Settings命令，或在设置编辑器中选择Remote标签页进行主机特定设置。这些设置会在连接该主机时覆盖对应用户设置；而工作区设置会覆盖远程设置与用户设置。需要注意：本地用户设置中涉及绝对路径的配置在远程环境中可能失效，建议改用远程设置（见 troubleshooting 的路径设置章节）。

使用本地工具处理远程源码

Remote - SSH 扩展本身不直接支持源码同步或使用本地工具处理远程内容，但可用两种常见方式（适用于多数 Linux 主机）：

1. 使用 SSHFS 挂载远程文件系统：SSHFS 基于 SFTP 构建，只需 SSH 访问即可，无需同步步骤，最适合单文件编辑与内容上传/下载；但性能明显低于在 VS Code 中直接工作。Linux 下sudo apt-get install sshfs，macOS 下可通过 Homebrew 安装，Windows 下可用 SSHFS-Win（详见 troubleshooting 的 SSHFS 章节）。
2. 使用rsync同步源码：若需要使用批量读写大量文件的本地应用（如本地源码管理工具），rsync更合适——它每次运行只传输有变化的文件。从远端拉取示例：

rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" .

反向参数即可推送到远端；Windows 下建议先在项目中加入.gitattributes统一行尾（详见 troubleshooting 的 rsync 章节）。

已知限制

Remote - SSH 限制

• 推荐使用基于密钥的认证；为其他认证方式输入的密码与 token 不会被保存。
• 不支持 Alpine Linux及非 glibc 的 Linux SSH 主机。
• 较旧（社区支持）的 Linux 发行版需变通安装所需前置条件（见 Remote Development with Linux）。
• Windows 下不支持 PuTTY。
• 若使用带 passphrase 的 SSH 密钥克隆 Git 仓库，远程运行时 VS Code 的拉取与同步功能可能挂起——改用无 passphrase 的密钥、以 HTTPS 克隆，或在命令行执行git push均可绕过。

扩展相关限制

多数扩展无需修改即可在远程 SSH 主机上工作，但部分特性可能需要调整；报告问题时可引用 troubleshooting 的扩展提示。此外，安装于 ARMv7l / ARMv8l 设备的部分扩展可能因仅含 x86_64 原生模块或运行时而无法工作，此类扩展需为 ARM 目标编译/附带二进制才能支持这些平台。

常见问题

SSH 客户端 / 服务器如何安装？

分系统安装命令见 troubleshooting 的安装章节与 安装受支持的 SSH 服务器。

可以用密码等额外认证方式登录吗？

可以，扩展会自动提示输入 token 或密码；但密码不会被保存，因此基于密钥的认证通常更方便。

如何修复 "bad permissions" 权限错误？

见 修复 SSH 文件权限错误：Linux/macOS 下需保证~/.ssh为700、~/.ssh/config与~/.ssh/id_ed25519.pub为600，服务器端~/.ssh为700、~/.ssh/authorized_keys为600。

远程 SSH 主机需要安装哪些 Linux 包 / 库？

大多数 Linux 发行版无需额外依赖。SSH 场景下主机需具备 Bash（/bin/bash）、tar，以及curl或wget之一——某些精简发行版可能缺失这些工具。Remote Development 还要求内核 >= 3.10、glibc >= 2.17、libstdc++ >= 3.4.18；当前仅支持基于 glibc 的发行版，因此 Alpine Linux 不受支持。需要说明的是，较新版本 VS Code Server 的基线更高（linux.md 列出内核 >= 4.18、glibc >= 2.28、libstdc++ >= 3.4.25，对应 Debian 10、RHEL 8、Ubuntu 20.04 等发行版），部署前建议以 Remote Development with Linux 为准核对版本。

VS Code Server 在远程机器 / VM 上的连通性要求？

安装 VS Code Server 要求本地机器具备到以下地址的出站 HTTPS（443 端口）连接：

• update.code.visualstudio.com
• vscode.download.prss.microsoft.com

默认情况下 Remote - SSH 会先在远程主机下载，失败则回退为在本地下载 Server 再传输到远端；可通过remote.SSH.localServerDownload设置改为"始终本地下载后传输"或"绝不在本地下载"。离线安装扩展可用Extensions: Install from VSIX...命令；若通过扩展面板安装，本地机器与 VS Code Server 还需出站 HTTPS 访问marketplace.visualstudio.com与*.gallerycdn.vsassets.io（Azure CDN）。部分扩展（如 C#）还会从其他域名下载二级依赖，请查阅扩展文档。除此之外，Server 与 VS Code 客户端之间的一切通信均经由经过认证的安全 SSH 隧道完成。

只有 SFTP/FTP 文件系统访问权限（无 shell）时能用 VS Code 吗？

Remote Development 并非为此场景设计。此类需求通常可通过组合 SFTP 类扩展与远程调试功能（Node.js、Python 等）实现。

作为扩展作者需要注意什么？

VS Code 扩展 API 已抽象了本地/远程差异，多数扩展无需修改即可工作；但扩展可能使用任意 node 模块或运行时，仍存在需调整的情形。建议实际测试扩展，详见 Supporting Remote Development。

延伸阅读

• 动手练习：完整的 Azure VM + Node.js Express 远程开发演练见 SSH 入门教程
• 分场景排查清单：Remote Development Tips and Tricks
• 发行版兼容性矩阵与前置条件：Remote Development with Linux
• 高频问题汇总：Remote Development FAQ
• 扩展作者指南：Supporting Remote Development

• 文档
• 教程