1. 为什么你需要告别密码，拥抱SSH密钥？

每次打开VS Code，准备连接远程服务器写几行代码，或者部署个小项目，是不是都得停下来，输入那一长串密码？输错一两次还得重来，要是服务器设置了复杂的密码策略，那体验就更“酸爽”了。更别提那些需要频繁在本地和服务器之间切换的场景，比如调试、文件同步、查看日志，每次操作都弹出一个密码输入框，简直是在打断你的“心流”。

我刚开始用VS Code连服务器的时候，也是这么过来的。直到有一次，我在一个紧急的线上问题排查中，因为手抖输错了两次密码，差点耽误了时间。从那以后，我就下定决心，必须搞定这个“免密登录”。今天要跟你聊的，就是这个能极大提升你开发幸福感的技巧——用SSH密钥实现VS Code一键连接远程服务器。

简单来说，SSH密钥就像是一把专属于你的、高度安全的“物理钥匙”。你本地电脑上存着私钥（这把钥匙的“齿纹”部分，绝对不能给别人），远程服务器上放着你对应的公钥（相当于“锁芯”）。当你尝试连接时，服务器会用你给的“锁芯”去验证你手里的“钥匙齿纹”，匹配上了，门就自动开了，根本不需要你每次都在门口喊密码。这种方式不仅快，而且比单纯的密码要安全得多，因为它几乎无法被暴力破解。

所以，无论你是前端、后端还是运维开发，只要你需要经常和远程Linux服务器打交道，花10分钟配置好这个，以后的日子就舒坦多了。接下来，我就手把手带你走一遍这个流程，保证你一次成功。

2. 准备工作：确认你的“装备”齐全

在开始打造你的“万能钥匙”之前，咱们得先看看手头的工具是不是都齐活了。这个过程很简单，但检查一下能避免后面走弯路。

2.1 检查本地SSH客户端

SSH密钥的生成和管理，依赖于一个叫做SSH客户端的东西。好消息是，对于Windows 10（版本1803及以后）和Windows 11用户，以及所有macOS和Linux用户，系统基本都自带了OpenSSH客户端。怎么确认呢？

打开你的终端。在Windows上，可以是命令提示符（CMD） 或者更推荐的 PowerShell；在macOS或Linux上，就是终端（Terminal）。输入下面这个命令：

ssh -V

注意，这里的 V 是大写的。敲下回车，如果你看到类似 OpenSSH_8.9p1, OpenSSL 3.0.7... 这样的版本信息输出，那就恭喜你，你的“装备”是齐全的。如果系统提示“ssh不是内部或外部命令”，那说明你的Windows可能比较老，没有安装OpenSSH客户端。

对于旧版本Windows用户，别担心，有两个非常简单的解决方案：

1. 安装Git for Windows：这是我最推荐开发者的方式。去Git官网下载并安装Git，在安装过程中，记得勾选“Use OpenSSH”相关选项。安装完成后，Git Bash终端就会自带完整可用的SSH套件。
2. 启用Windows可选功能：在Windows设置里搜索“可选功能”，点击“添加功能”，找到“OpenSSH 客户端”并安装。

我自己在好几台电脑上都是用的Git Bash，因为它不仅提供了SSH，还给了你一个非常接近Linux的环境，用起来很顺手。

2.2 确保VS Code和远程扩展就位

主角VS Code当然要准备好。确保你安装的是最新稳定版。然后，我们需要一个至关重要的扩展：Remote - SSH。这个扩展是微软官方出的，它就是VS Code能够无缝连接并操作远程服务器的“桥梁”。

打开VS Code，点击侧边栏的扩展图标（或者按 Ctrl+Shift+X），在搜索框里输入“Remote SSH”。你应该能很快找到它，作者是Microsoft。点击安装即可。安装成功后，你会在VS Code左下角看到一个绿色的远程连接图标，像这样：><。有了它，我们后续的所有操作才有了舞台。

2.3 获得远程服务器的访问凭证

