# Docker 工具链

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

> **TL;DR**
> 平台  ：macOS / Linux / Windows / WSL
>
>
>
> 项目模型  ： [CMake](quick-cmake-tutorial.html) / [Makefile](makefiles-support.html)

为了在 Docker 容器中进行开发，CLion 通过专用的 Docker [工具链](how-to-create-toolchain-in-clion.html) 提供了完整的 Docker 集成。 观看此视频以了解更多信息：

[Video](https://www.youtube.com/v/p7Bi-mOyelM)

> **Note:**
> Docker 工具链不支持远程 TCP 和 SSH 连接。 要处理远程运行的容器，请使用 [Remote with Gateway](remote.html) 或 [Remote with local sources](remote-projects-support.html)。

Procedure: 示例 Dockerfile

为了帮助您开始在 CLion 中进行 Docker 开发，我们为基于 Ubuntu 的镜像创建了一个 [示例 Dockerfile](https://github.com/JetBrains/clion-remote/blob/master/Dockerfile.cpp-env-ubuntu)。 您可以将此文件复制到您的项目中并根据需要进行调整，或者仅将其用作参考。

示例文件包括以下行和部分：

* 在顶部的注释中，您可以找到用于 [构建](#build-and-run)容器的命令。

* `FROM ubuntu:20.04` 行指向容器的基础镜像。

* `apt-get` 部分将所有工具链依赖项安装到容器中。 在这里，您可以调整工具及其版本。

> **Tip:**
> 在 Linux 上，当 Docker 不是无根模式时，CLion 使用主机 UID，这是由于 [从 Docker 容器写入卷时的文件权限限制](https://dille.name/blog/2018/07/16/handling-file-permissions-when-writing-to-volumes-from-docker-containers/)。
>
>
>
> 作为一种解决方法，您可以将 Docker 守护进程配置为无根模式，或者在 Dockerfile 中创建一个参数化用户，例如：
>
>
>
>
> ```DOCKERFILE
> ARG UID=1000
> RUN useradd -m -u ${UID} -s /bin/bash builder
> USER builder
>
> ```
>
>
>
> 然后使用新的 UID 构建镜像：
>
>
>
>
> ```DOCKERFILE
> docker build --build-arg UID=$(id -u) ...
>
> ```

Procedure: 构建容器

> **Tip:**
> 另一种选择是使用来自 [docker registry](https://docs.docker.com/registry/) 的预构建容器。

* 从 Dockerfile 顶部运行  `docker build`  命令：

```
docker build -t clion/ubuntu/cpp-env:1.0 -f Dockerfile.cpp-env-ubuntu .
```

根据您的平台和 Docker 设置，您可能需要使用  `sudo`  运行它。

此命令将构建具有适当工具链依赖项的 Ubuntu 基础镜像。

Procedure: 创建 Docker 工具链

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

点击 ![添加工具链](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   Docker  ：

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

2. 点击   服务器   字段旁的齿轮按钮以添加 Docker 镜像：

![添加 Docker 镜像](https://resources.jetbrains.com/help/img/idea/2026.3/cl_docker_toolchain_add_image.png)

> **Note:**
> 在   使用以下方式连接到 Docker 守护进程   中列出的选项中，只有本地选项（第一个）可以在 CLion 中用作工具链。 对于远程 Docker，我们建议使用 [Remote with local sources](remote-projects-support.html)。

您还可以在  `设置 | 构建、执行、部署 | Docker`  中配置一个 Docker 服务器，然后在工具链设置中选择它。

3. 选择 Docker 镜像并等待工具检测完成。

![Docker 工具链已配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_docker_toolchain_configured.png)

使用   容器设置   字段提供其他容器设置，例如端口和卷绑定：

![Docker 容器设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_dockertoolchain_containersettings.png)

> **Tip:**
> 请参阅 [Docker 插件集成](docker.html)，了解服务工具窗口和 Docker 特定 IDE 操作的描述。
>
> ![Docker 服务工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/cl_docker_services.png)

Procedure: 使用 Docker 工具链进行构建、运行和调试

配置 Docker 工具链后，您可以在 [CMake 配置文件](cmake-profile.html)或 [Makefile 设置](makefiles-support.html#makefile-settings) 中选择它。 或者，将工具链移到列表顶部以将其设为默认。

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

* 项目文件夹将被挂载到 Docker 容器中，并在其中执行构建/运行/调试。 默认情况下，项目文件夹被挂载到容器中的 `/tmp` 文件夹。 但是，如果在 [工具链](#create-docker-toolchain) 中指定了路径映射，CLion 将使用这些映射。 例如，如果项目根目录是 `/data/code/project` ，工具链路径映射是 `/data/code` -> `/代码` ，那么 CLion 将重用此映射，并且不会将项目挂载到 `/tmp/project` 。 > **Tip:** > 除了项目根目录，CLion 还会挂载以下文件夹： > > > > `$TMPDIR/<major>_<minor>/Docker/<imageName>_<imageTag>`

* CLion 将启动容器并在命令执行后关闭它。

Procedure: SELinux 上的绑定挂载

您可以向 Docker 绑定挂载添加  `:z`  配置标志，以将文件和文件夹连接到在启用 SELinux 的工作站上运行的容器。 这允许 CMake 和其他工具访问您的项目文件以及系统上的其他文件。

1. 转到  `设置/首选项 | 高级设置 | Docker` 。

2. 选中相应的复选框：

![适用于 SELinux 系统的绑定](https://resources.jetbrains.com/help/img/idea/2026.3/docker_selinux_advsetting.png)

> **Tip:**
> 在 [Docker 容器：SELinux 上的绑定挂载](docker-containers.html#bind_mounts_selinux) 中查找更多详细信息。

Procedure: 提高 Windows 上 Docker 工具链的性能

为了在 Windows 上获得更好的性能，我们建议使用带有 WSL 2 后端的 Docker。

1. 设置 [带有 WSL 2 后端的 Docker Desktop](https://docs.docker.com/desktop/windows/wsl/)。

2. 在 Docker 桌面应用程序中，导航到  `设置 | 资源 | WSL 集成`  并启用与您的 WSL 分发版（例如，  `ubuntu-20.04` ）的集成。

3. 将项目源文件放入 WSL 文件系统中（例如，  `\\wsl$\ubuntu-20.04\tmp\llvm` ），然后在 CLion 中打开它并配置 Docker 工具链。

Procedure: 为 WSL 中的 Docker 启用调试输出

要在 WSL 中使用 Docker 工具链进行调试时获取调试输出，您需要在  `wsl.conf`  中进行更改。

1. 打开 WSL shell。

2. 打开  `wsl.conf`  文件进行编辑：

```CONSOLE
sudo $EDITOR /etc/wsl.conf

```

3. 添加以下行：

```CONSOLE
[automount]
root = /mnt
crossDistro = true
options = "metadata"

```

4. 保存更改。

5. 重启 WSL。 您可以通过运行  `wsl -t <distribution_name>`  来完成此操作。

## 替代工作流：使用远程和本地源在 Docker 中开发

> **Note:**
> 通常，我们建议按照上述描述使用 Docker 工具链。 这种替代方法可能在某些罕见情况下有用，例如，当您在 Windows 上遇到性能问题且 WSL 2 后端因某些原因不可用时。

在这种情况下，基于 Docker 的工具链通过 [Remote with local sources](remote-projects-support.html) 配置。 容器应运行一个 SSH 守护进程。

[Video](https://www.youtube.com/v/h69XLiMtCT8)

> **Tip:**
> 以下说明是 [在 CLion 中使用 Docker](https://blog.jetbrains.com/clion/2020/01/using-docker-with-clion/) 博客文章的简要总结。

### 远程场景的示例 Dockerfile

使用 [remote-cpp-env](https://github.com/JetBrains/clion-remote/blob/master/Dockerfile.remote-cpp-env) 示例文件。 它包括两个附加部分：

* `ssh` 部分设置了 CLion 连接所需的 SSH。

* `user` 部分在容器中创建了一个用户。

Procedure: 1. 构建容器

1. 使用 Dockerfile 顶部的  `docker build`  行：

```
docker build -t clion/remote-cpp-env:0.5 -f Dockerfile.remote-cpp-env .
```

根据您的平台和 Docker 设置，您可能需要使用  `sudo`  运行它。

此命令将构建具有适当工具链依赖项的 Ubuntu 基础镜像，设置 SSH 并创建用户。

Procedure: 2. 运行容器

1. 使用下一个命令，  `docker run` ：

```
docker run -d --cap-add sys_ptrace -p127.0.0.1:2222:22 --name clion_remote_env clion/remote-cpp-env:0.5
```

在此行中，  `-d`  以守护进程方式运行容器，  `--cap-add sys_ptrace`  添加了  `ptrace`  功能，这是调试所必需的。

`-p`  部分指定了端口映射。 它将容器内的默认 SSH 端口（22）暴露为主机环境上的端口 2222。 您可以在此处指定任何可用的端口号。

2. （可选）您可以使用  `-v`  标志创建映射卷：  `-v /local/path/to/project:/remote/path/to/project`

之后，转到  `设置 | 构建、执行、部署 | 部署` ，将连接类型更改为   本地或已挂载的文件夹  ，并设置路径映射。 请参阅 [Remote with local sources：检查并调整部署配置](remote-projects-support.html#deployment-entry)。

Procedure: 3. 清除缓存的 SSH 密钥

1. 构建和运行容器的最后一步是  `ssh-keygen`  命令，它会清除任何缓存的 SSH 密钥。 这很重要，因为本地主机端口只是临时映射的，可以被不同的容器重复使用。

```
ssh-keygen -f "$HOME/.ssh/known_hosts" -R "[localhost]:2222"
```

Procedure: 4. 创建远程主机工具链

此时，容器正在运行一个 SSH 服务器守护进程，您可以使用 CLion 的标准远程开发功能连接到它。

1. 请按照 [创建远程工具链](remote-projects-support.html#remote-toolchain)的一般说明操作。

在   凭据   字段中设置 SSH 配置：

* 主机 - localhost

* 端口 - 2222

* 用户名/密码 - 如 Dockerfile 中指定

2. 建立连接后，CLion 会尝试检测工具链。 由于工具已安装在默认位置，它们将被自动检测到。

如果您更改了 Dockerfile 中的  `apt-get`  部分以将工具安装到其他位置，请在   生成  、   C 编译器  、   C++ 编译器   和   调试器   字段中提供路径。

3. 创建一个使用远程工具链的 [CMake 配置文件](remote-projects-support.html#CMakeProfile)。 等待项目重新加载。

> **Note:**
> 如果收到错误消息  "需要 CMake 3.15. 或更高版本" ，说明容器中的 CMake 版本比本地项目的版本低。 您可以在  `CMakeLists.txt`  文件顶部更改版本。 作为更复杂的替代方案，可以在容器内构建更高版本的 CMake 或使用不同的基础镜像。

文件传输到容器后，您将能够在运行/调试配置切换器中选择配置文件，以使用指定的工具链在容器内构建、运行或调试代码。

> **Tip:**
> 默认情况下，您的项目代码会传输到容器中的默认位置。 要更改默认路径，请使用   映射   选项卡中的 [部署条目](remote-projects-support.html#deployment-entry)。

## See also

### 操作指南

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

### 流程

[Docker plugin](docker.html)

### 外部链接

[Watch Docker Toolchain in Action](https://blog.jetbrains.com/clion/2021/12/docker-toolchain/)

