笙亿网络策划

怎么在 VSCode 中配置 SSH 密钥免密登录远程服务器

约 7 分钟读完 47 阅
文章导读
VSCode 远程开发依赖本地 SSH 客户端配置。只要本地终端能通过密钥免密登录远程服务器，VSCode 即可实现免密连接。核心在于正确生成密钥、部署公钥并设置合适的文件权限。
📋 目录
  1. Ⅰ 前置检查
  2. Ⅱ 生成 SSH 密钥
  3. Ⅲ 部署公钥到远程服务器
  4. Ⅳ 权限配置（关键步骤）
  5. Ⅴ VSCode 插件配置详解
  6. Ⅵ 验证连接是否生效
  7. Ⅶ 常见报错与排查
  8. Ⅷ 参考来源
A A

VSCode 远程开发依赖本地 SSH 客户端配置。只要本地终端能通过密钥免密登录远程服务器，VSCode 即可实现免密连接。核心在于正确生成密钥、部署公钥并设置合适的文件权限。

先说结论：VSCode 本身不管理密钥，而是调用系统 SSH 客户端。本地 SSH 通了，VSCode 就通了。

  • 适合：需要频繁通过 VSCode 远程开发、调试 Linux 服务器（或安装了 OpenSSH 的 Windows 服务器）的场景
  • 先准备：本地安装 SSH 客户端，生成密钥对，将公钥部署到远程服务器
  • 验收：VSCode 左下角显示远程主机名，且连接过程无密码输入框

前置检查

在开始之前，请确认以下环境状态，避免后续步骤报错：

  • 本地环境：Windows 用户建议安装 Git Bash 或使用 Windows 10/11 自带的 OpenSSH 客户端；Mac/Linux 用户默认自带。
  • 远程环境：远程服务器必须安装并运行 SSH 服务（Linux 默认开启，Windows 服务器需手动安装 OpenSSH Server）。
  • 网络连通：本地能 ping 通远程主机，且 22 端口（或自定义 SSH 端口）未被防火墙拦截。

生成 SSH 密钥

在本地终端（PowerShell、CMD 或 Terminal）运行以下命令生成密钥对。建议直接使用默认路径，避免配置复杂化。

ssh-keygen -t ed25519 -C "your_email@example.com"

命令执行后，连续回车使用默认设置即可。私钥默认位于 ~/.ssh/id_ed25519，公钥位于 ~/.ssh/id_ed25519.pub。

怎么在 VSCode 中配置 SSH 密钥免密登录远程服务器

部署公钥到远程服务器

此步骤将本地公钥内容追加到远程服务器的 ~/.ssh/authorized_keys 文件中。根据本地操作系统不同，操作方式有所区别。

1. Mac / Linux 用户

直接使用 ssh-copy-id 工具，最简便。

ssh-copy-id user@remote_host

2. Windows 用户

Windows 原生 PowerShell 或 CMD 不支持 ssh-copy-id 命令，直接运行会报错。可选择以下两种方案之一：

怎么在 VSCode 中配置 SSH 密钥免密登录远程服务器
  • 方案 A（推荐）：使用 Git Bash
    如果安装了 Git，打开 Git Bash 终端，可直接运行上述 ssh-copy-id 命令。
  • 方案 B：手动复制
    1. 查看公钥内容：type $env:USERPROFILE\.ssh\id_ed25519.pub（PowerShell）或 type %USERPROFILE%\.ssh\id_ed25519.pub（CMD）。 2. 复制全部文本内容。 3. 登录远程服务器：ssh user@remote_host。 4. 在远程服务器执行：mkdir -p ~/.ssh && chmod 700 ~/.ssh。 5. 编辑授权文件：vim ~/.ssh/authorized_keys，将复制的内容粘贴进去并保存。

权限配置（关键步骤）

SSH 对密钥文件权限非常敏感，权限过开会导致拒绝连接。不同系统设置方式不同。

1. Mac / Linux 用户

确保私钥权限仅为所有者可读写。

chmod 600 ~/.ssh/id_ed25519
chmod 700 ~/.ssh

2. Windows 用户

怎么在 VSCode 中配置 SSH 密钥免密登录远程服务器

Windows OpenSSH 客户端也会检查权限。如果连接时报错 @WARNING: UNPROTECTED PRIVATE KEY FILE!，需通过 icacls 命令重置权限：

icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant "$($env:USERNAME):R"
icacls $env:USERPROFILE\.ssh\id_ed25519.pub /inheritance:r /grant "$($env:USERNAME):R"

或者右键文件属性 -> 安全，移除除当前用户外的所有权限。

VSCode 插件配置详解

完成上述系统级配置后，再进入 VSCode 进行连接配置。

  1. 安装插件：在扩展商店搜索并安装 Remote - SSH 插件（Microsoft 出品）。
  2. 配置主机：
    • 点击左侧栏“远程资源管理器”图标（显示器加箭头）。
    • 点击“+”号或按下 F1，输入 Remote-SSH: Connect to Host。
    • 输入 user@remote_host 回车。
  3. 编辑配置文件（可选但推荐）：
    • 按下 F1，输入 Remote-SSH: Open Configuration File。
    • 选择本地配置文件（通常是 C:\Users\用户名\.ssh\config 或 ~/.ssh/config）。
    • 添加如下配置以便快速连接：
Host my-server
    HostName 192.168.1.100
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

验证连接是否生效

配置完成后，通过以下方式确认免密登录是否成功：

  • 界面验证：点击 VSCode 左下角绿色图标选择远程主机，连接过程中未弹出密码输入框，且左下角显示远程主机名。
  • 终端验证：在 VSCode 内置终端运行 whoami，输出应为远程服务器用户名。
  • 连接信息：运行 echo $SSH_CONNECTION（Linux 远程）或 $env:SSH_CONNECTION（PowerShell 远程），若有输出则表明 SSH 通道已建立。

常见报错与排查

  • Permission denied (publickey)：90% 是权限问题。检查本地私钥权限（Windows 用 icacls，Mac/Linux 用 chmod），以及远程 ~/.ssh/authorized_keys 权限应为 600。
  • ssh-agent 未启动：如果密钥设置了 passphrase，需确保 ssh-agent 正在运行。Windows 上可运行 Get-Service ssh-agent 检查状态，未运行则 Start-Service ssh-agent。
  • 配置文件冲突：检查 ~/.ssh/config 是否有错误的 Host 配置覆盖了指针，或 HostName 填写错误。
  • 远程服务器拒绝连接：确认远程 /etc/ssh/sshd_config 中 PubkeyAuthentication 设置为 yes。

参考来源

  • Microsoft Learn: Remote Development over SSH
  • OpenSSH: ssh-keygen, ssh-copy-id man pages