【小白向超详细】使用 VSCode 远程连接 Linux 服务器详细教程

使用 VSCode 远程连接 Linux 服务器详细教程

前提条件

1. 已安装 VSCode。
2. 已在 VSCode 中安装 Remote - SSH 插件。
3. 目标 Linux 服务器 开启了 SSH 服务，并可以通过 SSH 访问。
4. 本地电脑已安装 SSH 客户端（Linux 和 macOS 自带，Windows 用户可以安装 OpenSSH）。

一、安装 Remote - SSH 插件

1. 打开 VSCode。
2. 点击左侧扩展（Extensions）图标。
3. 搜索 Remote - SSH，点击 Install 安装插件。

二、配置 SSH

2.1 检查或创建 SSH 配置文件

SSH 的配置文件路径通常为：

~/.ssh/config

如果文件不存在，可以通过以下命令创建：

touch ~/.ssh/config

配置示例：

编辑配置文件：

nano ~/.ssh/config

添加以下内容：

Host my-linux-server
    HostName 192.168.1.100        # 替换为服务器 IP 地址或域名
    User username                # 替换为你的 SSH 用户名
    Port 22                      # SSH 服务的端口，默认是 22
    IdentityFile ~/.ssh/id_rsa   # 指定私钥路径

保存后，测试连接：

ssh my-linux-server

如果可以正常登录，则配置无误。

三、使用 VSCode 连接服务器

3.1 打开 Remote - SSH

1. 点击 VSCode 左下角绿色按钮（打开远程开发菜单）。
2. 选择 Remote-SSH: Connect to Host…。

3.2 选择服务器

1. 在弹出的输入框中，输入你在 ~/.ssh/config 中配置的 Host，例如 my-linux-server。
2. 按下回车后，VSCode 会尝试通过 SSH 连接到服务器。

3.3 输入密码或配置免密登录

1. 如果没有配置免密登录，会提示输入服务器的 SSH 密码。
2. 如果设置了公钥认证（免密登录），直接连接即可。

四、解决远程连接问题

常见错误及解决方法：

1. config 文件路径错误

错误描述： 如果 VSCode 输出窗口中提示类似：

Error: ENOENT: no such file or directory, mkdir '/path/to/.ssh/config'

解决方法：

• 打开 VSCode 左侧扩展栏，找到已安装的 Remote - SSH 插件。
• 右键点击插件，选择 Extension Settings。
• 在 Config File 项中，输入正确的 SSH 配置文件路径（例如：~/.ssh/config）。
• 保存设置后重新尝试连接。

2. 权限问题

错误描述： 权限不足，无法连接 SSH。
解决方法：

• 确保 ~/.ssh/config 文件权限为 600：

  chmod 600 ~/.ssh/config
  

• 确保私钥文件权限为 600：

  chmod 600 ~/.ssh/id_rsa
  

3. 服务器配置问题

错误描述： 无法连接到服务器，报错类似：

Permission denied (publickey)

解决方法：

• 确保服务器的 SSH 服务已启动：

  sudo systemctl status sshd
  

• 检查服务器是否正确配置了公钥认证。公钥应该存放在服务器的 ~/.ssh/authorized_keys 文件中。

4. 远程 VSCode 服务未正确安装

错误描述： 首次连接时，VSCode 会尝试在服务器上安装所需的远程服务，可能失败。
解决方法：

• 确保服务器可以访问互联网。
• 如果安装失败，可以手动下载 VSCode 的远程服务文件并解压到服务器上的对应目录（提示路径中会包含 ~/.vscode-server）。

五、配置免密登录（可选）

为了避免每次连接时输入密码，可以设置 SSH 公钥认证。

1. 本地生成公钥和私钥：

   ssh-keygen -t rsa -b 4096
   

   按提示选择保存路径（默认路径为 ~/.ssh/id_rsa）。

2. 将公钥上传到服务器：

   ssh-copy-id username@192.168.1.100
   

   如果没有安装 ssh-copy-id，可以手动上传公钥：

   cat ~/.ssh/id_rsa.pub | ssh username@192.168.1.100 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
   

3. 测试免密登录：

   ssh username@192.168.1.100
   

六、常用技巧

6.1 打开远程文件夹

连接成功后，可以选择打开服务器上的特定目录。例如 /home/username/project。

6.2 安装远程扩展

• 当你使用远程连接时，扩展默认会安装到服务器上。
• 如果需要某些扩展在服务器运行，可以直接在 VSCode 扩展市场中点击安装。

总结

通过配置 SSH 和使用 Remote - SSH 插件，VSCode 可以方便地连接远程 Linux 服务器，支持文件编辑、代码调试等操作。如果遇到问题，可以根据报错信息一步步排查。

希望本文对你有所帮助！如果有其他问题，欢迎评论交流。