VS Code SSH：配置一次用三年

▌ 技术引导
VS Code SSH配置一次用三年，这绝不是夸张。我亲测过，在 Linux、Mac、Windows 环境下，只要一次正确配置，后续跨平台、跨服务器的远程开发几乎不需再动配置。关键在于如何把 SSH 配置文件、密钥管理、自动补全、终端集成等细节，默认值都设定好。别小看这些细节，它们能帮你省去每天重复输入密码、手动切换环境、调整路径的麻烦。我见过太多人为了 SSH 配置折腾半天，结果发现只要设置好 ssh_config 和 ~/.ssh/config，配合上 Git、Docker、Nginx，整个开发流程就顺畅了。直接把 SSH 免密登录、端口转发、代理设置、密钥分发这些埋进配置里，你就能在不同的机器上直接开发，不用再重新配置。

▌ 技术参考
SSH 配置核心是 ~/.ssh/config 文件，里面可以定义主机别名、端口、用户、密钥路径、代理跳转等。规则是：在 config 文件中添加 Host block，通过 Host 的 name 来快速连接。比如 Host myserver，然后指定 Hostname 为你的服务器 IP，User 是登录用户名，IdentityFile 是你私钥路径。重要的是，这个配置文件一旦写好，所有终端工具、IDE、命令行都能识别，包括 VS Code。如果服务器配置了 SSH 配置文件，别忘了在本地配置文件里添加 ProxyJump，这样就能实现跳板机连接，省去中间人手动输入的步骤。

SSH 密钥生成和管理不能糊弄，必须用 ssh-keygen 命令，指定 -m PEM 参数生成 PKCS#8 格式的密钥，兼容 OpenSSH 和 Git。密钥分发必须用 ssh-copy-id 工具，直接把公钥拷贝到服务器 ~/.ssh/authorized_keys 文件中。别用 cat 命令手动复制，那样容易出错。如果服务器不支持免密登录，检查一下 authorized_keys 文件权限是否是 600，所属用户是否是 ssh 用户。如果服务器是 Ubuntu，记得给 ~/.ssh 目录加上 700 权限，否则登录会被拒绝。密钥路径必须写绝对路径，否则配置无法识别。

VS Code 的 SSH 配置需要在 settings.json 里添加 remote.SSH.configFile 路径，指向全局的 ~/.ssh/config 文件。如果服务器端没有配置文件，就直接把 SSH 配置写进 VS Code 的配置里，用 remote.SSH.customServerEntries。这样每次打开远程开发，就能自动加载配置，不需要手动输入命令。另外，VS Code 的 Remote - SSH 和 Remote - Container 都能共存，但需要确保 SSH 配置和容器启动命令不冲突。比如，如果容器用 22 端口，而 SSH 配置用了 22，那就会出问题，必须修改其中一个端口。

远程开发时，终端的集成是关键。VS Code 的 Terminal 工具会自动识别 SSH 配置，所以每次打开终端，它都会自动连接到对应的服务器。如果终端不识别，检查一下 ssh-agent 是否在运行，以及环境变量是否正确。在 Linux 上，使用 eval $(ssh-agent) 来启动代理，然后 ssh-add 加载私钥。Windows 用户可以用 Pageant 工具，把私钥导入进去，这样 Terminal 就能自动识别。如果环境变量还没加，可以在 ~/.bashrc 或 ~/.zshrc 里添加 export SSH_ASKPASS=/usr/bin/ssh-askpass，避免弹窗问题。

有些服务器默认禁用密码登录，只能用密钥。这时候必须确保配置文件里有 PermitRootLogin 选项，或者用指定用户登录，比如 User root。如果服务器是阿里云的，记得开启 SSH 端口转发，否则无法连接。还有，SSH 配置文件里如果有多个 Host，必须确保名称不重复，否则会覆盖。我之前就因为 Host 名称写重复了，导致连接一直失败，最后才发现是配置文件里 Host block 写错了。配置文件里的每个 Host block 都是独立的，可以设置不同的 User、IdentityFile、Port，甚至不同的 ServerAliveInterval。

远程开发效率提升的关键是路径映射。VS Code 的 Remote - SSH 会自动将本地文件夹映射到远程服务器，但默认情况下，它会把整个本地目录同步过去，占用大量磁盘空间。这时候需要设置 remote.SSH.pathMapping，把不需要同步的目录排除出去。比如，设置 exclude 为 "/node_modules", "/dist"，这样本地的 node_modules 和 dist 目录就不会被同步，节省存储和传输时间。如果服务器是 Docker 容器，可以考虑用 volume 挂载，这样 VS Code 会直接访问容器内的文件，不需要同步整个目录。

代理跳转配置需要前置条件，服务器必须能访问目标服务器，且目标服务器允许 ssh 连接。比如，配置 ProxyJump=jumpserver，这样就能通过 jumpserver 连接到目标服务器。但要注意，ProxyJump 是 OpenSSH 的特性，不是所有服务器都支持。如果服务器是 Ubuntu 16.04，需要手动更新 ssh 配置，添加 AllowAgentForwarding yes 和 GatewayPorts yes。如果服务器是 Windows 10 且使用 OpenSSH 服务器，同样要确认这些配置是否开启。否则代理跳转会失败，导致远程连接卡在中间。

