VS Code Remote-SSH扩展指定自定义端口仍默认用22连接求助

问题背景 #

使用VS Code Remote-SSH扩展2年，近期无法连接配置了自定义端口的远程服务器（手动SSH连接正常，排除服务器端问题）。无论采用哪种SSH配置，扩展始终默认使用22端口连接，报错信息如下：

Install terminal quit with output: ssh: connect to host_name port 22: Connection refused
Received install output: ssh: connect to host_name port 22: Connection refused
Failed to parse remote port from server output

尝试过的SSH配置包括：

Host server_name
  HostName server_ip_address
  User username
  Port 1234

# 曾解决过扩展不使用指定用户名的问题
Host username@server_name
  HostName server_ip_address
  User username
  Port 1234

# server_name已在本地hosts文件中配置对应IP
Host server_name
  HostName server_name
  User username
  Port 1234

上述配置此前稳定运行9个月，近期突然失效。

排查与解决步骤 #

• 确认扩展读取的配置文件路径
  打开VS Code命令面板（Ctrl+Shift+P / Command+Shift+P），输入 Remote-SSH: Open SSH Configuration File，确认选择的是你修改的目标配置文件（通常是~/.ssh/config或Windows下的C:\Users\<用户名>\.ssh\config）。扩展可能误读其他路径的配置文件，导致自定义端口不生效。

• 验证SSH配置文件语法
  SSH配置对格式要求严格，确保每个配置项（HostName、User、Port）前使用空格缩进（禁止用制表符），无语法错误。可通过本地命令测试配置有效性：ssh server_name，如果能正常连接，说明配置文件本身没问题；若不能，先修正语法问题。

• 重置扩展缓存
  扩展可能缓存旧连接信息，导致忽略新配置：

  1. 完全关闭VS Code
  2. 删除缓存目录：
     • Windows：%USERPROFILE%\AppData\Roaming\Code\CachedData、%USERPROFILE%\AppData\Roaming\Code\CachedExtensions
     • macOS：~/Library/Application Support/Code/CachedData、~/Library/Application Support/Code/CachedExtensions
     • Linux：~/.config/Code/CachedData、~/.config/Code/CachedExtensions
  3. 重启VS Code后重新尝试连接

• 更新VS Code及Remote-SSH扩展
  旧版本扩展可能存在端口解析bug，更新到最新版本：

  1. 在扩展面板找到Remote-SSH，点击更新
  2. 通过帮助>检查更新升级VS Code本身

• 测试VS Code内置SSH命令
  在VS Code终端执行 ssh -F <你的配置文件路径> server_name，如果能正常连接，说明扩展调用SSH时可能存在参数异常；若仍使用22端口，检查是否有系统环境变量覆盖了配置。

• 排除全局SSH配置干扰
  检查系统级SSH配置（如/etc/ssh/ssh_config），其中的全局设置（比如Port 22）或针对该服务器的条目可能覆盖用户级配置。如有冲突，可注释或调整配置优先级。

• 测试干净VS Code环境
  临时重命名VS Code配置目录，排查是否为本地配置导致的问题：

  • Windows：%USERPROFILE%\AppData\Roaming\Code → 重命名为Code_old
  • macOS：~/Library/Application Support/Code → 重命名为Code_old
  • Linux：~/.config/Code → 重命名为Code_old
    重启VS Code后仅安装Remote-SSH扩展，重新配置连接测试。

内容的提问来源于stack exchange，提问作者KyleDev