docker:cache

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

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

使用场景：构建频繁下载依赖、想加速流水线时使用——例如把依赖安装步骤固化成 缓存镜像，后续构建直接复用，省去重复下载的时间。 缓存需要与镜像构建、依赖清单联动，写脚本成本较高，docker:cache 把这一步收敛成一个内置任务。

• 适用事件
• 参数
• 输出结果
• 配置样例

适用事件

所有事件

参数

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

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

各参数详细说明如下。

dockerfile

• type: String
• required: true

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

为避免构建耗时过长，Docker 镜像构建超时时间受 job.timeout 参数控制。

by

• type: Array<String> | String
• required: false

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

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

• 支持数组格式
• 支持字符串格式，多个文件用英文逗号分隔。
• 支持目录，会递归复制进构建上下文。

versionBy

• type: Array<String> | String
• required: false

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

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

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

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

buildArgs

• type: Object
• required: false

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

target

• type: String
• required: false

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

sync

• type: Boolean
• required: false
• default: false

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

ignoreBuildArgsInVersion

• type: Boolean
• required: false
• default: false

版本计算是否忽略 buildArgs。

参见 版本控制

输出结果

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

配置样例

.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，示例：

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

# 设置工作目录
WORKDIR /space

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

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

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