这是前提中的前提：你必须已经知道如何用密码登录到你的远程服务器。也就是说，你需要知道：

• 服务器的IP地址或域名（比如 192.168.1.100 或 example.com）
• 你的用户名（比如 ubuntu, root, deploy 等）
• 对应的登录密码

为什么强调这个？因为我们的配置过程，需要你先用密码登录一次服务器，去完成公钥的部署。如果你现在连用密码都登录不上去，那后面的步骤就无从谈起了。你可以先用系统自带的终端（或PuTTY等工具）测试一下：ssh username@server_address，输入密码，看看能否成功登录并看到服务器的命令行提示符。

3. 核心实战：生成并部署你的专属密钥对

好了，工具齐备，舞台搭好，现在我们来制作并安装那把“钥匙”。这是整个流程最核心的一步，跟着我做，一步一步来。

3.1 在本地生成SSH密钥对

首先，我们打开终端（Windows用户我强烈建议用安装Git时带来的 Git Bash）。我们将使用 ssh-keygen 这个命令来生成密钥。

这里有个小技巧：默认情况下，ssh-keygen 会生成一对RSA算法、2048位长度的密钥，保存在你用户目录下的 .ssh 文件夹里（比如 C:\Users\你的用户名\.ssh\ 或 /home/你的用户名/.ssh/）。这对大多数场景已经足够安全。但如果你想用更新、更推荐的算法，比如Ed25519，可以用这个命令：

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

这里的 -t ed25519 指定了算法，它比RSA更安全、更快，生成的密钥也更短。-C 后面跟的注释，通常用你的邮箱，这有助于你以后识别这个密钥是用于哪里的。如果你就想要RSA，或者不确定，直接用 ssh-keygen 然后一路回车也行。

执行命令后，你会看到几次交互提示：

1. Enter file in which to save the key (/home/you/.ssh/id_ed25519): 这里问你把密钥文件存到哪。直接按回车，使用它建议的默认路径和文件名。这样最省事，所有工具都会默认去这里找。
2. Enter passphrase (empty for no passphrase): 这是设置一个密钥口令。我强烈建议你设置一个！虽然我们的目标是“免密登录服务器”，但这个口令是保护你本地私钥的。即使别人拷贝了你的私钥文件，没有这个口令也无法使用。输入一个你能记住但别人猜不到的短语，然后回车。它会让你再输入一次确认。
3. 然后，终端会显示密钥的“指纹”和随机的艺术图案，生成过程就完成了。

现在，去你的用户目录下的 .ssh 文件夹看看（这个文件夹默认是隐藏的，你可能需要在文件管理器里设置显示隐藏文件）。你应该能看到两个新文件：

• id_ed25519 (或者 id_rsa)：这是你的私钥。这个文件相当于你的银行密码，绝对不能泄露给任何人，也不要通过网络发送。
• id_ed25519.pub (或者 id_rsa.pub)：这是你的公钥。这个文件的内容就是我们要放到服务器上的“锁芯”，可以随便分发。

3.2 将公钥“安装”到远程服务器

现在，我们要把公钥（锁芯）装到服务器的门（你的账户）上。传统做法是手动复制粘贴，但这里我分享一个更优雅、更不容易出错的方法——使用 ssh-copy-id 命令。

如果你的本地环境是macOS、Linux，或者安装了完整Git Bash的Windows，通常都自带这个命令。它的用法极其简单：

ssh-copy-id -i ~/.ssh/id_ed25519.pub username@server_address

把 username 和 server_address 换成你的。执行这个命令，它会自动用密码登录到你的服务器，找到（或创建）~/.ssh/authorized_keys 文件，并把你的公钥内容追加进去，同时设置好正确的文件权限。你只需要在它提示时输入一次服务器的登录密码。

但是，很多Windows环境可能没有 ssh-copy-id 命令。 别慌，我们手动操作一次，你也能彻底明白原理：

1. 首先，用密码登录服务器：在终端里输入 ssh username@server_address，输入密码，成功进入服务器的命令行。

