当前位置：首页 > 文章列表 > 文章 > 软件教程 > Docker Compose 构建缓存为什么没有命中

Docker Compose 构建缓存为什么没有命中

来源：17golang原创 2026-09-12 14:51:31 0浏览收藏

Docker Compose 构建缓存没有命中，通常不是 Compose “随机失效”，而是构建输入已经变化，或者缓存来源没有接上。先看三处：服务的 context 是否把多余文件送进构建、Dockerfile 是否把易变源码放在依赖安装之前、cache_from 是否能读到上一轮导出的缓存。

官方文档：https://docs.docker.com/compose/

排查要点

缓存命中依赖 Dockerfile 指令和它读取的文件；一个层失效后，后续层通常也会重建。
Compose 的 cache_from 只声明缓存来源，想让下一次构建复用，还要配置 cache_to 导出。
Build 面板里先找第一个非 CACHED 层，不要一上来就使用 --no-cache。

第 1 步：先核对 Compose 的构建入口

在开发工具左侧打开 Compose 项目，进入“Compose 项目 > compose.yaml > 构建设置”，选择服务 web。依次核对 Context、Dockerfile、cache_from 和 cache_to 四个字段。Compose 的相对路径是以 Compose 文件所在目录为基准，Context 指错目录时，即使 Dockerfile 没变，送入构建器的文件集合也可能完全不同。

Docker Compose web 服务构建设置界面示意，显示 Context Dockerfile cache_from 和 cache_to 字段 — 图1：Compose 构建设置入口示意图，先核对服务、Context、Dockerfile 与缓存字段是否指向预期对象。此图为原创界面示意，不是实际软件截图。

如果项目只需要 web/ 目录，Context 不要填仓库根目录。配套的 .dockerignore 也应排除日志、依赖缓存和构建产物，减少不相关文件改变造成的缓存校验变化。

第 2 步：检查 Dockerfile 的层顺序

在“Compose 项目 > web > Dockerfile”打开构建文件，先把变化较少的依赖描述文件复制进去，再执行依赖安装，最后复制经常变化的源码。下面是一个最小示例：

FROM node:22-alpine

WORKDIR /app

# 依赖清单变化少，优先形成可复用层。
COPY package.json package-lock.json ./
RUN npm ci

# 源码变化频繁，放在依赖安装之后减少重建范围。
COPY src ./src
CMD ["node", "src/server.js"]

点击编辑器右上角的“保存”，再回到构建设置。若把整个项目先 COPY . .，任何源码、日志或未被忽略的文件变化都可能让依赖安装层之后的内容重新构建。Docker 对 COPY 和 ADD 会根据相关文件计算缓存校验，文件的修改时间单独变化并不是唯一判断依据。

第 3 步：在 Compose 中接上外部缓存

在“Compose 项目 > compose.yaml > service web > build”字段组中，确认 cache_from 与 cache_to 使用同一个可访问的缓存引用。下面的配置使用 registry 类型作为示例，引用名称只是示意值，请替换为团队实际可读写的地址。

services:
  web:
    build:
      context: ./web
      dockerfile: Dockerfile
      # 从上一轮构建导入缓存层。
      cache_from:
        - type=registry,ref=example/web:buildcache
      # 把本轮新缓存导出，供后续构建读取。
      cache_to:
        - type=registry,ref=example/web:buildcache

保存后检查字段值是否仍在面板中。只写 cache_from 而没有持续导出 cache_to，下一台机器可能没有可用的新缓存；缓存后端不支持或地址不可访问时，Compose 实现也可能忽略该来源并继续构建，因此要把“缓存不可用”和“层本身不匹配”分开判断。

第 4 步：从构建结果确认缓存是否命中

在“Compose 项目 > service web > 构建设置”点击“Build”，打开右侧“Build history”中的最新记录。先找第一条不是 CACHED 的层：如果 COPY package.json 已缓存而 COPY src 显示 REBUILT，说明依赖层复用成功，变化集中在源码层；如果从 RUN npm ci 就开始重建，应回到第 1、2 步检查 Context、锁文件和层顺序。

Docker Compose Build history 构建结果界面示意，区分 CACHED 依赖层和 REBUILT 源码层 — 图2：构建结果面板示意图，CACHED 层与重建层并列显示，可据此定位第一个未命中的 Dockerfile 指令。此图为原创界面示意，不是实际软件截图。

右侧摘要同时确认缓存来源为预期 registry，底部状态显示 Build complete 后再继续启动服务。若只是想验证 Dockerfile 是否能从零构建，可以临时使用 Compose 的“禁用缓存”选项或命令行 --no-cache，但它不能修复缓存配置，验证结束后要恢复正常构建设置。