# 教程：开发容器入门

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

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

## 开始之前

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

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

* 本地项目已在 IntelliJ IDEA 中打开。

有关包括远程开发容器在内的完整要求列表，请参阅 [前提](prerequisites-for-dev-containers.html)。

## 步骤 1。 准备项目

由于  `devcontainer.json`  是构建开发容器所需的配置文件，因此它应存在于项目中。 该文件位于项目根目录中的  `.devcontainer`  文件夹内；中间可能还有其他文件夹，例如  `.devcontainer/.../.../devcontainer.json` 。

要快速开始创建开发容器，有两个选项：创建简单文件，或使用 IDE 内功能从模板创建配置文件。

创建简单配置文件:

开发容器的最低要求是提供用于构建它的镜像。

Procedure:

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

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

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

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

```

从模板创建项目:

Procedure:

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

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

点击   OK   以创建一个相对简单 (但注释很多) 的  `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。 准备构建过程

构建开发容器之前，请考虑要使用哪种开发容器实现：

* 对于远程开发旧版实现，请确保 设置 | 高级设置 中的 原生打开 devcontainer 项目 选项已禁用。

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

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

Procedure: 为开发容器选择特定的 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)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `高级设置` 。

2. 在右侧的选项中，在   Dev Container   部分下禁用   自动选择后端版本  ，然后点击   OK   保存更改。

3. 禁用此选项后，构建开发容器后将提供多个后端版本。

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

Procedure: 手动下载 IDE 后端

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

2. 选择   Unix / Linux   作为操作系统，因为开发容器目前仅支持基于 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` (Visual Studio), `Shift` (Visual Studio (macOS)), `Shift` (NetBeans), `Shift` (Eclipse), `Shift` (Eclipse (macOS)) 以打开搜索窗口。

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

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

7. 重启 IDE。

8. 启用注册表密钥后，开始开发容器构建。

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

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

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

12. 继续开发容器构建过程。

## 步骤 3。 启动开发容器构建

Procedure:

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

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

3. 根据所选实现 (远程开发与原生模式)，以下流程会略有不同。

使用远程开发时:

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

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

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

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

使用原生模式时:

由于没有后端部署步骤，开发容器项目将立即在 IDE 中打开。 如果   设置 | 外观 & 行为 | 系统设置   中的   在 中打开项目   选项设置为   询问  ，项目将在确认后打开。

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

![开发容器微件](https://resources.jetbrains.com.cn/help/img/idea/2026.3/devcontainer_widget.png)