2. 确保服务器上有.ssh目录：登录后，执行 mkdir -p ~/.ssh。-p 参数的意思是，如果目录已经存在，不会报错；如果不存在，就创建它。

3. 编辑或创建authorized_keys文件：我们需要把本地公钥的内容，添加到服务器 ~/.ssh/authorized_keys 文件的末尾。你可以用 vim 或 nano 编辑器打开这个文件添加。但我教你一个更直接的方法，在你本地电脑的终端（注意，不是登录服务器后的终端）里执行：

   # 在本地终端执行，将公钥内容通过一次SSH连接，追加到远程服务器的文件末尾
   cat ~/.ssh/id_ed25519.pub | ssh username@server_address "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
   

   这个命令组合有点长，我解释一下：cat 命令先读取你本地的公钥文件内容，然后通过管道 | 传给 ssh 命令。ssh 命令登录服务器后，执行引号内的操作：先确保 .ssh 目录存在，然后用 cat >> 将接收到的公钥内容追加到 authorized_keys 文件里。执行时，你同样需要输入一次服务器密码。

4. 关键一步：设置正确的文件权限：SSH协议对权限非常敏感，权限不对会导致免密登录失败。回到服务器的命令行，执行以下两条命令：

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/authorized_keys
   

   chmod 700 表示只有你自己能读、写、执行这个目录。chmod 600 表示只有你自己能读写这个授权文件。这一步很多人会忽略，然后卡住，务必检查。

完成以上步骤后，你可以在服务器的终端里输入 logout 或按 Ctrl+D 退出登录。

3.3 验证免密登录是否成功

这是激动人心的测试时刻。在你本地电脑的终端里，再次输入连接命令：

ssh username@server_address

如果一切配置正确，这次你将不会看到密码提示符，而是直接登录到了服务器！如果失败了，通常会提示“Permission denied (publickey)”。别着急，这是调试的好机会。你可以给ssh命令加上 -v 参数（verbose，详细模式）来查看连接过程的细节：

ssh -v username@server_address

仔细看输出，它通常会告诉你它尝试了哪些密钥，有没有找到你的私钥，以及服务器端拒绝了什么。最常见的错误就是上面提到的服务器端 .ssh 目录或 authorized_keys 文件的权限不对，或者公钥内容粘贴时多了空格、换行。

4. 在VS Code中配置并使用SSH连接

本地终端测试成功，说明你的SSH密钥对工作正常。现在，我们把这份便利集成到VS Code里，实现真正的“一键连接”。

4.1 配置VS Code的Remote-SSH

打开VS Code，按下 F1 键（或 Ctrl+Shift+P）打开命令面板，输入 “Remote-SSH: Connect to Host...”，然后选择它。

你会看到一个下拉框，选择 “Configure SSH Hosts...”，接着会让你选择一个SSH配置文件。通常就选用户目录下的那个（比如 C:\Users\你\.ssh\config）。这个文件就是用来管理你所有SSH连接配置的。

用VS Code打开这个config文件后，你可以按照以下格式添加你的服务器配置：

Host myserver # 给你服务器起个别名，好记就行
    HostName 192.168.1.100 # 服务器的真实IP或域名
    User ubuntu # 登录用户名
    IdentityFile ~/.ssh/id_ed25519 # 你的私钥文件路径
    # Port 22 # 如果SSH端口不是默认的22，取消注释并修改

保存这个文件。这里 IdentityFile 指定了私钥路径，VS Code连接时就会自动使用它，不再询问密码。

4.2 连接并享受无缝体验

保存配置后，再次按 F1 打开命令面板，输入 “Remote-SSH: Connect to Host...”，这次你会看到列表里出现了你刚才配置的 myserver。选择它。

VS Code会打开一个新的窗口，状态栏显示“正在连接”，稍等片刻，就会连接成功。第一次连接时，它可能会在右下角提示你选择服务器的平台（Linux、macOS、Windows），选择正确的即可。然后VS Code会在服务器上自动安装一个轻量级的“服务端”来支持远程开发。

