PyCharm远程开发连接失败排查与解决

PyCharm 远程开发连接失败：SSH 测试成功，却提示 No connection handle was returned

使用 PyCharm 的"远程开发"功能连接 Linux 服务器时，SSH 检查已经通过，但点击"下载 IDE 并连接"后，仍然出现连接失败弹窗。本文记录一次实际排查过程：最终发现，后台残留的 JetBrains Gateway 仍在使用旧的 SSH 配置，彻底退出相关进程后重新连接，问题解决。

本文中的服务器地址、用户名示例和项目路径均已做匿名化处理。这里的解决方法适用于本次日志所指向的问题；相同弹窗也可能由其他原因引起。

一、问题现象

在 PyCharm 的远程开发界面，填写服务器信息并检查连接后，页面显示连接成功。

随后点击："文件"→"远程开发"→"新建连接"→选择 IDE 版本和远程项目目录，点击"下载 IDE 并连接"，出现两个错误：

当时的环境如下：

项目	环境
本地系统	Windows 11
本地 PyCharm	2026.1.4
远程系统	Ubuntu 22.04.5 LTS，x86_64
连接方式	Remote Development，通过 SSH 连接
SSH 端口	自定义端口，本文以 23 为例

需要先区分两个功能：远程开发 会部署并启动远程 IDE 后端；SSH 远程解释器则是在本地 IDE 中使用服务器上的 Python。本次错误发生在前者。

二、先验证基础连接

1. PyCharm 中的 SFTP 测试成功

打开：

设置 → 构建、执行、部署 → 部署 → 连接 → 测试连接

测试结果显示 SFTP 连接成功，说明这套配置可以通过认证并建立文件传输连接。

不过，SFTP 成功并不能保证远程 IDE 的部署、启动和后续连接也能成功。

2. PowerShell 中的 SSH 登录成功

在本地 PowerShell 中执行，按实际情况替换参数：

ssh -p 23 your_user@your_server

能够进入 Ubuntu 命令行，说明此次测试中的服务器地址、端口和 SSH 登录链路可用。因此，排查重点转向 PyCharm 与 Gateway 之间的连接交接过程。

三、日志揭示真正的失败点

两个弹窗的信息比较笼统，真正有用的线索在 Gateway 日志中。

本次 Windows 环境下，日志位于以下目录结构中：

%LOCALAPPDATA%\JetBrains\PyCharm2026.1\log\gateway\<启动时间>\idea.log

其中 PyCharm2026.1 应替换成实际版本目录。也可以通过 PyCharm 的"帮助"菜单查找日志目录，或使用"收集日志和诊断数据"。

日志中出现了以下关键信息，连接配置 ID 已省略：

SSH configuration ID ... not found
No connection handle was returned

第一条错误说明：Gateway 收到了一个 SSH 配置 ID，但在自身已加载的配置中找不到它。 第二条则是连接创建失败后的后续报错。

进一步检查发现，接收请求的 Gateway 是此前启动后一直保留在后台的进程，其日志跨越了多天。它列出的已知 SSH 配置仍然是旧配置，没有包含这次要使用的新连接。

这解释了看似矛盾的现象：

• PyCharm 可以使用当前配置完成 SSH 或 SFTP 测试。
• 点击"下载 IDE 并连接"后，请求交给后台 Gateway。
• 残留的 Gateway 找不到请求中的 SSH 配置 ID，导致连接失败。

结合日志以及重启后的成功结果，本次问题可归因于后台 Gateway 保留了旧的 SSH 配置状态。

四、解决方法

1. 保存工作并退出相关窗口

保存当前工作，关闭 PyCharm、JetBrains Gateway，以及已打开的远程开发客户端窗口。

2. 清理残留的 Gateway 进程

打开 Windows 任务管理器，检查是否仍有 JetBrains Gateway 进程（直接在最上方搜）。

如果还有残留，将其结束。

关键是确认 Gateway 已经退出。仅关闭 PyCharm 窗口，可能没有退出后台的 Gateway。

不要直接结束所有 Java 进程，应先确认进程属于 JetBrains Gateway，避免影响其他程序。

3. 重新打开 PyCharm 并连接

重新进入"远程开发"，选择正确的 SSH 配置；必要时新建连接，并填写：

服务器：your_server
端口：实际 SSH 端口
用户名：your_user
认证方式：与已验证成功的连接一致

检查连接通过后，选择 IDE 版本和远程项目目录，再点击"下载 IDE 并连接"。

本次在彻底退出残留 Gateway 并重新连接后，连接恢复正常。

五、排查期间还发现的安装选项问题

排查过程中还尝试过手动上传安装包和修改安装目录。这两项并不是日志中 SSH configuration ID ... not found 的直接原因，但配置错误会影响后续部署。

Linux 服务器需要 Linux 安装包

本地电脑虽然是 Windows，但 IDE 后端要安装在 Ubuntu 服务器上。如果选择"上传安装程序文件"，需要使用 Linux 的 .tar.gz 安装包，例如：

pycharm-<version>.tar.gz

Windows 的 .exe 安装包不能用作 Ubuntu 上的远程 IDE 后端安装包。也可以直接恢复自动下载，由远程开发向导获取安装包。

安装目录使用默认路径

/dev 是 Linux 的设备目录，不应作为 IDE 安装目录。建议使用默认目录：

~/.cache/JetBrains/RemoteDev/dist

如果使用 root 用户，对应路径通常是：

/root/.cache/JetBrains/RemoteDev/dist

IDE 安装目录和项目目录是两个独立的设置。项目目录填写实际代码所在位置，例如 /home/your_user/project。

六、如果重启 Gateway 后仍然失败

不要仅凭 No connection handle was returned 判断原因，应查看同一时间附近、位于它之前的具体异常。

如果日志仍然提示 SSH configuration ID ... not found，继续检查是否有旧 Gateway 进程，或者在重新启动的 Gateway 中新建 SSH 连接。

如果日志已经变成其他错误，则根据新的失败点检查：

• 下载失败 ：检查远程服务器能否访问 JetBrains 下载服务；必要时使用本地上传的 Linux .tar.gz 安装包。
• 解压或安装失败：检查安装包格式、目标目录权限和磁盘空间。
• 后端启动或连接失败：检查服务器资源、启动日志，以及 SSH 是否允许所需的 TCP 转发。

这些是其他可能的排查方向，本次没有通过修改服务器 SSH 配置或 Python 环境来解决问题。

参考资料

• JetBrains：通过 PyCharm 连接远程服务器
• JetBrains：远程开发故障排查与日志收集