Docker Buildx CI环境下Build Arg变更未触发缓存失效

环境信息 #

• Docker版本：v27
• Docker Buildx插件版本：v0.16

问题详情 #

在使用构建参数RELEASE设置环境变量的构建层中，未触发缓存失效。预期当RELEASE参数值变更时，以下层级应该触发缓存失效：

ARG RELEASE=dev
ENV EVELIN_RELEASE=${RELEASE}

进而导致后续的RUN npm run build等步骤重新执行，但CI环境中所有构建层都命中了缓存，本地环境行为符合预期（与Docker缓存机制描述一致）。

补充：本地使用与Kubernetes中相同的构建器实例尝试复现，未出现问题。

Dockerfile示例 #

FROM someBaseImage:5.4.0 AS base

# Install dependencies stage
FROM base AS build

COPY --chown=hive:hive package.json package-lock.json .npmrc ./
RUN npm ci --production=false && rm -f .npmrc

COPY --chown=hive:hive src/ src/

ARG RELEASE=dev
ENV EVELIN_RELEASE=${RELEASE}

RUN npm run build

RUN if [ "${NODE_ENV}" = "production" ]; \
    then npm prune --production;  \
    fi

FROM base

COPY --from=build /app /app
COPY --chown=hive:hive .eslintignore .prettierrc.js tsconfig.json ./

CMD ["npm", "run", "dev:server"]

构建命令 #

docker buildx build --progress=plain -f /docker/Dockerfile --build-arg 'RELEASE=09705c14' . --cache-from app:latest --cache-to type=registry,ref=someRepo,mode=min,oci-mediatypes=true,image-manifest=true --push -t app:latest

CI构建日志（关键部分） #

$ docker buildx build ${DOCKER_DIND_BUILDX_ARGS[@]}
docker buildx build --progress=plain -f /docker/Dockerfile --build-arg 'RELEASE=09705c14' . --cache-from app:latest --cache-to type=registry,ref=someRepo,mode=min,oci-mediatypes=true,image-manifest=true --push -t app:latest
#0 building with "kube-new" instance using kubernetes driver
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 778B done
#1 DONE 0.0s
#2 [auth] sharing credentials for someRegistry
#2 DONE 0.0s
#3 [internal] load metadata for someBaseImage:5.4.0
#3 DONE 0.1s
#4 [internal] load .dockerignore
#4 transferring context: 89B done
#4 DONE 0.0s
#5 [internal] load build context
#5 DONE 0.0s
#6 [base 1/1] FROM someBaseImage:5.4.0@sha256:...
#6 resolve someBaseImage:5.4.0@sha256:... 0.0s done
#6 DONE 0.0s
#7 importing cache manifest from app:latest
#7 inferred cache manifest type: application/vnd.oci.image.manifest.v1+json done
#7 DONE 0.3s
#5 [internal] load build context
#5 transferring context: 3.11MB 0.2s done
#5 DONE 0.2s
#8 [build 5/5] RUN if [ "${NODE_ENV}" = "production" ];     then npm prune --production;      fi
#8 CACHED
#9 [stage-2 1/2] COPY --from=build /app /app
#9 CACHED
#10 [build 1/5] COPY --chown=hive:hive package.json package-lock.json .npmrc ./
#10 CACHED
#11 [build 2/5] RUN npm ci --production=false && rm -f .npmrc
#11 CACHED
#12 [build 3/5] COPY --chown=hive:hive src/ src/
#12 CACHED
#13 [build 4/5] RUN npm run build
#13 CACHED
#14 [stage-2 2/2] COPY --chown=hive:hive .eslintignore .prettierrc.js tsconfig.json ./
#14 CACHED
#15 exporting to image
#15 exporting layers done
#15 exporting manifest sha256:... 0.0s done
#15 exporting config sha256:... done
#15 exporting attestation manifest sha256:... 0.0s done
#15 exporting manifest list sha256:... 0.0s done
#15 pushing layers
#15 pushing layers 0.3s done
#15 pushing manifest for app:latest@sha256:...
#15 pushing manifest for app:latest@sha256:... 0.3s done
#15 DONE 1.2s
#16 exporting cache to registry
#16 preparing build cache for export
...
#16 writing cache image manifest sha256:... 0.1s done
#16 DONE 0.5s

可能的原因及解决方案 #

1. 缓存模式配置限制 #

当前使用--cache-to ... mode=min，mode=min仅导出构建结果的缓存，不会包含构建参数相关的元数据，导致后续构建无法识别参数变更。尝试将mode改为max：

--cache-to type=registry,ref=someRepo,mode=max,oci-mediatypes=true,image-manifest=true

mode=max会导出完整的构建缓存元数据，包括构建参数、指令上下文等，确保Buildx能正确对比参数变化。

2. Kubernetes驱动构建器的缓存同步问题 #

CI环境使用Kubernetes驱动的构建器（building with "kube-new" instance using kubernetes driver），可能存在缓存元数据未正确同步或存储的情况。可以尝试：

• 重新创建Buildx构建器实例：

  docker buildx rm kube-new
  docker buildx create --name kube-new --driver kubernetes --driver-opt replicas=1
  

• 检查构建器的缓存存储配置，确保缓存元数据能被正确读取和写入。

3. 构建参数传递异常 #

检查CI环境中${DOCKER_DIND_BUILDX_ARGS[@]}是否包含覆盖RELEASE参数的配置，或者参数传递时出现引号/转义问题。可以在CI中打印完整的构建命令，确认RELEASE参数确实被正确传递。

4. 版本兼容性bug #

虽然使用的是v0.16，但Kubernetes驱动在部分版本下可能存在缓存识别的bug。尝试升级Buildx到最新稳定版本（如v0.17+），同时确保Docker版本保持兼容。

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