openidea/docs/zh/guide/remote/ssh.mdx

---
title: "SSH"
description: "打开位于 SSH 主机或 WSL 发行版中的项目，IDE 后端在代码所在的机器上运行。"
---

远程开发让你在普通的 OpenIDEA 窗口里打开另一台机器上的项目文件夹。界面留在本机，IDE 后端
[`openidea-server`](/zh/guide/remote/server) 运行在远程主机上：索引、语言服务器、终端、运行配置、调试器、构建工具和 Git
都在代码旁边执行。

OpenIDEA 通过 SSH 连接；在 Windows 上也可以直接连入 WSL 发行版。开发容器见[容器](/zh/guide/remote/containers)。

## 前提条件

- SSH 主机运行 Linux（x86_64 或 aarch64）或 macOS（Apple 芯片或 Intel）。不支持 Windows 主机。
- 主机上有 POSIX shell 以及 `uname`、`gzip`、`mkdir`、`chmod`、`mv`、`find`，并启用了 SFTP 子系统（安装服务端和连接对话框里的**浏览**都要用到）。
- 首次连接时，本机会下载对应版本的 `openidea-server` 发布构建，再上传到主机。本机无法联网时，见[离线安装](/zh/guide/remote/server#离线安装)。

## 添加 SSH 配置

远程开发、运行目标、数据源隧道、部署服务器以及**启动 SSH 会话…**都使用应用级的 SSH 配置连接。

<Steps>
  <Step title="打开 SSH 设置">选择**工具 › SSH 配置…**，或打开**设置 › 工具 › SSH 配置**。</Step>
  <Step title="添加配置">点击 **+**（添加），填写**名称**、**主机**、**端口:** 和**用户名**。</Step>
  <Step title="选择身份验证方式">在**身份验证类型**中选择一项（见下表）。</Step>
  <Step title="测试连接">
    点击**测试连接**。如果主机密钥还不在 `~/.ssh/known_hosts` 中，OpenIDEA
    会显示该密钥并提供**信任主机并重试**，把它写入该文件。
  </Step>
</Steps>

| 身份验证类型                   | 使用的凭据                                                                                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **密码**                       | 密码。勾选**保存密码**后存入系统凭据库。                                                                                                                 |
| **密钥对（OpenSSH 或 PuTTY）** | **私钥文件**（例如 `~/.ssh/id_ed25519`）及其**密码短语**，勾选**保存密码短语**后存入凭据库。                                                             |
| **OpenSSH 配置和身份验证代理** | `~/.ssh/config` 中的 `HostName`、`User`、`Port`、`IdentityFile` 和 `ProxyJump`，以及 SSH 代理中的密钥。**主机**可以填 `~/.ssh/config` 里的 `Host` 别名。 |

保存的密码和密码短语存放在 macOS 钥匙串、Windows 凭据管理器或 Linux 的 Secret Service 中，不会写进设置文件。列表上方的
**+**、**−** 和复制按钮用于添加、移除和复制配置。

### `~/.ssh/config` 支持

OpenIDEA 自带 SSH 客户端，自行读取 `~/.ssh/config`，支持 `Host`、`Match`、`Include`、`HostName`、`User`、`Port`、
`IdentityFile`、`ProxyJump`、`ProxyCommand`、`StrictHostKeyChecking` 和 `UserKnownHostsFile`。跳板机通过代理和身份文件认证，
配置里的密码或密码短语只用于目标主机。

主机密钥会与 `known_hosts` 比对。未知密钥需要先信任一次；密钥发生变化时会拒绝连接，除非对该主机关闭了主机密钥检查。

## 打开远程项目

<Steps>
  <Step title="打开连接对话框">选择**文件 › 远程开发…**，或在欢迎页点击**远程开发**。</Step>
  <Step title="选择主机">在 **SSH 配置：**中选择一项。还没有配置时，点击**配置…**打开 SSH 设置。</Step>
  <Step title="选择文件夹">
    在**项目目录：**中输入路径（`~` 和 `~/…` 相对于远程用户主目录），或点击**浏览**逐级选择远程文件夹。
  </Step>
  <Step title="打开">点击**打开**。如果当前已有打开的项目，再选择**当前窗口**或**新窗口**。</Step>
</Steps>

连接过程中，对话框会依次显示各个阶段：连接主机、检查主机上的 IDE 后端、按需下载或安装、启动后端、打开项目。第一次连接某台主机时需要上传服务端，
会慢一些；之后会复用已安装的版本。

项目打开后，和本地文件夹一样会询问是否信任该项目。

<Tip>首次连接前，先在 SSH 设置里运行一次**测试连接**：信任新主机密钥、输入密码或密码短语都在这里完成。</Tip>

## 在远程窗口中工作

- 窗口标题末尾显示主机名，状态栏显示 **SSH: `<host>`**，点击它会打开**远程开发**对话框。
- 远程项目会出现在欢迎页的最近项目列表中，可以从那里重新打开。
- OpenIDEA 安装的语言服务器、调试器等工具都装在远程主机的 `~/.openidea/data` 下。
- 快捷键、外观、编辑器字体和配色方案保留在本机；项目和工具相关的设置保存在主机上。
- 你的代码插件会同步到服务端，在项目所在的机器上运行。
- **文件 › 断开与远程主机的连接**会关闭项目并断开连接。

### 端口转发

远程窗口中有一个**端口**工具窗口。在**远程端口，例如 3000**处输入端口，点击**转发端口**后，远程主机上的 `localhost:<port>`
就可以在本机访问：本机同号端口空闲时使用同一端口，否则换一个空闲端口。每一行都可以在浏览器中打开、复制地址或停止转发。

转发的端口按主机和文件夹记住，下次连接时会自动重新转发。

### 重新加载环境

服务端启动时会读取你在主机上的登录 shell 环境。修改 shell 配置文件后，选择**文件 › 重新加载环境**，新开的终端、运行和工具就会拿到新值；
已经在运行的进程保持原来的环境。如果有变量发生变化，通知里会提供**重启语言服务器**。

如果远程项目包含 `.devcontainer/devcontainer.json` 或 `.devcontainer.json`，其中的 `remoteEnv` 也会生效，`postStartCommand`
会在每次服务端启动时运行一次。

## 打开 SSH 终端

**工具 › 启动 SSH 会话…**（或终端工具窗口新建标签菜单里的 **SSH 会话…**）会让你选择一个 SSH 配置，并在终端标签页中运行对应的 `ssh`
命令。这里用的是本机的 OpenSSH 客户端，所以 `ssh` 必须在 `PATH` 中。它不会打开远程项目。

## 连接 WSL（Windows）

在 Windows 上，只要装有至少一个 WSL 发行版，连接对话框就会出现**连接方式：**，可选 **SSH** 或 **WSL**。选择 **WSL**，
在 **WSL 发行版：**中选好发行版，再在**项目目录：**中填写发行版内的路径。OpenIDEA 通过 `wsl.exe` 在发行版内安装并启动
`openidea-server`，不需要 SSH 服务器。状态栏随后显示 **WSL: `<distribution>`**。

打开 `\\wsl.localhost\<distribution>\` 下的文件夹时，也会自动通过该发行版打开。WSL 方式不支持**浏览**。

## SSH 配置的其他用途

- **运行目标**（**设置 › 构建、执行、部署 › 运行目标**）可以在 SSH 主机上执行运行配置，见[运行配置](/zh/guide/run)。
- **数据源**可以通过 SSH 隧道连接，见[数据库](/zh/guide/database)。
- **工具 › 部署**通过 SFTP 与服务器上传、下载和同步项目文件。

## 限制

- 一个远程窗口只对应一个项目：远程项目不能附加到其他窗口的项目中。
- SSH 主机必须是 x86_64 或 aarch64 上的 Linux 或 macOS。