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

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

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

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

在开发工具左侧打开 Compose 项目，进入“Compose 项目 > compose.yaml > 构建设置”，选择服务 web。依次核对 Context、Dockerfile、cache_from 和 cache_to 四个字段。Compose 的相对路径是以 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、锁文件和层顺序。

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

常见问题

为什么只改了源码，依赖安装也重跑了？

通常是 Dockerfile 先复制了整个构建上下文，或者依赖清单与源码没有分层。把 package.json、锁文件和 RUN npm ci 放到源码复制之前。

cache_from 写了镜像名就一定会命中吗？

不一定。它只是缓存解析来源；来源中必须存在与当前指令和输入匹配的层，且构建环境要能访问该来源。

.dockerignore 会影响缓存吗？

会。它改变发送给构建器的 Context 文件集合，可能让 COPY 的输入发生变化，也可能排除原本不该影响构建的日志和产物。

什么时候应该使用 no-cache？

适合验证依赖安装或基础镜像是否需要重新执行，也适合处理明确要求完全重建的场景。日常排障先定位第一个失效层，再决定是否临时禁用缓存。