为何Docker构建中COPY缓存生效但RUN pnpm fetch缓存失效？

问题背景 #

Dockerfile中执行COPY --from=builder /srv/pnpm-lock.yaml .已命中缓存，但后续的RUN pnpm fetch --production却未复用缓存，需要分析具体原因。

相关Dockerfile片段 #

COPY --from=builder /srv/pnpm-lock.yaml .
RUN pnpm fetch --production

构建日志 #

#21 [runner 6/9] COPY --from=builder /srv/pnpm-lock.yaml .
#21 CACHED

#22 [runner 7/9] RUN pnpm fetch --production
#22 sha256:30f9f1937ac26c0bee1bf1f43bc2cdf011b7dbe3274259fa3a38207eb7c134d8 3.23kB / ...
#22 sha256:9515600f9c042af6514cc6ee2a695846114c98f7ccb408866f8c0335b3ad8249 278.35MB / 278.35MB 2.1s done
#22 DONE 2.2s

构建命令 #

docker buildx build \
  --progress plain \
  --file apps/contra-api/Dockerfile \
  --push \
  --tag redacted/contrawork/contra-api/review:cd6b0550 \
  --cache-to type=registry,ref=redacted/contrawork/contra-api/review:cd6b0550-build-cache,mode=max,compression=zstd \
  --cache-from type=registry,ref=redacted/contrawork/contra-api/review:cd6b0550-build-cache \
  --cache-to type=registry,ref=redacted/contrawork/contra-api/review:latest_review-build-cache,mode=max,compression=zstd \
  --cache-from type=registry,ref=redacted/contrawork/contra-api/review:latest_review-build-cache \
  --build-arg RELEASE_VERSION=cd6b0550 \
  --secret id=env,src=/home/github/actions-runner/_work/gaia/gaia/.env .

可能的失效原因 #

• builder阶段存在未追踪的环境变更
  虽然COPY步骤显示已缓存，但--from=builder引用的builder镜像可能存在隐性变化：比如pnpm版本更新、npm源配置修改、镜像内的pnpm缓存目录变更等。这些变更不会体现在pnpm-lock.yaml内容上，但会改变后续RUN步骤的执行环境，导致Docker计算的缓存哈希不匹配。

• 构建参数或secret的间接影响
  构建命令中使用的RELEASE_VERSION构建参数和--secret可能触发缓存失效：

  • 若Dockerfile中在当前RUN步骤前有使用RELEASE_VERSION的指令（比如写入版本信息到镜像内文件），会改变该步骤之前的镜像层哈希，导致后续RUN步骤的缓存依赖链断裂。
  • 部分场景下，--secret的存在或其引用路径的变化，会导致Docker重新计算RUN步骤的缓存键，无法命中旧缓存。

• Registry缓存的一致性问题
  使用registry作为缓存存储时，可能出现以下情况：

  • 之前的构建未将RUN pnpm fetch对应的层完整推送到registry缓存中。
  • 多平台构建场景下，当前构建的平台与缓存中存储的平台不匹配，导致缓存无法复用。
  • 缓存引用的latest_review-build-cache标签被新构建覆盖，旧的RUN步骤缓存层已被替换。

• pnpm自身配置的变化
  pnpm fetch --production的执行结果不仅依赖pnpm-lock.yaml，还受镜像内的pnpm配置（如.npmrc、全局pnpm设置）影响。如果这些配置在builder阶段或基础镜像中发生变更（比如镜像源切换），即使pnpm-lock.yaml未变，fetch的结果也会不同，导致Docker无法复用旧缓存层。

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