---
url: /zh/build/pipeline-cache.md
description: |
  介绍云原生构建流水线的缓存机制， 包括节点缓存（代码缓存、文件缓存）和跨节点缓存的配置与使用方法。
---
流水线构建过程中通常会产生大量依赖和中间产物，
缓存这些产物供后续流水线复用，可有效缩短构建时间。

## 节点缓存

:::tip
节点分配并非永久固定——平台扩缩容时可能发生变化。
:::

为在单点故障风险与缓存命中率之间取得平衡，
流水线默认分配到 3 个构建节点（节点数随资源使用情况动态调整）。

### 代码缓存

流水线执行时会自动拉取代码到构建节点，
并缓存代码供后续流水线复用。

### 文件缓存

构建过程中产生的项目依赖、构建缓存等文件可缓存到构建节点，
供后续流水线复用。

通过 [`docker.volumes`](./grammar.md#pipeline-volumes) 声明缓存目录即可。
以下示例将 npm 依赖目录缓存到构建节点，后续构建可直接复用，无需重复下载：

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:20
        volumes:
          - /root/.npm:copy-on-write # 缓存 npm 依赖，供后续流水线复用
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test
```

* `copy-on-write`：基于 OverlayFS 的缓存即时复制技术，可在高并发下复用缓存。
* 数据卷的类型与更多格式见[语法手册](./grammar.md#pipeline-volumes)。

## 跨节点缓存

节点缓存在当前构建节点内有效。若需在所有节点共享同一份缓存，
可将需要缓存的内容构建为 Docker 镜像，实现跨节点共享。

具体方法参考内置任务：[docker:cache](./internal-steps/docker/cache.md)