VSCode Remote-SSH 是否生效取决于系统 ssh 命令能否在启动环境中正确加载 ~/.ssh/config；GUI 启动常不加载 shell 配置，导致 $HOME 错误、ssh 找不到 config 或调用错误二进制，应优先通过终端启动验证。
VSCode 的 Remote-SSH 插件默认读取 ~/.ssh/config，但是否真正生效，取决于它调用的系统 ssh 命令能否在当前运行环境下正确加载该文件——多数连接失败不是配置写错了，而是 VSCode 启动时根本没看到你的 config。
为什么终端能连上，VSCode 却报 Permission denied (publickey)
这是最典型的环境不一致问题。VSCode 桌面端（尤其是 macOS Dock 点开、Windows 双击启动）往往不加载 shell 配置（~/.zshrc、~/.bash_profile），导致：$HOME 错误、ssh 找不到 ~/.ssh/config、甚至调用了错误的 ssh 二进制。
- 在 VSCode 内置终端里执行
echo $HOME和ssh -G your-host-name | grep 'identityfile\|user\|hostname'，和你在 iTerm / Terminal 里运行结果必须完全一致 - macOS 用户应改用终端启动：
code --remote ssh-remote+your-host-name - Windows + WSL 用户注意：VSCode Desktop 默认走 Windows OpenSSH，若想用 WSL 的
~/.ssh/config，需在设置中将remote.ssh.path明确设为/usr/bin/ssh - 不要依赖 GUI 启动方式做调试；所有验证务必在终端中完成
Host 别名写法与匹配规则的实际限制
OpenSSH 的 Host 匹配是**顺序优先、首个命中即止**，且不支持正则，只认 *（任意）、?（单字符）、!（排除）。VSCode Remote-SSH 对通配符支持不稳定，生产环境建议全用精确别名。
- 别名不能含下划线（
_）或大写字母——旧版 OpenSSH 会静默忽略，连接时直接 fallback 到默认行为 -
HostName必须是真实可达的 IP 或域名；写成localhost并不能“自动转发到跳板机”，必须显式配ProxyJump - 多个 Host 共享参数？别复制粘贴，用
Include ~/.ssh/common.conf复用（要求 OpenSSH ≥7.3） - 测试配置是否被识别：
ssh -F ~/.ssh/config -G your-host-name，看输出里的hostname、user、identityfile是否符合预期
跳板机（ProxyJump）配置常见断点
通过跳板机连内网服务器时，ProxyJump 是最简洁可靠的方案，但容易卡在“Resolving host…”或权限拒绝，根源常在控制连接复用冲突或跳板机自身配置缺失。
- 确保跳板机本身也允许 SSH 登录（
sshd_config中PermitTunnel yes非必需，但AllowTcpForwarding yes必须开启） - VSCode 默认启用
ControlMaster auto，若你同时在终端用相同 Host 连接跳板机，可能因 socket 文件锁导致阻塞；可在 config 中对跳板机段加ControlMaster no -
ProxyJump值必须是另一个已定义的Host别名，不能是裸 IP 或未声明的主机名 - 如果跳板机需要密钥而目标机需要另一把密钥，
IdentityFile仍写在目标 Host 段下，OpenSSH 会自动分层使用
Git 操作不走 SSH Config？检查 VSCode 调用的 git 和 ssh
VSCode 的 Source Control 面板里 Git 提交失败、拉取报 Permission denied，往往不是 Remote-SSH 连接问题，而是 VSCode 内置终端没继承 ssh-agent 或 Git 没走对 SSH 代理路径。
- VSCode 默认使用系统 PATH 下的
git，不是内置版本；确认which git输出和终端一致 - macOS：在
~/.ssh/config中为对应 Host 加AddKeysToAgent yes，并确保ssh-agent已启动 - Windows：手动运行
ssh-add ~/.ssh/id_rsa_work（私钥路径按实际填），或改用无密码私钥（仅限可信环境） - Git 的 SSH 行为完全由
core.sshCommand配置或环境变量GIT_SSH_COMMAND控制，VSCode 不干预这一层
最易被忽略的点：VSCode Remote-SSH 的行为是“镜像系统 ssh 命令”，不是独立实现。任何你以为“VSCode 应该支持”的功能，都得先在终端里 ssh -F ~/.ssh/config -v your-host 跑通。配置文件语法没错、密钥权限（chmod 600）对了、网络通了，剩下的几乎全是环境变量和启动上下文的问题。
