# 教程：Dev Containers 入门

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

在本教程中，将为本地项目创建 Dev Container 配置，构建容器，并在其中打开项目。 最后，将获得一个正在运行的容器，以及一个连接到该容器的 IDE 窗口。

## 在开始之前

* [Docker](https://docs.docker.com/install/) 已安装在计算机上，并且 Docker 守护程序正在运行。 CLion 通过 Docker 构建容器，因此如果守护程序已停止，构建将失败。

* [Docker 插件](docker.html)已安装并启用。

* 本地项目已在 CLion 中打开。

有关包括远程 Dev Containers 在内的完整要求列表，请参阅 [先决条件](prerequisites-for-dev-containers.html)。

## 步骤 1。 准备项目

由于  `devcontainer.json`  是构建 Dev Containers 所必需的配置文件，因此项目中应存在该文件。 该文件放置在项目根目录下的  `.devcontainer`  文件夹中；中间可能还有其他文件夹，例如  `.devcontainer/.../.../devcontainer.json` 。

有两个选项可快速开始创建 Dev Containers：创建一个简单文件，或使用 IDE 内功能从模板创建配置文件。

创建简单的配置文件:

Dev Container 的最低要求是用于构建它的镜像。

Procedure:

1. 在项目视图中，右键点击项目名称并选择   新建文件  。

2. 输入  `.devcontainer/devcontainer.json`  以在项目根目录下的  `.devcontainer`  目录中创建配置。

3. 在编辑器中打开文件并添加以下代码：

```JSON
{
    image: "ubuntu:latest"
}

```

从模板创建项目:

Procedure:

1. 在项目视图中，右键点击项目名称并选择   新建 | Dev Container 配置  。

2. 在打开的对话框中，CLion 会显示默认容器配置。 默认模板足以创建 Dev Container，但如有必要，也可以从   开发容器模板   下拉列表中选择任何其他特定于语言的模板。

点击   确定   以创建一个相对简单（但注释很多）的  `devcontainer.json` ：

```JSON
// Default Ubuntu-based DevContainer Template.
// For more customization options, see https://containers.dev/implementors/json_reference
{
    name: "Default",
    image: "ubuntu:latest",

    customizations : {
        // Configure JetBrains IDE-specific properties
        jetbrains : {
            backend : "IntelliJ",
            settings : {
                // IDE settings can be added via “Show context actions”|“Add currently modified settings from IDE”.
                // A complete list of supported settings is also available through auto-completion
            },
            plugins: [
                // A set of plugin IDs.
                // Plugin ID can be found on the corresponding plugin’s page at https://plugins.jetbrains.com.
            ]
        }
    },
    features: {
        "ghcr.io/devcontainers/features/git" : {},
        // Add additional features to your project using auto-completion.
    },
    // Comment out to connect as the root user.
    remoteUser: "ubuntu"
}

```

## 步骤 2。 准备构建流程

在构建 Dev Container 之前，请考虑将使用哪种 Dev Container 实现：

* 对于 Remote Development 旧实现，请确保 原生打开 devcontainer 项目 选项在 设置 | 高级设置 中已禁用。

* 如果使用本机模式实现，请在 设置 | 高级设置 中启用 原生打开 devcontainer 项目 选项。

此外，使用 Remote Development 实现时，建议设置 IDE 以提供扩展的后端选择。

Procedure: 为 Dev Containers 选择特定的 IDE 后端版本

1. 按下 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `高级设置` 。

2. 从右侧的选项中，在   开发容器   部分下，禁用   自动选择后端版本  ，然后点击   确定   保存更改。

3. 禁用此选项后，构建 Dev Container 后将可使用多个后端版本。

要使用自定义远程开发后端（例如，检查未发布的 IDE 构建中的问题），请执行以下操作：

Procedure: 手动下载 IDE 后端

1. 打开 [下载](https://www.jetbrains.com/zh-cn/idea/download/) 页面。

2. 选择   Linux   作为操作系统，因为 Dev Containers 目前仅支持基于 Linux 的镜像。

3. 下载与 Docker 引擎运行所在主机的架构对应的归档文件。

4. 在主菜单中，转到  `导航 | 全局搜索` 或按两次 `Shift` (Windows), `Shift` (macOS), `Shift` (IntelliJ IDEA Classic (macOS)), `Shift` (macOS System Shortcuts), `Shift` (XWin), `Shift` (GNOME), `Shift` (KDE), `Shift` (Emacs), `Shift` (Sublime Text), `Shift` (Sublime Text (macOS)), `Shift` (Xcode), `Shift` (Visual Studio), `Shift` (Visual Studio (macOS)), `Shift` (ReSharper), `Shift` (ReSharper (macOS)), `Shift` (QtCreator), `Shift` (QtCreator (macOS)), `Shift` (NetBeans), `Shift` (Eclipse), `Shift` (Eclipse (macOS))以打开搜索窗口。

5. 键入  `registry`  并选择   注册表……   选项。

6. 在打开的窗口中，搜索  `devcontainers.use.separate.project.panel`  密钥并启用它。 点击   关闭  。

7. 重启 IDE。

8. 启用注册表密钥后，启动 Dev Container 构建。

9. 当   选择 IDE 和项目   窗口打开时，点击   安装选项   链接并选择   上传安装文件   操作。

10. IDE 版本   字段将更改为   选择归档   文件。

11. 指定已下载的 IDE 后端归档文件的路径。

12. 继续 Dev Container 构建过程。

## 步骤 3。 启动 Dev Container 构建

Procedure:

1. 打开  `.devcontainer/devcontainer.json` 。 点击装订区域中的 Dev Containers 图标并选择   创建开发容器并挂载源代码…  。 如果系统提示选择后端 IDE，请选择 CLion。

2. 构建启动后，应会自动打开 Services 视图以显示构建过程：

3. 根据选择的实现（远程开发或原生模式），后续流程会略有不同。

使用远程开发时:

从列表中选择后端版本，并等待它和 Client 下载：

在某些情况下，如果 Dev Container 构建和后端部署过程超过 10 秒，Client 将不会打开；而是会在 IDE 中显示带有   连接   按钮的通知。 按下该按钮。

在以下窗口中按下   信任项目   按钮，并等待 Client 打开：

如何判断已打开的是 Dev Container 中的项目？ 通过左上角的   后端状态详情   微件。

使用原生模式时:

由于没有后端部署步骤，Dev Container 项目将立即在 IDE 中打开。 如果   设置 | 外观与行为 | 系统设置   中的   在以下位置打开项目   选项设置为   请求  ，项目将在确认后打开。

要判断项目是否在使用原生模式的 Dev Container 中打开，请检查不常见的项目根路径，以及编辑器左上角显示 Dev Container 信息的微件。

![Dev_Container_微件](https://resources.jetbrains.com/help/img/idea/2026.3/devcontainer_widget.png)

