@[toc]

修复 VS Code Remote-SSH 连接超时：启用 PTY 分配

在这里插入图片描述

适用场景

出现 Remote-SSH 连接阶段超时（例如 Connecting with SSH timed out），同时满足以下特征：

  • ICMP 连通（ping 正常）
  • TCP/22 连通（Test-NetConnection <REMOTE_HOST> -Port 22 为 True）
  • 命令行 ssh -vvv <USERNAME>@<REMOTE_HOST> 可成功认证并进入 Shell
  • VS Code Remote-SSH 日志中存在 remote.SSH.permitPtyAllocation = false（或等价配置）

根因

Remote-SSH 建连不只是建立 TCP 会话，还会在远端通过 ssh ... sh 执行初始化脚本（探测、安装、启动 VS Code Server）。

当 PTY（伪终端）分配被禁用 时，常见后果包括：

  • 远端脚本输出被缓冲或输出形态变化，客户端等待不到期望标记
  • 远端登录脚本或环境初始化逻辑在非交互会话下阻塞（例如涉及终端能力检测的逻辑）
  • 初始化阶段无法按预期完成，最终触发连接超时

解决方案

启用 PTY 分配后再重连

在 VS Code 设置中启用：

  • Remote.SSH: Permit PTY Allocation = true

或在 settings.json 中配置：

1
2
3
{
  "remote.SSH.permitPtyAllocation": true
}

完成后重启 VS Code，再次发起 Remote-SSH 连接。

可选增强配置

显示登录终端以避免交互被吞

当远端首次连接需要确认指纹、或存在需要交互输入的场景时，建议启用：

1
2
3
{
  "remote.SSH.showLoginTerminal": true
}

验证方式

验证 22 端口可达

运行：

1
Test-NetConnection <REMOTE_HOST> -Port 22

期望：

  • TcpTestSucceeded : True

验证命令行 SSH 可进入 Shell

运行：

1
ssh -vvv <USERNAME>@<REMOTE_HOST>

期望：

  • Authentication succeeded (publickey).
  • 进入远端 shell 提示符

若上述两项均正常但 VS Code 仍超时，优先检查 remote.SSH.permitPtyAllocation 是否被禁用或被工作区配置覆盖。

结论

Remote-SSH 超时且网络与 SSH 服务正常时，禁用 PTY 分配是高概率根因。启用 remote.SSH.permitPtyAllocation 可使远端初始化脚本按预期完成，从而恢复连接流程。