【VSCode】SSH远程服务器连接全攻略

目录

一、为什么选择 VSCode 连接 SSH 远程服务器

二、准备工作

（一）确保服务器开启 SSH 服务

（二）本地安装 VSCode

（三）安装 Remote - SSH 插件

三、具体连接步骤

（一）添加服务器连接配置

（二）连接到远程服务器

四、实现免密登录

（一）生成 SSH 密钥对

（二）将公钥添加到远程服务器

（三）验证免密登录

五、常见问题及解决方案

（一）连接失败问题

（二）权限问题

（三）其他问题

六、总结

---

一、为什么选择 VSCode 连接 SSH 远程服务器

在软件开发和系统管理的过程中，远程连接服务器进行代码编写和调试是一项常见的任务。以往，我使用过如 Xshell、Putty 等传统的 SSH 连接工具，它们在执行命令和文件传输方面表现尚可，但在进行代码开发时却存在诸多不便。例如，在本地编写代码后，需要手动将文件上传到服务器，这个过程繁琐且容易出错；而且在服务器上运行程序时，调试信息的查看也不够直观和便捷。

直到我发现了 VSCode 连接 SSH 远程服务器的方式，它彻底改变了我的开发体验。VSCode 不仅拥有简洁美观的界面和强大的代码编辑功能，还通过插件扩展实现了与远程服务器的无缝连接，让我可以直接在本地编辑远程服务器上的文件，就像操作本地文件一样方便。这种方式大大提高了开发效率，减少了因文件传输和环境差异带来的问题。

二、准备工作

在使用 VSCode 连接 SSH 远程服务器之前，我们需要做好一些准备工作，以确保连接的顺利进行。

（一）确保服务器开启 SSH 服务

1. 检查 SSH 服务状态：如果你使用的是 Linux 系统，可以通过以下命令检查 SSH 服务是否已经开启。在服务器的终端中输入sudo systemctl status sshd（对于使用 systemd 的系统）或sudo service sshd status ，如果 SSH 服务已经启动，你会看到类似如下的信息：

● sshd.service - OpenSSH server daemon

Loaded: loaded (/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)

Active: active (running) since Tue 2024-12-10 10:15:30 CST; 3 days ago

Docs: man:sshd(8)

man:sshd_config(5)

Main PID: 1234 (sshd)

Tasks: 1 (limit: 4915)

Memory: 3.5M

CGroup: /system.slice/sshd.service

└─1234 sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups

如果服务未启动，信息中会显示Active: inactive (dead) 。

2. 开启 SSH 服务：若 SSH 服务未启动，我们可以使用命令来启动它。同样在服务器终端输入sudo systemctl start sshd（systemd 系统）或sudo service sshd start ，执行命令后，再次检查服务状态，确保 SSH 服务已成功启动。另外，还可以设置 SSH 服务开机自启，以方便后续使用，使用命令sudo systemctl enable sshd即可。

（二）本地安装 VSCode

1. 下载 VSCode：打开你的浏览器，访问 VSCode 官方下载地址：https://code.visualstudio.com/Download 。在该页面，你可以根据自己的操作系统选择对应的安装包，如 Windows 系统可选择 Windows 用户安装程序（x64 或 Arm64） ，Mac 系统选择适用于 macOS 10.15 + 的版本。

1. 安装 VSCode：下载完成后，找到下载的安装包并双击运行。以 Windows 系统为例，安装过程中，首先会弹出许可协议界面，阅读并同意协议后点击 “下一步”；接着选择安装路径，你可以保持默认路径，也可以点击 “浏览” 选择其他位置，然后继续点击 “下一步”；在 “选择开始菜单文件夹” 步骤也可保持默认设置；最后点击 “安装”，等待安装完成即可。安装完成后，你可以在开始菜单中找到 VSCode 并打开它。

（三）安装 Remote - SSH 插件

1. 打开扩展市场：启动 VSCode 后，在界面左侧的活动栏中找到并点击 “扩展” 图标（看起来像一个方块拼图），或者使用快捷键Ctrl+Shift+X（Windows/Linux） 、Command+Shift+X（Mac），即可打开扩展市场。

