---
url: /zh/build/build-env.md
description: 介绍云原生构建中基于 Docker 容器的构建环境配置方式，包括使用现有镜像和动态构建镜像两种方法。
---
## 概述

构建环境定义了任务 (Job) 的运行环境，包含执行构建所需的软件和工具，如 JDK、Node.js、Python 等特定版本。

`云原生构建`采用 Docker 容器作为构建运行时。相比传统虚拟机，Docker 容器启动更快、资源开销更低、
环境一致性更好，是 CI/CD 行业的通行方案。

::: tip 提示
Docker 知识基础有助于您更好地理解和使用 `云原生构建`。
:::

## 配置方式

可通过以下两种方式为流水线配置构建环境：

* **[使用现有镜像 (`image`)](#示例-1使用现有镜像-image)**：直接使用已构建并推送至镜像仓库的现有镜像。
  适用于使用官方镜像或团队内部预置的公共工具镜像。私有镜像需配置镜像仓库认证信息。
* **[动态构建镜像 (`build`)](#示例-2使用-dockerfile-构建镜像-build)**：指定项目中的 Dockerfile 文件，动态构建镜像。
  适用于需要高度自定义环境、安装特定依赖或工具的复杂项目。无特殊权限要求。

### 使用现有镜像 (image)

直接使用已构建并推送至镜像仓库的现有镜像，是最快的方式。

**语法参考**：[`pipeline.docker.image`](./grammar.md#pipeline-image)

### 动态构建镜像 (build)

指定项目中的 `Dockerfile` 文件，在构建开始时动态构建镜像，并用于后续流程。

**工作机制**：

1. 系统计算镜像版本哈希值
2. 若本地缓存或远端仓库中已存在该镜像，则直接使用，以加速构建
3. 否则执行 `docker build` 构建镜像，并自动推送至流水线项目所属制品库，供后续复用

**语法参考**：[`pipeline.docker.build`](./grammar.md#pipeline-build)

### 环境作用范围

流水线级别声明的构建环境将作为其下所有**脚本任务**的默认运行环境。每个**脚本任务**也可单独指定专属的 `image` 环境。

::: warning 注意
任务级仅支持 `image` 配置，不支持 `dockerfile`。
:::

**语法参考**：[脚本任务](./grammar.md#job-script-task) |
[脚本任务 vs 插件任务](./script-vs-plugin.md)

## 示例说明

### 示例 1：使用现有镜像 (image)

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - node -v
```

### 示例 2：使用 Dockerfile 构建镜像 (build)

**步骤 1**：创建 Dockerfile 文件

```dockerfile title="image/Dockerfile"
FROM node:20
```

**步骤 2**：配置流水线使用该 Dockerfile

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        build: image/Dockerfile
      stages:
        - node -v
```

### 示例 3：任务级别覆盖构建环境 + 缺省镜像

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - node -v
        - name: 使用特定镜像版本
          image: node:20
          script:
            - node -v
```

### 示例 4：使用缺省镜像

当流水线未显式指定 `image` 或 `build` 配置时，系统会自动使用缺省镜像，确保基础环境可用。

| 构建类型   | 缺省镜像变量                                |
|------------|---------------------------------------------|
| 云原生构建 | `cnbcool/default-build-env`           |
| 云原生开发 | `cnbcool/default-dev-env`       |

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - stage1
        - stage2
# 未指定环境时，等价于使用 cnbcool/default-build-env
```

云原生开发也类似，未声明镜像时使用默认开发镜像：

```yaml title=".cnb.yml"
$:
  vscode:
    - services:
        - vscode
      stages:
        - stage1
# 未指定环境时，等价于使用 cnbcool/default-dev-env
```

## Volume 共享

如果您的自定义镜像通过 `VOLUME` 指令声明了数据卷（例如：`VOLUME /cache`），
这些卷会被自动共享给后续由**插件任务**启动的容器。

### 应用场景示例

**步骤 1**：在 Dockerfile 中准备共享数据

```dockerfile
FROM alpine
RUN mkdir /cache && echo 'Initial data' > /cache/data.txt
VOLUME /cache
```

**步骤 2**：在后续任务中访问共享数据

```yaml
- name: 读取共享卷中的数据
  image: alpine
  script:
    - cat /cache/data.txt
```

::: tip 提示
Volume 共享机制允许不同镜像的任务之间共享数据，适合缓存依赖、共享构建产物等场景。
:::