使用COPY --chmod时修改源文件权限为何导致Docker构建缓存失效

核心原因 #

Docker 对 COPY 指令的缓存匹配规则，是基于本地源文件的原始元数据 + COPY 指令本身的参数计算缓存键，而非基于复制到镜像后的最终文件状态判断。

具体规则说明 #

• 每次执行 COPY 指令前，Docker 会先计算待复制本地文件的组合校验值：包含文件内容哈希、文件原始权限位两个核心维度
• 再将上述校验值和 COPY 指令的所有参数（如本场景中的 --chmod=755）合并，生成当前构建层的唯一缓存键
• 只有新生成的缓存键和历史构建的缓存键完全一致时，才会命中缓存复用历史层

本场景失效逻辑 #

你修改了本地 hello.txt 的权限从 644 变为 777 后，虽然 COPY --chmod=755 会在复制时强制将镜像内的文件权限覆盖为755，最终镜像内的文件内容、权限都和之前的构建结果完全一致，但：

本地源文件的原始权限已经发生变化，导致第一步计算的源文件校验值发生变更，最终生成的缓存键和历史缓存不匹配，因此无法复用之前的构建缓存。

设计逻辑说明 #

Docker 采用该规则而非提前计算复制后文件状态做缓存匹配，是为了控制构建开销：如果要提前模拟所有 COPY 参数（--chmod/--chown等）的执行结果生成校验值，当待复制文件数量多、体积大时，会大幅提升构建前的预处理耗时，反而降低常规场景下的构建效率。 #

内容的提问来源于stack exchange，提问作者Pierre