kaniko cache repo 写入失败、tag 命名冲突、env/arg 使用不当及 --snapshotmode=full 配置错误，均会导致镜像层 hash 不一致；应确保 cache repo 可写、使用唯一 tag、合理声明 env/arg 并慎用 --snapshotmode=full。
cache repo 写入失败导致镜像层 hash 不一致
kaniko 用 cache repo 加速构建时，如果 push 权限不足、网络中断或 registry 返回非 200 响应，它不会报错退出，而是静默跳过缓存写入。下次构建时，本该复用的 layer 缺失，kaniko 只能重新计算 —— 结果就是相同 Dockerfile 产出不同 digest 的镜像。
- 检查
cache repo是否可写：手动docker push一个测试镜像到同一地址，确认凭据和权限无误 - 启用 debug 日志：加
--verbosity=debug，搜索pushing cache image和error pushing cache行 - 避免用
gcr.io或quay.io等不支持 OCI blob mount 的 registry 做 cache repo，它们对POST /v2/.../blobs/uploads/的响应可能触发 fallback 到 full upload，间接破坏一致性
--snapshotMode=full 下的文件系统扫描开销与 cache 失效风险
--snapshotMode=full 强制 kaniko 对每个 RUN 指令后整个 rootfs 做递归 stat + hash，不依赖 overlayfs 或 inotify。这会让 cache repo 的命中率变高（因为 snapshot 更稳定），但代价是每次构建都多出大量 I/O 和 CPU 计算 —— 尤其当 WORKDIR 下有大量小文件（如 node_modules、target/）时，hash 耗时可能翻倍，且容易因文件 mtime 或 nanosecond 精度差异导致误判为“变更”。
- 仅在必须规避 overlayfs 不一致（如某些容器运行时）或调试 cache 命中问题时启用
--snapshotMode=full - 搭配
--ignore-path过滤掉已知易变目录：--ignore-path=/workspace/node_modules --ignore-path=/workspace/target - 注意：
--ignore-path不影响 cache repo 的写入逻辑，只跳过 snapshot 计算；若忽略路径里有构建产物，仍需确保其生成逻辑幂等
cache repo tag 命名冲突引发的层复用错误
kaniko 默认把 cache 存在 cache-repo:latest，多个分支或 CI job 并发构建时，不同 commit 的 layer 可能被混写进同一个 tag。下一次构建拉取 cache 时，会拿到不属于当前上下文的 layer，造成构建结果不可靠 —— 比如某次构建成功，换了个 Git SHA 后却莫名失败，实际是因为 cache 中混入了旧版本的编译中间产物。
- 强制用 Git SHA 或 build ID 做 cache tag：
--cache-repo=my-registry/cache:abc123 - 不要复用
:latest；即使单流水线也建议用:$(GIT_COMMIT)，避免本地调试污染远程 cache - CI 中若使用自托管 runner，还需确认
/cache目录是否跨 job 隔离；否则本地 cache 文件可能干扰 registry cache 的决策逻辑
Dockerfile 中 ENV 和 ARG 如何影响 cache repo 层哈希
kaniko 把 ENV 和 ARG 视为构建上下文的一部分，只要它们出现在某个 RUN 指令之前，就会参与该指令对应 layer 的 hash 计算。但很多人误以为只有 RUN 才触发 snapshot —— 实际上，ENV FOO=bar 后接 RUN echo $FOO，和 ENV FOO=baz 后同样 RUN，产生的 layer digest 完全不同，哪怕 echo 输出一样。
-
ARG在FROM后、RUN前声明才参与后续 layer hash；放在最后的ARG不影响任何 snapshot -
ENV是持久的，会影响所有后续 RUN；若只是临时变量，优先用RUN FOO=bar command替代ENV - 敏感值（如 token）别用
ENV注入再 RUN，既泄露到镜像层，又让 cache repo 绑定到具体值，破坏可复现性
cache repo 和 --snapshotMode=full 一起用时，最麻烦的不是配置，而是“看起来生效了”的假象：日志显示 cache hit，但镜像 digest 还是变了。这时候得一层层查 registry 里实际存了哪些 blob、对比两次构建的 layer diff，而不是只信 kaniko 的 log 输出。
