---
url: /zh/workspaces/custom-dev-env.md
description: |
  介绍如何通过指定 Docker 镜像或自定义 Dockerfile 来配置云原生开发环境， 包括单容器和双容器两种启动模式。
---
## 通过 Docker 镜像指定开发环境

在 `.cnb.yml` 中编写云原生开发事件流水线，通过 `docker.image` 指定开发环境。

如果指定镜像中已安装 code-server，将使用**单容器模式**启动；未安装则使用**双容器模式**。

指定开发环境镜像有两种方式，按需选择：

### 使用已有镜像（image）

```yaml title=".cnb.yml"
$: # 兜底匹配所有分支，不被 glob 匹配的分支
  vscode:
    - docker:
        image: cnbcool/default-dev-env:latest
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al
```

### 通过 Dockerfile 构建（build）

```yaml title=".cnb.yml"
$: # 兜底匹配所有分支，不被 glob 匹配的分支
  vscode:
    - docker:
        # 使用仓库根目录的 .ide/Dockerfile 构建镜像
        build: .ide/Dockerfile
        # image 作为构建失败时的回退镜像（可选）
        image: cnbcool/default-dev-env:latest
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al
```

* `image`：直接使用已有镜像（适用于预置镜像场景）
* `build`：通过 Dockerfile 自定义构建（与 `image` 二选一，也可同时指定 `image` 作为回退镜像）

## 通过 Dockerfile 自定义开发环境

如果指定镜像无法满足需求，可在仓库根目录创建 `.ide/Dockerfile` 来自定义开发环境。

未自定义启动流水线时，系统会优先使用 `.ide/Dockerfile` 构建镜像作为基础镜像。
如果 `.ide/Dockerfile` 不存在或构建失败，会回退使用默认镜像。

```dockerfile
# .ide/Dockerfile

# 可将 node 替换为需要的基础镜像
FROM node:20

# 安装 code-server 和常用 vscode 插件
RUN curl -fsSL https://code-server.dev/install.sh | sh \
  && code-server --install-extension cnbcool.cnb-welcome \
  && code-server --install-extension redhat.vscode-yaml \
  && code-server --install-extension dbaeumer.vscode-eslint \
  && code-server --install-extension mhutchie.git-graph \
  && echo done

# 安装 CodeBuddy Code（提供 codebuddy 命令），用于在浏览器中使用 CodeBuddy Web
# 需确保版本 >= 2.137.0，详见「CodeBuddy Web」文档
RUN npm install -g @tencent-ai/codebuddy-code

# 安装 ssh 服务，用于支持 VSCode 等客户端通过 Remote-SSH 访问开发环境（也可按需安装其他软件）
RUN apt-get update && apt-get install -y git wget unzip openssh-server

# 指定字符集支持命令行输入中文（根据需要选择字符集）
ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8
```

## 同时自定义开发环境和启动流程

如需同时自定义开发环境和启动流程，可编写 `.ide/Dockerfile` 和 `.cnb.yml`。
Dockerfile 内容与上文相同，不再重复。

`.cnb.yml` 中启用 `build: .ide/Dockerfile`（参考上方「通过 Dockerfile 构建」示例），
并可同时指定 `image` 作为回退镜像。完整写法如下：

```yaml title=".cnb.yml"
$: # 兜底匹配所有分支，不被 glob 匹配的分支
  vscode:
    - docker:
        build: .ide/Dockerfile
        image: cnbcool/default-dev-env:latest
      services:
        - vscode
        - docker
      stages:
        - name: install deps
          script: npm install
        - name: dev
          script: npm run dev
```