权限问题是 SSH 配置中最容易出乱子的地方。服务器的 ~/.ssh/authorized_keys 文件必须是 600 权限，且属于当前用户。否则会提示 Permission denied。如果用户权限不对，可以在服务器上运行 chmod 600 ~/.ssh/authorized_keys，然后 chown 用户名:用户名 ~/.ssh/authorized_keys。还有，服务器的 ~/.ssh 目录权限必须是 700，否则也会报错。我之前就因为这个错误，花了好几个小时排查，最后发现是目录权限的问题。

远程开发的性能优化可以通过 SSH 配置来实现。比如，设置 ServerAliveInterval=30，让 SSH 客户端每 30 秒发送一次心跳包，避免连接超时。再比如，设置 TCPKeepAlive=yes，保持 TCP 连接活跃。如果服务器是 Windows，可以使用 sshd_config 配置 SessionAliveInterval 和 ClientAliveInterval，避免长时间空闲断开。另外，设置 Compression=yes 可以减少传输量，提升远程编辑的响应速度。这些参数虽然小，但对开发体验影响很大，特别是当网络不稳定时。

VS Code 的 Remote - SSH 配置推荐使用全局配置文件，而不是项目配置文件。全局配置文件在 ~/.ssh/config，默认不被 VS Code 读取，必须手动指定。这在团队开发中特别有用，所有人都用同一个配置，避免环境差异。如果需要自定义配置，可以创建一个 config.json 文件，放在项目根目录，然后在 settings.json 里设置 remote.SSH.configFile。这样配置更灵活，也更便于管理。不过需要注意，全局配置和项目配置不能同时存在，否则会冲突。

在配置过程中，如果遇到连接失败，可以先用 ssh -v 命令查看详细日志，确定是配置问题还是网络问题。比如，如果提示 "Connection refused"，说明服务器端 SSH 服务没有运行，或者防火墙阻止了端口。如果提示 "Host key verification failed"，说明本地没有存储服务器的公钥，或者公钥不匹配。这时候可以手动运行 ssh -T git@github.com 来添加 GitHub 公钥。如果是私钥路径错误，检查一下 IdentityFile 的路径是否正确，是否被权限限制。

远程开发时，路径映射需要特别注意。VS Code 默认会把本地项目映射到远程服务器的相同路径，但有时候需要调整。比如，如果服务器是 ~/project/myapp，而本地是 /home/user/myapp，可以通过远程配置中的 rootPath 来指定映射关系。或者用 remote.SSH.pathMapping 设置规则，把某些路径映射到不同的目录。比如，设置 mapping: {"source": "/home/user/myapp", "target": "~/project/myapp"}，这样 VS Code 会把本地的路径映射到远程的路径上。这个配置对跨平台、跨服务器开发至关重要。

如果服务器使用了非标准端口，比如 2222，那么在 ~/.ssh/config 文件里必须指定 Port=2222。否则会连接到默认的 22 端口，导致失败。同样，如果服务器使用了不同的用户，比如 User=deploy，那么配置文件里必须写清楚。我之前就因为忘记指定 User，导致每次连接都提示 "Permission denied"。还要注意，如果服务器配置了 PasswordAuthentication=no，必须确保是密钥登录，否则会连接失败。

VS Code 远程开发的另一个特性是自动补全。如果远程环境是 Ubuntu，可以安装 bash-completion 包，让命令行有自动补全功能。同时，安装 oh-my-zsh 和 powerlevel10k，提升终端体验。如果远程环境是 Windows，可以考虑使用 WSL2，这样命令行和 VS Code 的终端都能兼容。不过，WSL2 的 SSH 配置需要额外处理，比如在 Windows 的 ~/.ssh/config 文件中设置 Host windows，然后指定 Hostname=localhost，Port=2222，User=ws1，这样就能通过 SSH 连接到 WSL2 环境。

为了防止配置文件重复，建议用 Host block 来定义不同环境。比如，用 Host dev 来连接测试服务器，用 Host prod 来连接生产服务器。这样每次连接时，只需要输入 ssh dev，就能自动加载配置。如果配置文件里写了很多 Host，最好按环境分类，比如 dev、prod、docker、k8s，这样查找起来更方便。配置文件的结构也要清晰，避免写死路径，尽量用相对路径，这样在不同机器上都能正常运行。

有些服务器要求特定的密钥格式，比如 PKCS#8 或 PEM。这时候需要用 ssh-keygen -m PEM 来生成密钥。如果服务器不支持 PKCS#8，可以转换格式，用 ssh-keygen -p 命令转换。另外，如果服务器要求密钥有特定的注释，比如 "dev key"，可以在生成密钥时用 -C 参数添加注释。这样在配置文件里就能清晰识别每个密钥对应哪个服务器，避免混淆。密钥管理要规范，建议用一个目录来存放所有密钥，比如 ~/.ssh/id_rsa_dev，然后在配置文件里引用。