1. 搜索并安装插件：在扩展市场的搜索框中输入 “Remote - SSH”，搜索结果中会出现 “Remote - SSH” 插件，点击插件卡片上的 “安装” 按钮，VSCode 会自动下载并安装该插件。安装完成后，在插件列表中找到 “Remote - SSH”，你会看到 “已安装” 的标识，此时 Remote - SSH 插件就安装成功了。

三、具体连接步骤

（一）添加服务器连接配置

1. 打开 Remote Explorer：当你成功安装 Remote - SSH 插件后，在 VSCode 界面左侧的活动栏中，你会看到一个新的图标，形状类似一台电脑和一个箭头，这就是 “Remote Explorer” 。点击它，打开远程资源管理器。

1. 添加新 SSH 配置：在 “Remote Explorer” 的 “SSH TARGETS” 部分，点击带有 “+” 号的按钮，这是添加新 SSH 配置的入口。此时会弹出一个输入框，在这里你需要输入 SSH 连接信息。例如，如果你的服务器 IP 地址是 192.168.1.100，用户名是 user，端口使用默认的 22（一般情况下，SSH 默认端口是 22，若服务器管理员更改了端口，需填写实际端口） ，那么你需要输入ssh user@192.168.1.100 -p 22 ，当然，如果你使用域名连接服务器，将 IP 地址替换为域名即可。

1. 选择配置文件保存路径：输入完连接信息并回车后，VSCode 会提示你选择一个配置文件来保存这些信息。一般情况下，默认的配置文件路径是~/.ssh/config（Linux 和 Mac 系统）或C:\Users\你的用户名\.ssh\config（Windows 系统） ，直接选择默认选项即可。选择后，VSCode 会将你输入的服务器连接信息保存到该配置文件中。

（二）连接到远程服务器

1. 选择连接服务器：完成服务器连接配置添加后，在 “Remote Explorer” 的 “SSH TARGETS” 下，你会看到刚刚添加的服务器配置，它显示的格式通常是你输入的用户名 @服务器地址 。右键点击这个服务器配置，你会看到两个连接选项：“Connect to Host in Current Window” 和 “Connect to Host in New Window” ，你可以根据自己的需求选择，前者会在当前 VSCode 窗口连接服务器，后者则会打开一个新的 VSCode 窗口进行连接。

1. 输入密码连接：选择连接选项后，如果服务器没有设置免密登录，VSCode 会弹出一个输入框，要求你输入该服务器用户的密码。输入密码时，屏幕上不会显示你输入的字符，这是正常的安全机制，输入完成后回车即可。如果密码输入正确，VSCode 将开始连接到远程服务器，连接过程中，你可以在 VSCode 左下角看到连接状态提示，如 “Connecting to 192.168.1.100...” ，当连接成功后，你会发现 VSCode 的界面标题栏会显示远程服务器的相关信息，此时你就已经成功连接到远程服务器了。

四、实现免密登录

每次连接远程服务器都需要输入密码，不仅繁琐，还容易出错，尤其是在频繁进行代码调试和文件编辑时，反复输入密码会打断工作思路，降低效率。而实现免密登录后，我们可以快速连接到服务器，专注于开发任务本身。接下来，我将详细介绍如何在 VSCode 连接 SSH 远程服务器的基础上，实现免密登录。

（一）生成 SSH 密钥对

1. 运行密钥生成命令：打开本地计算机的终端（Windows 系统可使用 PowerShell 或 Git Bash ，Linux 和 Mac 系统直接使用终端），运行ssh-keygen -t rsa -b 4096 -C "your_email@example.com"命令 。这里的ssh-keygen是生成 SSH 密钥的工具；-t rsa指定生成的密钥类型为 RSA ，这是一种广泛使用的非对称加密算法；-b 4096表示生成的密钥长度为 4096 位，密钥长度越长，安全性越高；-C "your_email@example.com"用于为密钥添加注释，一般可以填写你的电子邮件地址，方便识别密钥的归属。