连接成功后，你就可以像操作本地文件一样，通过左侧的资源管理器访问服务器上的文件目录，在集成的终端里运行服务器命令，安装扩展也会自动区分为“本地”和“远程”，一切都无比顺畅。下次再想连接，只需要点击VS Code左下角的绿色远程状态栏，选择你的主机，或者直接从命令面板连接，全程无需再输入密码。

5. 进阶技巧与疑难排坑指南

配置一次，终身受益。但为了让你用得更踏实，我再分享几个进阶技巧和常见问题的解决办法。

5.1 管理多个服务器与密钥

你很可能不止一台服务器，或者在同一台服务器上有不同用途的账户。这时候，SSH的config文件就派上大用场了。你可以这样组织：

Host work-server
    HostName company-server.com
    User alice
    IdentityFile ~/.ssh/id_ed25519_work

Host personal-project
    HostName 123.45.67.89
    User deploy
    IdentityFile ~/.ssh/id_ed25519_personal
    Port 2222 # 非标准端口

Host github.com # 甚至可以为Git服务配置
    IdentityFile ~/.ssh/id_ed25519_github

这样，当你 ssh work-server 或者用VS Code连接 work-server 时，它会自动使用对应的用户名和私钥。为不同用途生成不同的密钥对，也是一种安全最佳实践。

5.2 常见问题与解决方案

• 问题：连接时依然提示输入密码。

  • 检查1：config文件路径。确保VS Code的SSH配置指向了正确的config文件，并且里面的 IdentityFile 路径绝对正确。Windows路径注意是 C:\Users\... 格式还是 /c/Users/... 格式（在Git Bash中）。
  • 检查2：服务器权限。再次通过SSH登录服务器，用 ls -la ~/.ssh/ 确认 authorized_keys 文件权限是600，目录权限是700。
  • 检查3：公钥内容。用 cat ~/.ssh/authorized_keys 查看服务器上的公钥，确保它和你本地 id_xxx.pub 文件的内容完全一致，没有多出空行或空格。

• 问题：VS Code连接超时或失败。

  • 网络问题：确认IP、端口、防火墙设置。尝试先用系统终端SSH连接，排除VS Code扩展本身的问题。
  • 扩展问题：尝试禁用再重新启用Remote-SSH扩展，或者更新到最新版。
  • 配置文件语法：确保config文件没有语法错误，比如缩进最好是空格，每行参数前有四个空格或一个Tab。

• 问题：私钥口令（Passphrase）每次都要输入？

  • 这是为了安全。但如果你觉得麻烦，可以使用 ssh-agent 这个密钥管理器。在终端执行 eval $(ssh-agent) 启动代理，然后用 ssh-add ~/.ssh/id_ed25519 添加你的私钥（输入一次口令），之后在当前会话中就不再需要输入了。VS Code的Remote-SSH扩展通常能很好地与系统自带的ssh-agent集成。

5.3 安全注意事项

方便不能以牺牲安全为代价。最后唠叨几句安全：

1. 私钥即密码：你的 id_xxx 文件（没有.pub后缀）就是私钥。保护好它，不要上传到网盘、Git仓库，也不要通过邮件发送。
2. 使用强口令：给私钥设置一个强口令（Passphrase），是最后一道防线。
3. 定期回顾：定期查看服务器上 authorized_keys 文件，移除不再信任或不再使用的公钥。
4. 考虑硬件密钥：对于极高安全要求的场景，可以考虑使用YubiKey这类硬件安全密钥，它将私钥存储在物理设备中，更加安全。

配置的过程可能会遇到一两个小坑，但一旦搞定，你会发现之前每次输密码的等待和烦躁都是完全不必要的。我团队里的同事在被我安利配置了这个之后，都感慨“早就该这么做了”。希望这篇详细的指南能帮你顺利通关，享受那种在本地和远程之间无缝切换、行云流水般的开发体验。如果过程中遇到任何卡点，不妨回头看看权限和文件内容这两个最关键的环节，大多数问题都能迎刃而解。