文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载本文围绕 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/20191803可使用 Windows OpenSSH Client更早的 Windows 可安装 Git for WindowsmacOS 自带Debian/Ubuntu 运行sudo apt-get install openssh-clientRHEL/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要求架构 / 系统版本要求x86_64Debian 8、Ubuntu 16.04、CentOS / RHEL 7ARMv7lAArch32Raspberry Pi OS原 RaspbianStretch/932 位ARMv8lAArch64Ubuntu 18.0464 位WindowsWindows 10 / Server 2016/20191803使用官方 OpenSSH ServermacOSmacOS 10.14Mojave需开启 Remote Login内存方面远程主机至少需要 1 GB RAM推荐 2 GB RAM 与双核 CPU。其他基于glibc的 x86_64、ARMv7l、ARMv8l Linux 发行版只要满足前置条件也可工作社区支持的发行版准备细节参见 Remote Development with Linux。注意虽然支持 ARMv7l / ARMv8l但由于扩展内可能携带 x86 原生代码部分安装在这些设备上的扩展可能无法正常工作。安装与 SSH 主机初始化安装步骤安装OpenSSH 兼容的 SSH 客户端若尚未安装。安装 Visual Studio Code 或 Insiders 版本。安装Remote-SSH 扩展扩展 IDms-vscode-remote.remote-ssh。若计划配合其他远程扩展一起使用可直接安装 Remote Development 扩展包。SSH 主机初始化若尚无 SSH 主机按操作系统搭建Linux 安装openssh-server并启动服务Windows 10/Server1803安装官方 OpenSSH ServermacOS 开启 Remote Logintroubleshooting 中有分系统安装命令。可选——多用户服务器安全加固如果 Linux/macOS SSH 主机将被多个用户同时访问可在 VS Code 用户设置中开启Remote.SSH: Remote Server Listen On Socket。默认情况下服务器监听localhost上的随机 TCP 端口再转发到本地开启后改用锁定到特定用户的 Unix socket 进行转发安全性更高。注意该设置会禁用连接多路复用因此建议配合公钥认证使用详见 troubleshooting 的多用户服务器安全章节。可选——推荐配置基于密钥的认证。虽然支持密码认证但密码与 token 不会被保存troubleshooting 的密钥认证配置章节给出了完整的ssh-keygen、ssh-copy-id、Windowsauthorized_keys写入等操作。连接远程主机首次连接按以下步骤操作在终端 / PowerShell 中验证可连通 SSH 主机按需替换userhostnamessh userhostname # Windows 下使用域 / AAD 账户时 ssh userdomainhostname在 VS Code 中从命令面板F1/CtrlShiftP选择Remote-SSH: Connect to Host...输入与第 1 步相同的userhostname。若 VS Code 无法自动识别目标服务器的类型会提示手动选择平台。选择后该平台会存入 VS Code 设置的remote.SSH.remotePlatform属性中随时可修改。片刻后 VS Code 会连接 SSH 服务器并完成自身初始化进度通过通知呈现详细日志可在Remote - SSH输出通道查看。连接挂起或失败时可参考 troubleshooting 的挂起/失败连接排查遇到 SSH 文件权限错误则参见 修复 SSH 文件权限错误。连接成功后进入空窗口状态栏会显示当前所连主机点击状态栏项可呼出远程命令列表。通过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 文件格式的本地文件。扩展提供了免手改文件的引导流程在命令面板执行Remote-SSH: Add New SSH Host...或点击 Activity Bar 中 SSH Remote Explorer 的Add New图标。输入连接信息既可以直接输入主机名也可以输入完整的ssh命令行。选择要写入的配置文件。若想用列表之外的配置文件可在用户settings.json中设置remote.SSH.configFile属性。例如输入ssh -i ~/.ssh/id_rsa-remote-ssh yournameremotehost.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 和 27017Host 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-remoteremote_server /code/my_project详见 troubleshooting 的终端连接章节。远程调试连接远程主机后调试器用法与本地完全一致在launch.json中选择启动配置并开始调试应用会在远程主机上启动、调试器随即附加。调试配置细节参见 debugging 文档。SSH 主机特定设置VS Code 的本地用户设置会在连接 SSH 主机时复用以保持体验一致。若希望某些设置在本地与各主机之间有所差异可在连接后执行Preferences: Open Remote Settings命令或在设置编辑器中选择Remote标签页进行主机特定设置。这些设置会在连接该主机时覆盖对应用户设置而工作区设置会覆盖远程设置与用户设置。需要注意本地用户设置中涉及绝对路径的配置在远程环境中可能失效建议改用远程设置见 troubleshooting 的路径设置章节。使用本地工具处理远程源码Remote - SSH 扩展本身不直接支持源码同步或使用本地工具处理远程内容但可用两种常见方式适用于多数 Linux 主机使用 SSHFS 挂载远程文件系统SSHFS 基于 SFTP 构建只需 SSH 访问即可无需同步步骤最适合单文件编辑与内容上传/下载但性能明显低于在 VS Code 中直接工作。Linux 下sudo apt-get install sshfsmacOS 下可通过 Homebrew 安装Windows 下可用 SSHFS-Win详见 troubleshooting 的 SSHFS 章节。使用rsync同步源码若需要使用批量读写大量文件的本地应用如本地源码管理工具rsync更合适——它每次运行只传输有变化的文件。从远端拉取示例rsync -rlptzv --progress --delete --exclude.git userhostname:/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 要求本地机器具备到以下地址的出站 HTTPS443 端口连接update.code.visualstudio.comvscode.download.prss.microsoft.com默认情况下 Remote - SSH 会先在远程主机下载失败则回退为在本地下载 Server 再传输到远端可通过remote.SSH.localServerDownload设置改为始终本地下载后传输或绝不在本地下载。离线安装扩展可用Extensions: Install from VSIX...命令若通过扩展面板安装本地机器与 VS Code Server 还需出站 HTTPS 访问marketplace.visualstudio.com与*.gallerycdn.vsassets.ioAzure 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赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐Visual Studio Code Remote - SSH 远程开发实战从 Azure VM 搭建到端口转发与远程调试Visual Studio Code Remote SSH 远程开发实战从 Azure VM 搭建到端口转发与远程调试 VS Code 的 Remote SS文档教程VizTracer 附加日志Extra Log全指南不改一行源码用命令行与 API 记录变量、函数、异常与审计事件VizTracer 附加日志Extra Log全指南不改一行源码用命令行与 API 记录变量、函数、异常与审计事件 导读 VizTracer 的核心能力文档教程Visual Studio Code 中 AI 远程开发Remote Development的实战指南Visual Studio Code 中 AI 远程开发Remote Development的实战指南 在 Visual Studio Code 中文档教程上一篇Cursor Pro破解工具如何彻底解决API限制并实现无限免费使用下一篇Deep SORT实战指南高效多目标追踪的深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考