1. 选择密钥保存路径和设置密码（可选）：运行命令后，终端会提示你选择密钥的保存路径，默认路径是~/.ssh/id_rsa（Linux 和 Mac 系统）或C:\Users\你的用户名\.ssh\id_rsa（Windows 系统） ，直接回车即可使用默认路径。接着，终端会提示你输入密码（passphrase），这一步是可选的。如果你设置了密码，在使用私钥进行连接时需要输入该密码；如果不设置，直接回车即可。建议在个人开发环境中，为了方便操作，可以不设置密码，但在涉及重要数据和安全要求较高的场景下，设置密码可以增强私钥的安全性。完成上述步骤后，在指定的保存路径下会生成两个文件：id_rsa（私钥文件）和id_rsa.pub（公钥文件） ，私钥文件需要妥善保管，不能泄露给他人。

（二）将公钥添加到远程服务器

1. 使用 scp 命令复制公钥文件：如果你对命令行操作比较熟悉，可以使用scp（secure copy）命令将本地生成的公钥文件id_rsa.pub复制到远程服务器。在本地终端运行命令scp ~/.ssh/id_rsa.pub user@192.168.1.100:~/.ssh/ ，这里的user是远程服务器的用户名，192.168.1.100是服务器的 IP 地址 ，运行命令后，系统会提示你输入远程服务器用户的密码，输入正确后，公钥文件就会被复制到远程服务器的~/.ssh/目录下。然后登录到远程服务器，使用命令cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys将公钥内容追加到authorized_keys文件中 ，该文件用于存储授权的公钥，只有公钥在这个文件中的用户才能免密登录。

1. 使用 ssh 命令直接添加公钥内容：除了使用scp命令，我们还可以通过ssh命令直接将公钥内容添加到远程服务器。首先，在本地终端运行cat ~/.ssh/id_rsa.pub命令，查看公钥文件的内容，并复制全部内容；然后登录到远程服务器，运行echo "粘贴刚刚复制的公钥内容" >> ~/.ssh/authorized_keys命令 ，将公钥内容追加到authorized_keys文件中。同样，如果远程服务器的~/.ssh/目录下没有authorized_keys文件，需要先使用touch ~/.ssh/authorized_keys命令创建该文件 ，并确保~/.ssh/目录和authorized_keys文件的权限设置正确，一般~/.ssh/目录的权限为 700 ，authorized_keys文件的权限为 600 ，可以使用chmod 700 ~/.ssh/和chmod 600 ~/.ssh/authorized_keys命令进行设置。

（三）验证免密登录

完成公钥添加和权限设置后，我们就可以验证免密登录是否设置成功了。在 VSCode 的 “Remote Explorer” 中，选择之前添加的远程服务器配置，右键点击并选择 “Connect to Host in Current Window” 或 “Connect to Host in New Window” 进行连接 。如果设置成功，你会发现这次连接不再需要输入密码，直接就可以连接到远程服务器，VSCode 左下角会显示连接成功的状态信息，此时你已经成功实现了 VSCode 连接 SSH 远程服务器的免密登录。

五、常见问题及解决方案

（一）连接失败问题

在使用 VSCode 连接 SSH 远程服务器时，连接失败是一个常见的问题，可能由多种原因导致。

1. 网络问题：网络连接不稳定或服务器无法访问是导致连接失败的常见原因之一。你可以在本地计算机的终端中使用ping命令来测试与服务器的网络连通性，例如ping 192.168.1.100 ，如果出现大量丢包或无法 ping 通的情况，说明网络存在问题。此时，你需要检查本地网络设置，如路由器配置、网络连接是否正常等；如果是服务器端网络问题，联系服务器管理员进行排查。

1. 防火墙限制：服务器或本地计算机的防火墙可能会阻止 SSH 连接。在服务器端，如果使用的是 Linux 系统，你可以检查防火墙规则，例如对于使用iptables的系统，使用命令sudo iptables -L -n查看防火墙规则 ，确保 SSH 端口（默认为 22）是开放的。如果未开放，可以使用命令sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT开放端口 ；对于使用firewalld的系统，使用命令sudo firewall-cmd --zone=public --add-port=22/tcp --permanent开放端口 ，然后sudo firewall-cmd --reload使配置生效 。在本地计算机，如果使用 Windows 系统，打开 “控制面板” - “系统和安全” - “Windows 防火墙” ，在左侧选择 “允许应用或功能通过 Windows 防火墙” ，找到 “OpenSSH SSH Client” 并确保其在 “专用” 和 “公用” 网络下都被允许。

