Docker Build 缓存挂载怎么复用包管理器下载

Docker Build 反复安装依赖时，最实用的做法不是把 node_modules 复制进镜像，而是在安装依赖的 RUN 指令上挂一个 BuildKit 缓存目录。这样源码变化导致安装步骤重新执行时，npm 仍能从持久化缓存里复用已有压缩包，只下载新增或变化的依赖。

官方地址：https://docs.docker.com/build/cache/optimize/

缓存挂载解决的是“下载慢”，不是“依赖版本不确定”。依赖清单和 lockfile 仍要保留，构建也必须在缓存为空时正常完成。

步骤一：固定 Docker Desktop 的构建入口和项目文件

先准备一个只包含 Dockerfile、package.json、package-lock.json 和源码的项目目录。在 Docker Desktop 中进入 Images → Build，把这个目录填到 Context，选择项目内的 Dockerfile，在 Tag 中填入 cache-demo:local。如果版本界面没有这些字段，使用同一目录执行下面的命令即可，关键是构建必须走 BuildKit。

不要把包管理器缓存目录写进构建上下文，也不要把它 COPY 到最终镜像。缓存挂载只在对应的 RUN 期间出现，命令结束后不会成为镜像层。

步骤二：把包管理器缓存挂到 RUN 指令

以 npm 为例，把依赖清单单独放在源码之前，并把 npm 默认缓存目录挂载到 /root/.npm：

# 固定 BuildKit Dockerfile 语法，启用 RUN --mount 选项
# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim
WORKDIR /app

# 先复制依赖清单，让 lockfile 变化才触发依赖安装层
COPY package*.json ./

# 缓存 npm 下载包；缓存为空时也必须能正常安装
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
    npm ci --prefer-offline

# 源码变化只影响后面的镜像层，不会清空 npm 下载缓存
COPY . .
CMD ["npm", "start"]

target 必须对应包管理器真正使用的目录。id 可以给不同项目拆分缓存；sharing=locked 适合需要独占缓存数据的场景。npm 是否必须加锁要看自己的并发构建方式，但不应把缓存目录当成共享数据库。

在终端中的等价启动命令如下：

# 使用 plain 进度，便于观察安装步骤是否仍在执行
docker buildx build --progress=plain --tag cache-demo:local .

步骤三：从 Docker Desktop 的 Build 详情启动两次构建

第一次在 Build 页面点击 Build，等待镜像标签出现。第一次没有缓存是正常的，重点是确认 npm ci 能完成并生成镜像。然后只修改一个源码文件，再用相同 Context、Dockerfile 和 Tag 构建第二次。

第二次构建中，安装步骤可能仍会执行，因为源码变化使后续层需要重新计算；但包管理器应优先读取缓存，只补齐新增下载。界面中应看到安装阶段完成、cache-demo:local 出现在镜像列表，且最终镜像没有多出一个 npm 缓存目录。

步骤四：按包管理器并发规则确认边界

用这张清单做最后确认：

• 依赖安装命令带有 lockfile，缓存为空时仍能从网络完成安装。
• 改源码后重新构建，复用的是下载内容，不是跳过依赖版本解析。
• 需要多任务并行构建时，按包管理器要求选择 shared、private 或 locked。
• 用 docker buildx build --no-cache --tag cache-demo:local . 做一次冷启动对照，不要把冷启动失败误判为缓存失效。

Docker 文档明确提醒，缓存可能被垃圾回收，也可能被其他构建写入。因此正确的验收标准是“缓存有则更快、缓存无也能成功”，而不是“每次都必须命中同一份缓存”。

常见问题：缓存挂载的三个误区

缓存挂载会把 npm 包带进最终镜像吗？

不会。它只在这条 RUN 指令执行期间挂载；最终镜像是否包含依赖，取决于安装结果和后续镜像层。

为什么第二次构建仍然显示 npm ci？

缓存挂载复用下载内容，不等于把整个 RUN 层标成 CACHED。源码或前置层变化时，命令仍可能执行，只是网络下载减少。

把 target 改成任意空目录可以吗？

不可以。空目录只有在包管理器也使用它时才有意义；先查清 npm、Apt、pip 或 Cargo 的缓存路径，再决定 target 和并发策略。

最终可以用一句话检查配置：RUN 上有正确的 cache mount，依赖清单先于源码复制，缓存为空时构建仍可完成。满足这三点，Docker Build 才是在复用包管理器下载，而不是把一次构建结果藏在缓存里。