Docker Build 怎么用缓存挂载加速依赖安装

Docker Build 的缓存挂载适合解决“Dockerfile 这一层必须重建，但包管理器不该重新下载全部依赖”的问题。做法是在 RUN 指令中加入 --mount=type=cache，把 npm 的下载缓存放到 BuildKit 管理的持久目录；镜像层失效后，安装命令仍可复用已下载的包。

官方说明：https://docs.docker.com/build/cache/optimize/

缓存挂载不等于把 node_modules 永久塞进镜像层。它保存的是包管理器缓存目录；依赖清单变化时安装步骤仍会执行，但只需下载新增或变化的包。

一、先拆开依赖层和源码层

打开项目根目录的 Dockerfile，先复制 package.json 与锁文件，完成依赖安装后再复制其余源码。这样普通源码修改不会先让依赖清单层失效。

# syntax=docker/dockerfile:1
FROM node:22-alpine
WORKDIR /app

# 先复制依赖清单，让依赖层只受清单变化影响
COPY package.json package-lock.json ./

# 下一步会在这里添加 npm 缓存挂载
RUN npm ci

# 业务源码变化时，不必让前面的清单复制失效
COPY . .
CMD ["node", "server.js"]

路径：项目根目录 → Dockerfile → 依赖清单复制段。成功状态是 COPY package.json package-lock.json ./ 位于 COPY . . 之前。

二、给 npm 安装步骤添加 cache mount

把原来的 RUN npm ci 改成带缓存挂载的写法。target 必须指向包管理器实际使用的缓存目录；npm 的官方示例使用 /root/.npm。

# 把 npm 下载缓存交给 BuildKit 跨构建保存
RUN --mount=type=cache,target=/root/.npm \
    npm ci

路径：Dockerfile → RUN npm ci → 在命令前加入 --mount=type=cache,target=/root/.npm。这里缓存的是下载内容，不会自动把主机目录复制进最终镜像。

三、构建两次并核对缓存使用

保存 Dockerfile 后执行一次构建，再只修改业务源码并重新构建。命令中的标签可以替换为自己的镜像名：

# 第一次构建用于创建镜像层和 npm 缓存
docker buildx build --load -t demo-cache:latest .

# 修改普通源码后再次构建，观察依赖下载缓存是否被复用
docker buildx build --load -t demo-cache:latest .

然后打开 Docker Desktop，进入 Builds → Build history → 选择刚完成的构建 → Info。在 Build timing 区域查看 Cache usage；也可以切换到 Logs，确认依赖安装步骤没有重新下载全部包。

只有 BuildKit 驱动的构建会出现在 Builds 视图。若列表里没有记录，先确认当前 builder 正在运行，并且命令使用的是 Buildx/BuildKit 路径。

四、按包管理器调整 target

缓存挂载属于当前 builder 的缓存存储。更换 builder 或在临时 CI 机器上构建时，默认不会自动共享；这类场景要另行配置外部缓存，而不是继续扩大本地 mount。

相关问题

为什么加了 cache mount，RUN npm ci 仍然执行？

这是正常的。cache mount 复用的是 npm 下载缓存，不是跳过整个 RUN 层；依赖清单变化后命令会重新运行，但已存在的包可直接复用。

可以把 target 写成项目里的 node_modules 吗？

不建议把两者混为一谈。npm 缓存目录负责复用下载内容，node_modules 是安装结果；两者的生命周期和最终镜像需求不同。