# 远程与本地源

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

> **TL;DR**
> 本地客户端操作系统  ：macOS / Linux / Windows
>
>
>
> 远程主机操作系统  ：Linux
>
>
>
> 源代码位置  ：本地运行并自动同步到远程主机
>
>
>
> 远程主机所需的工具  ： [rsync](https://rsync.samba.org/) 用于 macOS/Linux/Windows 客户端， [tar](https://www.gnu.org/software/tar/) 用于 Windows 客户端
>
>
>
> 项目模型  ： [CMake](quick-cmake-tutorial.html) / [Makefile](makefiles-support.html)
>
>
>
> 必需插件  （  捆绑，默认启用 ）：FTP/SFTP/WebDAV 连接

此远程模式使您能够在 CLion 上的 macOS、Linux 或 Windows 桌面上工作，目标是通过 [SSH](https://en.wikipedia.org/wiki/Secure_Shell) 连接的远程 Linux 机器。 您可以选择   任何基于 Linux 的目标  ，包括单板计算机上的嵌入式系统，例如 [Raspberry Pi](https://www.raspberrypi.org/)。 此外，您的程序可以在云平台上启动，或者例如在 [Docker](clion-toolchains-in-docker.html) 容器中运行。

在此模式下，IDE 实例在本地运行，您的源文件也放置在本地客户端，并自动同步到远程主机。 在远程主机端，CLion 使用主机编译器和 CMake/make 执行编译和构建，使用主机 GDB 进行调试，并在远程目标上运行应用程序。

## 工作流程步骤

CMake:

1.

[创建远程工具链](#remote-toolchain)：

* 提供凭据并检查连接，

* 等待工具检测，如果需要，请手动提供路径。

2.

将远程工具链设置为   默认   或 [创建关联的 CMake 配置文件](#CMakeProfile)。

3.  如有需要，请在 [部署条目](#deployment-entry) 中调整路径映射。

4.

使用   默认配置   或选择   步骤 2 中的配置   进行构建、运行和调试。

Makefile:

1.

[创建远程工具链](#remote-toolchain)：

* 提供凭据并检查连接，

* 等待工具检测，如果需要，请手动提供路径。

2.

在  `设置 | 构建、执行、部署 | Makefile`  中切换到远程工具链。

3.  如有需要，请在 [部署条目](#deployment-entry) 中调整路径映射。

4.

调用  `工具 | Makefile | 清理并重新加载 Makefile 项目` 。

在配置设置中，将   可执行文件   指向远程二进制文件。

Procedure: Windows 客户端特性

在   Windows 客户端   上工作时，请注意以下事项：

* 由于 IntelliJ 平台的 [问题](https://youtrack.jetbrains.com/issue/IDEA-135546)，您需要在  `idea.properties`  文件中设置 [属性](tuning-the-ide.html#configure-platform-properties) 值  `idea.case.sensitive.fs=true` （要访问属性文件，请从主菜单中选择  `帮助 | 编辑自定义属性...` ），然后重启 CLion 并重置缓存（  `文件 | 使缓存无效 / 重启...` ）。

* 在 Windows 上进行文件同步时，默认情况下，CLion 依赖于其自身的   远程主机访问  ，并在主机端使用   tar   实用程序进行压缩。 此机制比在 macOS 和 Linux 上使用   Rsync   工具的同步速度更慢。 您可以通过在 [部署设置](deployment-connection-tab.html#sftp-settings) 中选择   使用 rsync 进行下载/上传/同步   复选框来启用 Windows 上的   Rsync   同步。

Procedure: 使用远程凭据创建工具链

1. 转到  `设置 | 构建、执行、部署 | 工具链` 。

2. 点击 ![加号图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   远程主机  ：

![添加远程工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_toolchains_addremote.png)

3. 如果您已有 [SSH 配置](create-ssh-configurations.html)，请从   凭据   列表中选择它：

![选择 SSH 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_toolchains_remote_sshconfigslist.png)

否则，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.settings.svg)，位于   凭据   字段旁边。 在打开的对话框中，创建一个 SSH 配置并提供访问远程机器的凭据：

![创建新的 SSH 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_toolchaincredentials.png)

4. 建立连接后，CLion 会尝试在默认的远程位置  `/usr/bin/cmake`  和  `/usr/bin/gdb`  检测工具（如果您手动提供了完整路径，也会使用这些路径）。 检查成功完成后，工具链即可使用：

![远程工具链配置成功](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_toolchainsuccess.png)

5. 您可以将新创建的工具链设置为   默认  （为此，请通过点击 ![向上移动](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.moveUp.svg) ![向下移动](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.moveDown.svg) 将其移至工具链列表顶部）。 设置为默认后，远程工具链将用于您在 CLion 中创建和打开的所有项目。

对于 CMake 项目，如果您将远程工具链设置为默认，   默认 CMake 配置   将自动连接到它，因此您无需为其配置单独的 CMake 配置文件。

Procedure: （CMake）创建相应的 CMake 配置文件

* 转到  `设置 | 构建、执行、部署 | CMake` 。

* 点击 ![加号图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 创建一个新的 [CMake 配置文件](cmake-profile.html)，并使用   工具链   字段将其连接到您的远程工具链：

![远程工具链的 CMake 配置文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_cmakeprofile.png)

或者，将远程工具链设置为 [默认](#RemoteAsDefault)，并选择   使用默认值  。

* Apply   更改。

Procedure: （Makefile）在 Makefile 设置中选择远程工具链

1. 转到  `设置 | 构建、执行、部署 | Makefile` 。

2. 在   工具链   字段中选择您的远程工具链：

![为 Makefile 选择远程工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_toolchain_remote.png)

或者，将远程工具链设置为 [默认](#RemoteAsDefault)，并选择   使用默认值  。

3. Apply   更改。

4. 使用   文件传输   工具窗口（  `视图 | 工具窗口 | 文件传输` ）监控文件同步的进度：

![上传通知](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_upload_remote.png)

Procedure: 检查并调整部署配置

当您为远程工具链创建连接实体时，CLion 会将其放入 [服务器访问配置](settings-deployment.html) 列表中，位于  `设置 | 构建、执行、部署 | 部署` 。

* CLion 会自动配置您的项目代码同步路径。 使用   映射   选项卡更改默认映射（例如，为复制的源代码设置特定的远程目录，而不是默认的  `tmp`  文件夹）：

![文件同步的路径映射](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_pathmappings.png)

* CMake:

对于 CMake 项目，当您更改部署设置时，CLion 会自动触发同步。 您可以在   文件传输   工具窗口（  `视图 | 工具窗口 | 文件传输` ）中监控该过程：

![文件传输工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_filetransfer.png)

将项目上传到远程机器时，CLion 使用包含顶层  `CMakeLists.txt`  的目录作为项目根目录（ [CPP-23995](https://youtrack.jetbrains.com/issue/CPP-23995)）。 如果您的顶层  `CMakeLists.txt`  位于不同的子目录中，请在   映射   选项卡中更改本地路径。

Makefile:

将 Makefile 项目上传到远程机器时，CLion 使用包含 Makefile 的目录作为项目根目录（请参阅通用工单 [CPP-23995](https://youtrack.jetbrains.com/issue/CPP-23995)）。 如果您的 Makefile 位于不同的子目录中，请在   映射   选项卡中更改本地路径。

* 您可以设置远程开发   无源代码同步  ，以避免当本地和远程机器共享挂载卷时（例如，使用 [Docker](docker.html) 容器的情况）或在 CLion 外部配置了第三方同步时出现不必要的文件重复。

为此，请打开   连接   选项卡并将连接类型更改为   本地或已挂载的文件夹  ，然后设置路径映射（对于 Docker，请指定映射的卷）。

![无源代码同步](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_deploy_nosync_docker.png)

CLion 在 CMake 重新加载时始终下载 CMake 构建文件夹。 但是，如果选择了   本地或已挂载的文件夹   部署类型，并且 CMake 构建文件夹存储在现有路径映射之一下，则可以跳过此步骤。

* SFTP 连接的部署过程可以通过 Rsync 工具加速。 在 macOS 和 Linux 上，默认启用 Rsync 支持；在 Windows 上，您需要在 [部署设置](deployment-connection-tab.html#sftp-settings) 中选择   使用 rsync 进行下载/上传/同步   复选框以启用。

Procedure: 排除路径

默认情况下，CLion 分析并同步列在  `CMakeLists.txt`  中的所有目录。 但是，如果您使用   将目录标记为 | 排除   操作 [排除](project-analysis.html#exclude_directory_from_project_analysis) 某个目录，该目录将被标记为   排除路径   用于远程部署，并且不会与远程机器同步。 在配置远程工具链之前排除文件夹时，此操作会自动执行。

您可以在 [部署条目](#deployment-entry) 设置的专用选项卡中检查并调整排除路径：

![排除路径](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_excluded_paths.png)

* 如果在已配置远程工具链并且项目已同步的情况下将目录标记为排除，CLion 将建议您更新排除路径。 更新后，排除的文件夹将继续同步。

![建议更新部署排除路径](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_mark_as_excluded.png)

* 如果您取消排除之前排除的目录，CLion 将建议更新排除路径列表并将文件夹重新上传到远程主机。

![建议更新部署排除路径并重新上传文件夹](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_unmark_excluded.png)

Procedure: 重新同步头文件搜索路径

* 为了正确解析您的代码，CLion 会将   头文件搜索路径   与远程机器上的所有内容同步到本地客户端。  例如 ，即使标准库头文件来自目标，您也可以像在 CLion 编辑器中本地工作一样导航到它们。

然而，头文件搜索路径的同步可能耗时，因此 CLion 仅在初始文件传输时自动执行此操作。 之后，它不会因 CMake 或 Makefile 的重新加载而触发。 因此，每次切换编译器或更改项目依赖项时，请确保通过调用  `工具 | 与远程主机重新同步`  手动更新头文件搜索路径。

> **Note:**
> 请注意，每次更改项目依赖项或编译器时，您都需要手动调用   与远程主机重新同步  。

您还可以切换到自动同步：在注册表中设置  clion.remote.resync.system.cache  键（转到  `帮助 | 查找操作`  或按 `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `⌘ ⇧ A` (Xcode), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (ReSharper), `⌘ ⇧ A` (ReSharper (macOS)), `Ctrl+Shift+A` (QtCreator), `⌘ ⇧ A` (QtCreator (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS))，输入  Registry ，并按名称搜索该键）。

从 2022.3 版本开始，CLion 使用 [pigz](https://zlib.net/pigz/) 在远程主机上进行压缩，以将头文件搜索路径同步回本地主机，而不是  gzip 。 这种多线程的  gzip  实现使操作速度更快。

Procedure: 构建、运行、调试

CMake:

现在，您已配置远程工具链及其对应的 CMake 配置文件，您可以通过在运行/调试配置切换器中   选择正确的 CMake 配置   以完全远程的方式构建、运行和调试您的应用程序和测试：

![远程的 cmake 配置文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_profile.png)

以下是一个演示，展示了应用程序输出如何根据运行的操作系统而变化。 以 macOS 作为本地系统，我们远程连接到 Ubuntu 目标并检查操作系统名称。 在此示例中，代码高亮取决于操作系统标识符，因此当我们切换 CMake 配置文件或 [解析上下文](switching-resolve-context.html) 时，CLion 会高亮显示相应的代码分支：

![选择远程运行的构建配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remote_runapp.animated.gif)

Makefile:

1.  创建一个新的 [本机应用程序](makefiles-support.html#create-makefile-config) 配置或编辑现有配置。

2.

在   可执行文件   字段中，将 CLion 指向  远程  二进制文件。

> **Tip:**
> 要快速找到远程主机上项目目录的路径，请调用  `工具 | 打开远程主机终端` 。

![配置设置中的远程可执行文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_remote_config.png)

3.  保存配置并使用它远程运行或调试您的 Makefile 应用程序。

> **Tip:**
> 对于 CMake 和 Makefile 配置，您可以将 [远程外部工具](settings-tools-remote-ssh-external-tools.html) 设置为   启动前   步骤。

Procedure: 设置环境变量

1. 要为远程操作系统配置环境变量，请在  `.bashrc`  文件的开头，在  `# If not running interactively, don't do anything`  行之前指定它们。

如果您的主要 shell 不是  bash ，请按照该特定 shell 的说明操作，或将  `PermitUserEnvironment yes`  添加到  `sshd_config`  文件中，重启  sshd  服务，然后在  `~/.ssh/environment`  中配置变量。

Procedure: 启用 IPv6 支持

* 要连接到 [IPv6](https://en.wikipedia.org/wiki/IPv6) 网络，您需要在 CLion 的 [JVM 选项](tuning-the-ide.html#configure-jvm-options) 中进行调整：

1.

从主菜单运行  `帮助 | 编辑自定义 VM 选项` 。 在打开的  `*.vmoptions`  文件中，删除  `-Djava.net.preferIPv4Stack=true`  行并添加以下行：

```CONSOLE
-Djava.net.preferIPv4Stack=false
-Djava.net.preferIPv6Stack=true
-Djava.net.preferIPv6Addresses=true
                    
```

2.  重启 CLion。

* 为了使用   主机名   替代原始地址，请以管理员身份在 Windows 上打开  `C:\Windows\System32\Drivers\etc\hosts`  或在 macOS/Linux 上以超级用户身份打开  `/etc/hosts` ，并将所需地址映射到相应的主机名。

每个地址应放在单独的一行，后跟至少一个空格和一个以空格分隔的主机名列表，例如：

```CONSOLE
f381::171d:c61c:c7f3:3a56      my.dev.host1 my.dev.host2
f381::171d:c61c:c7f3:3a26%en0  my.dev.host3
        
```

* 在   macOS   上，您还需要指定被禁用的网络接口列表：

1.  请按 `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `⌘ ⇧ A` (Xcode), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (ReSharper), `⌘ ⇧ A` (ReSharper (macOS)), `Ctrl+Shift+A` (QtCreator), `⌘ ⇧ A` (QtCreator (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)) 或从主菜单中选择  `帮助 | 查找操作` 。 在打开的弹出窗口中，开始输入  `Registry` ，选择相应的项目并按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `⏎` (Xcode), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (ReSharper), `⏎` (ReSharper (macOS)), `Enter` (QtCreator), `⏎` (QtCreator (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。

2.  找到   deployment.macOs.bannedInterfaces   键并设置以逗号分隔的被禁用接口列表，例如  `awdl0,bridge0,en1,en2,lo0,p2p0,utun0,utun1` 。

## See also

### 操作指南

[Remote development overview](remote-development.html)

### 概念

[Run/Debug Configurations](run-debug-configuration.html) [CMake 配置文件](cmake-profile.html)

### 流程

[Building](build-actions.html) [Deploying](deploying-applications.html) [Debugging](debugging-code.html)

### 操作指南

[复杂的远程场景](complicated-remote-scenarios.html)

### 外部链接

[CLion Blog: Using Docker with CLion](https://blog.jetbrains.com/clion/2020/01/using-docker-with-clion/) [Webinar Recording: Remote Development with CLion](https://blog.jetbrains.com/clion/2019/03/webinar-recording-remote-development-with-clion) [CLion Debugging Beyond the Basics - Part 3 - Beyond Local](https://blog.jetbrains.com/clion/2021/05/clion-debugging-beyond-the-basics-part-3-beyond-local)

