---
url: /zh/build/internal-steps/docker/cache.md
---
`docker:cache`

\==Docker 缓存==，将 Docker 镜像构建为缓存，供后续构建复用。

避免 `依赖包` 等网络资源被重复下载。

* [适用事件](#docker-cache-applicable-events)
* [参数](#docker-cache-parameters)
* [输出结果](#docker-cache-output)
* [配置样例](#docker-cache-configuration-examples)

## 适用事件 {#docker-cache-applicable-events}

[所有事件](../../trigger-rule.md#trigger-event)

## 参数 {#docker-cache-parameters}

以下列表先概览全部参数，再点进对应小节看细节。

* [dockerfile](#docker-cache-parameters-dockerfile)：构建缓存镜像所用的 Dockerfile 路径
* [by](#docker-cache-parameters-by)：缓存镜像构建所依赖的文件列表，用于触发缓存重建
* [versionBy](#docker-cache-parameters-versionBy)：参与缓存版本计算的文件，默认取 `by`
* [buildArgs](#docker-cache-parameters-buildArgs)：构建时注入的额外 `--build-arg` 参数
* [target](#docker-cache-parameters-target)：对应 `docker build --target`，只构建指定阶段
* [sync](#docker-cache-parameters-sync)：是否同步模式，等待缓存镜像 push 成功后再继续
* [ignoreBuildArgsInVersion](#docker-cache-parameters-ignoreBuildArgsInVersion)：版本计算是否忽略 `buildArgs`

各参数详细说明如下。

### dockerfile {#docker-cache-parameters-dockerfile}

* type: `String`
* required: `true`

用于构建缓存镜像的 Dockerfile 路径。

为避免构建耗时过长，Docker 镜像构建超时时间受
[job.timeout](../../grammar.md#job-timeout) 参数控制。

### by {#docker-cache-parameters-by}

* type: `Array<String>` | `String`
* required: `false`

声明缓存镜像构建过程中依赖的文件列表。

Docker 构建上下文（`docker build` 时能看到的文件）里只包含 Dockerfile
和 `by` 声明的这些文件。若缓存镜像构建还需要其他文件，须一并写入 `by`，
否则它们不会被复制进构建上下文，等同于在构建时不可用。

* 支持数组格式
* 支持字符串格式，多个文件用英文逗号分隔。

### versionBy {#docker-cache-parameters-versionBy}

* type: `Array<String>` | `String`
* required: `false`

用于版本控制。未传入 `versionBy` 时，默认取 `by` 的值。

当 `versionBy` 指向的文件内容发生变化时，会视为一个新版本，
具体的计算逻辑见这个表达式：

`sha1(Dockerfile + versionBy + buildArgs + target + arch)`

* 支持数组格式。
* 支持字符串格式，多个文件用英文逗号分隔。

### buildArgs {#docker-cache-parameters-buildArgs}

* type: `Object`
* required: `false`

在 build 时插入额外的构建参数 (`--build-arg $key=$value`)，
value 为 null 时只传入 key (`--build-arg $key`)。

### target {#docker-cache-parameters-target}

* type: `String`
* required: `false`

对应 docker build 的 --target 参数，
可选择性地构建 Dockerfile 中的特定阶段，而非构建整个 Dockerfile。

### sync {#docker-cache-parameters-sync}

* type: `Boolean`
* required: `false`
* default: `false`

是否同步模式，`true` 时会等待缓存镜像 push 成功后再继续后续任务。

### ignoreBuildArgsInVersion {#docker-cache-parameters-ignoreBuildArgsInVersion}

* type: `Boolean`
* required: `false`
* default: `false`

版本计算是否忽略 `buildArgs`。

参见 [版本控制](#docker-cache-parameters-versionBy)

## 输出结果 {#docker-cache-output}

```javascript
{
  // 缓存对应的 docker image name
  name;
}
```

## 配置样例 {#docker-cache-configuration-examples}

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            # by 支持以下两种形式：数组、字符串
            by:
              - package.json
              - package-lock.json
            # versionBy: package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          # 将 cache 中的文件拷贝过来使用
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: build with cache
          script:
            - npm run build
```

其中 cache.dockerfile 是一个用于构建缓存镜像的 Dockerfile，示例：

```dockerfile
# 选择一个 Base 镜像
FROM node:14

# 设置工作目录
WORKDIR /space

# 将 by 中的文件列表 COPY 过来
COPY . .

# 根据 COPY 过来的文件进行依赖的安装
RUN npm ci

# 设置好需要的环境变量
ENV NODE_PATH=/space/node_modules
```