1. 服务器配置错误：服务器的 SSH 配置文件可能存在错误。例如，配置文件中限制了特定的 IP 地址或用户才能连接，或者配置文件中的端口号设置错误等。你可以登录到服务器，检查 SSH 配置文件，通常位于/etc/ssh/sshd_config ，确保配置正确。例如，如果修改了 SSH 端口，需要在配置文件中正确设置Port参数，并且重启 SSH 服务使配置生效，使用命令sudo systemctl restart sshd 。

（二）权限问题

当遇到 “Permission denied (publickey)” 等权限相关错误时，可能是以下原因导致的。

1. 公钥未正确添加：虽然我们在前面介绍了将公钥添加到远程服务器的步骤，但可能存在操作失误。你可以登录到远程服务器，检查~/.ssh/authorized_keys文件 ，确保其中包含你本地生成的公钥内容。如果公钥缺失，可以重新按照前面介绍的方法将公钥添加到该文件中。另外，要确保~/.ssh/目录和authorized_keys文件的权限设置正确，~/.ssh/目录的权限应为 700 ，authorized_keys文件的权限应为 600 ，可以使用chmod 700 ~/.ssh/和chmod 600 ~/.ssh/authorized_keys命令进行设置 。

1. 私钥权限问题：在本地计算机上，私钥文件id_rsa的权限也需要正确设置。如果权限设置不当，例如权限过于宽松，可能会导致私钥被其他用户读取，从而引发权限错误。在 Linux 和 Mac 系统中，使用chmod 600 ~/.ssh/id_rsa命令设置私钥权限 ；在 Windows 系统中，如果你使用的是 Git Bash 或其他类 Unix 环境，可以使用类似的命令；如果是在 PowerShell 中，可以通过文件属性设置来确保只有当前用户有读取权限。

（三）其他问题

在连接过程中，还可能遇到 “无法安装 VS Code 服务器” 等问题。

1. 网络问题导致下载失败：VSCode 在连接远程服务器时，需要在服务器上安装 VS Code 服务器。如果网络不稳定或存在限制，可能会导致下载安装失败。你可以检查服务器的网络连接，确保可以正常访问互联网。另外，如果你在服务器上设置了代理服务器，需要在 VSCode 中正确配置代理，在 VSCode 的设置中搜索 “HTTP_PROXY” 和 “HTTPS_PROXY” ，填写正确的代理地址和端口。

1. 依赖缺失：服务器上可能缺少 VS Code 服务器安装所需的依赖项。如果是 Linux 服务器，不同的发行版依赖项可能略有不同。例如，在 Ubuntu 系统中，确保安装了openssh-server 、curl等依赖 ，可以使用命令sudo apt-get install openssh-server curl进行安装 ；在 CentOS 系统中，使用命令sudo yum install openssh-server curl进行安装 。如果缺少其他依赖项，根据错误提示进行相应的安装。

1. 服务器磁盘空间不足：如果服务器的磁盘空间不足，也可能导致 VS Code 服务器无法安装。你可以在服务器上使用df -h命令查看磁盘空间使用情况 ，如果某个分区的使用率过高，清理不必要的文件或扩展磁盘空间。例如，可以删除一些不再使用的日志文件、临时文件等，或者使用工具如du -sh /*查看各个目录的大小 ，找出占用大量磁盘空间的文件或目录并进行处理。

六、总结

通过以上步骤，我们详细介绍了如何使用 VSCode 连接 SSH 远程服务器，从准备工作、具体连接步骤，到实现免密登录以及常见问题的解决方法。VSCode 连接 SSH 远程服务器的方式，为我们的开发工作带来了极大的便利，它让我们能够在熟悉的本地开发环境中，高效地操作远程服务器上的代码，避免了传统开发方式中文件传输和环境差异带来的困扰。

如果你还在为远程开发的繁琐流程而烦恼，不妨按照本文的步骤尝试一下 VSCode 连接 SSH 远程服务器，相信它会成为你开发过程中的得力助手，让你的开发效率更上一层楼。在使用过程中，如果你遇到了任何问题，欢迎在评论区留言交流，我会尽力为大家解答 。