本文摘要改一行业务代码就触发依赖重装本地与 CI 构建都要等上数分钟。把依赖清单 COPY 提前并缩小输入集缓存只在依赖清单变动时才失效。该做法只对依赖清单稳定的项目有效依赖频繁变动时收益有限。一、问题与结论一个 FastAPI 后端的Dockerfile长这样在app/main.py里加一行注释后docker build会重跑完整的pip installFROM python:3.12-slim WORKDIR /srv COPY . . RUN pip install --no-cache-dir -r requirements.txt CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]CI 上更明显runner 通常没有本地构建缓存每次发版都跑完整安装。换--no-cache-dir、加内存、改基础镜像都不解决问题因为根因不在安装速度而在层的输入。需要验证的结论有两条COPY的缓存判定看的是被复制文件的内容某层失效后其后所有指令全部重建COPY . .等于把整个构建上下文接到pip install上。顺序只是必要条件缓存键的真实边界是COPY的输入集输入集里混进每次都变的文件层序排得再对也会失效。本文优化的是构建耗时与服务运行时性能无关。标题里的 6 分钟 / 40 秒是典型场景的目标量级不是本次实测值可复现的测量方法见第四节。二、排查与选择依据先定位失效层再改Dockerfile用--progressplain读CACHED标记、用time取耗时、用docker history看层的顺序三者交叉就能确定哪一层被重建而不是凭感觉调顺序。缓存判定对ADD与COPY构建器比较被复制文件内容的校验和与上一次构建对RUN等指令只看指令串与父层状态不看容器内文件一旦某层失效其后所有指令都生成新层。BuildKit 与 legacy builder 都做内容级判定但对文件元数据、权限的敏感度存在实现差异需在目标版本核对。排查命令dockerbuildx versiontimedockerbuild --no-cache-tcache-demo:v1.echo# changeapp/main.pytimedockerbuild--progressplain-tcache-demo:v2.dockerhistory--no-trunc cache-demo:v2|head-n8与指令顺序无关的补充手段均要求 BuildKitRUN --mounttypecache把 pip 下载缓存摘出代码依赖链COPY --link把复制构造成独立层不随父层变化连锁重建--cache-to/--cache-from面向没有本地缓存的 CI runner。写上# syntaxdocker/dockerfile:1可统一语法前端但离线构建机可能解析失败需自备语法镜像或退回引擎自带前端。替代方案与取舍方案做法选择条件代价 / 边界裁剪构建上下文精写.dockerignore排除.git、.venv、测试产物任何项目改动最小只缩小输入集不解决依赖安装排在代码复制之后的问题预构建依赖基础镜像自维护base-python-deps业务镜像只FROMCOPY app/依赖稳定、多服务共用一套依赖多一个镜像要升级存在版本漂移与发布顺序约束离线 wheel 目录pip download出 wheelpip install --no-index --find-links内网、离线构建wheel 目录成为构建输入需要版本管理CI 远程缓存--cache-to/--cache-from指向 registry 或本地目录runner 无本地构建缓存registry 占用、ref 生命周期管理cache mount 内容是否随导出需实测换构建器buildah --layers、podman build、kaniko --cache --cache-repoK8s 内构建、无 daemon 环境缓存语义各不相同BuildKit 前端特性--link、--mounttypecache不可直接移植不该用本文分层做法的场景每次构建都改requirements.txt构建上下文无法裁剪CI 每个 job 新建 builder 且不配远程缓存。缓存只能避免重复劳动首次构建与依赖变更仍需全量安装--no-cache应定期用于验证干净构建能否成功。三、关键原理输入集决定缓存键。把依赖复制写成COPY requirements*.txt ./看似省事某天目录里新增requirements-doc.txt匹配集合变化pip install无端重跑开发者会误以为我没动依赖。依赖清单用精确文件名开发依赖与运行时依赖拆到不同阶段让运行时镜像的输入集固定为单个文件。cache mount 活在 builder 实例里。RUN --mounttypecache的持久化粒度是 builder 实例的本地存储不是镜像层、也不是 registry。CI 每个 job 新建 builder 时它是空的期望的pip 提速可能完全不发生cache mount 内容是否随--cache-to导出需以 BuildKit 文档或实测为准。缓存不能替代干净构建。缓存命中不代表产物正确--no-cache仍是验证干净构建能否成功的必要手段首次构建、依赖变更、基础镜像升级都必须全量安装。四、可运行示例环境Docker Engine 且构建器为 BuildKitdocker buildx version能打印版本即满足。项目结构fastapi-cache-demo/ ├── app/ │ └── main.py ├── requirements.txt ├── Dockerfile └── .dockerignorerequirements.txt示例不锁版本以便复现生产项目应使用锁文件fastapi uvicorn[standard]A 组是第一节的坏写法B 组的完整Dockerfile# syntaxdocker/dockerfile:1 FROM python:3.12-slim WORKDIR /srv COPY requirements.txt ./ RUN --mounttypecache,target/root/.cache/pip \ pip install -r requirements.txt COPY app/ ./app/ CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]需要时可给COPY app/ ./app/加--link让代码层不因父层变化连锁重建。操作按第二节命令执行先 A 组后 B 组每组冷构建一次、改一次app/main.py再热构建一次。预期输出B 组热构建中COPY requirements.txt ./与pip install -r requirements.txt两行前出现CACHED标记time的 real 明显低于 A 组docker history里依赖层的创建时间早于代码层形如时间 COPY requirements.txt ./ # 早于代码改动 时间 RUN pip install ... # 早于代码改动 时间 COPY app/ ./app/ # 随最新改动刷新实际输出在目标机器把两组各跑 3 次取time输出 real 的中位数再用--progressplain与docker history --no-trunc核对层是否复用。标题中的 6 分钟 / 40 秒为量级目标、本次未实测实际倍率取决于依赖数量、网络、磁盘与 builder 实例。失败一输入集比想象中大。依赖复制写成COPY requirements*.txt ./目录新增一个requirements-doc.txt后缓存失效、pip install重跑。修复改用精确文件名或把开发依赖拆到独立阶段。失败二# syntax在内网解析失败。离线构建机无法拉取docker/dockerfile:1前端解析报错构建直接失败。修复内网预先准备语法镜像或退回引擎自带前端此时COPY --link等新特性可能不可用。失败三本地提速、CI 不提速。cache mount 保存在 builder 实例本地存储每个 job 新建 builder 时它是空的。修复配置--cache-to/--cache-from并把缓存是否跨 job 保留作为验收项单独验证。五、验证结果与边界构建耗时对比按下表记录数值请在目标机器实测后填写本文不给未经测量的倍率构建动作A 组COPY . .B 组依赖层拆分判定方式冷构建全量安装全量安装time中位数只改app/main.pypip install重跑依赖层CACHED--progressplain改requirements.txt重跑重跑同上适用边界依赖清单稳定、业务代码高频改动的后端服务收益最大依赖清单每次构建都变、或 CI 每 job 新建 builder 且无远程缓存时分层几乎不省时间。构建器若不是 BuildKit--mounttypecache、COPY --link与 cache backend 都不可用此时只剩缩小输入集与调整层序两种手段。参考资料Docker Build 缓存机制与缓存失效规则Dockerfile 最佳实践利用构建缓存与依赖分层Dockerfile reference