修复 VS Code Remote SSH 的 terminalRemoteResolver API 错误

VS Code Remote SSH 前一天还可以正常连接，第二天却突然失败。输出面板里有很多 ENOENT，最后又冒出一段很长的扩展错误：

Extension 'ms-vscode-remote.remote-ssh' CANNOT use API proposal:
terminalRemoteResolver.

Its package.json#enabledApiProposals-property declares:
resolvers, tunnels, terminalDataWriteEvent, contribRemoteHelp,
contribViewsRemote, telemetry but NOT terminalRemoteResolver.

这次问题发生在 Windows 本机，使用的是 VS Code 1.134.0 和 Remote SSH 0.126.0。最终的解决办法是把 Remote SSH 回退到 0.124.0。远程服务器的 SSH 配置、密钥和 VS Code Server 都没有改。

先别被一串 ENOENT 带偏

日志开头会看到 VS Code 在很多目录下寻找 ssh.exe：

Checking ssh with "C:\Program Files\...\ssh.exe -V"
Got error from ssh: spawn C:\Program Files\...\ssh.exe ENOENT

单看这些内容，很容易以为本机 OpenSSH 损坏了。继续往下看，VS Code 已经找到了系统自带的客户端：

Checking ssh with "C:\WINDOWS\System32\OpenSSH\ssh.exe -V"
OpenSSH_for_Windows_9.5p2, LibreSSL 3.8.2

前面的 ENOENT 只是逐个搜索候选路径时产生的记录。只要后面成功输出 OpenSSH 版本，它们就不是本次连接失败的原因。

真正的错误发生在连接命令刚生成之后：

"install" process failed: Error: Extension
'ms-vscode-remote.remote-ssh' CANNOT use API proposal:
terminalRemoteResolver.

从时间上也能看出来，失败发生得太快，SSH 认证、远程 Shell 和 VS Code Server 安装都还没有开始。此时去修改远程 sshd_config 或删除 ~/.vscode-server，处理的是另一个问题。

完全关闭 VS Code 仍然无效

我最初怀疑扩展刚更新过，VS Code 进程还缓存着旧清单。于是完全退出 VS Code，并检查 Code.exe、code-tunnel 等相关进程。进程确实已经全部结束，但重启后的最新日志仍然报同一个错误。

这一步排除了残留扩展宿主。继续看 renderer.log，终于出现了决定性的内容：

Extension 'ms-vscode-remote.remote-ssh' appears in product.json
but enables LESS API proposals than the extension wants.

package.json (LOSES):
resolvers
tunnels
terminalDataWriteEvent
terminalRemoteResolver
contribViewsRemote
telemetry
contribRemoteHelp

product.json (WINS):
resolvers
tunnels
terminalDataWriteEvent
contribRemoteHelp
contribViewsRemote
telemetry

DELTA: terminalRemoteResolver

Remote SSH 0.126.0 的 package.json 请求使用 terminalRemoteResolver，当前 VS Code 的 product.json 许可名单里却没有它，而且 product.json 优先。扩展因此在本机就被拦截了。

这不是单台机器上的偶发现象。VS Code 官方仓库的 terminalRemoteResolver 问题记录了同类故障，另一个 Remote SSH 连接报告给出了几乎相同的错误文本。后者使用 VS Code 1.133.0 和带日期的 Remote SSH 0.125 构建，也是在连接远程主机之前失败。前一个问题后来归入 VS Code 1.136.0 里程碑；在仍使用 1.134.0 时，先回退扩展是更直接的恢复办法。

回退到上一个可用的稳定版

新版 VS Code 的扩展菜单不一定再显示“安装其他版本”，而是提供“下载特定版本的 VSIX”。可以下载旧版 VSIX 后再执行“扩展: 从 VSIX 安装”，也可以直接使用命令行。

VS Code CLI 文档支持在扩展 ID 后追加 @版本号，并用 --force 安装指定版本：

code --install-extension "ms-vscode-remote.remote-ssh@0.124.0" --force

这里有一个容易浪费时间的细节：当时的版本列表里没有正式的 0.125.0。0.125 系列使用的是 0.125.2026082115 这类带日期的版本号，上一个正式稳定版是 0.124.0。如果执行下面的命令：

code --install-extension "ms-vscode-remote.remote-ssh@0.125.0" --force

CLI 会提示扩展不存在：

Extension 'ms-vscode-remote.remote-ssh\@0.125.0' not found.

输出中的 \@ 看起来像输入时多了反斜杠，但即使在 PowerShell 中用 [char]64 生成 @，结果仍然一样。真正的问题是版本号不存在，不是 PowerShell 转义。

安装完成后可以检查当前版本：

code --list-extensions --show-versions |
  Select-String 'ms-vscode-remote.remote-ssh'

预期输出为：

ms-vscode-remote.remote-ssh@0.124.0

随后重新打开 VS Code，Remote SSH 恢复连接。为了避免扩展马上自动升级回有问题的版本，可以暂时关闭 Remote SSH 的自动更新。等 VS Code 和扩展重新对齐后，再恢复自动更新并重新验证。

不建议使用的绕过方式

错误信息会建议添加：

--enable-proposed-api ms-vscode-remote.remote-ssh

这是扩展开发和测试时使用的参数，不适合作为官方稳定版扩展的长期修复。手工修改 VS Code 安装目录里的 product.json 也有同样的问题：它绕过了产品的 API 许可限制，下次更新还会被覆盖。

这次故障也不需要清理远程 VS Code Server。只有日志已经完成 SSH 认证，并明确指向远程 Server 安装、启动或端口转发失败时，才应该检查 ~/.vscode-server、sshd_config 和服务器日志。

下次按什么顺序判断

再遇到 Remote SSH 突然失效，我会先在“输出”面板选择 Remote - SSH，找到第一条真正中断流程的错误，而不是从日志里最早出现的 ENOENT 开始修。

如果系统最终找到了 ssh.exe，而错误包含 CANNOT use API proposal、product.json (WINS) 或 DELTA: terminalRemoteResolver，就先检查 VS Code 与 Remote SSH 的版本组合。这类错误发生在本机扩展加载阶段，与远程主机是否在线、密钥是否有效无关。

确认是版本兼容问题后，回退扩展比修改产品白名单更稳妥。版本恢复后再重新连接，能够把本机扩展故障和后续可能出现的 SSH 网络、认证问题分开处理。