Docker 构建用 ARG 传短期令牌，依赖安装层每次失去缓存

私有包版本没有变化，Docker 构建却每次重新下载、安装依赖。如果构建命令把短期令牌或含令牌的仓库地址传给 --build-arg，令牌轮换就可能让安装层失去缓存。即使包版本仍是同一个，Docker 看到的构建输入也已经不同。

本文针对启用 BuildKit、在 RUN 中访问私有包仓库的构建。处理方法是用 secret 挂载提供凭据，把决定依赖内容的锁文件、版本号与认证信息分开。secret 内容变化本身不会使缓存失效；因此修复时也要明确，哪些变化应当触发重新安装。

从第一条失去缓存的指令判断

先对比两次构建的普通进度日志，找到第一次没有显示 CACHED 的步骤。检查这一层之前的基础镜像、复制文件和构建参数是否变化，尤其是每次登录都会重新生成的 token。不要为了对比而打印令牌或完整带密码的仓库 URL。

例如，下面的结构会把认证地址作为构建输入：

ARG PRIVATE_REPO_URL
ARG CORE_VERSION
RUN pip install --extra-index-url "$PRIVATE_REPO_URL" "core==$CORE_VERSION"

这里仅展示有问题的结构，不能把真实凭据直接写进 Dockerfile。PRIVATE_REPO_URL 包含短期令牌时，更新它就会改变后续使用该参数的构建步骤。普通 ARG 的值变化会在首次使用处造成缓存失效，而不是在声明行创建一个新的文件层；后续 RUN 还会隐式使用已声明参数形成的环境，即使命令文本里没有直接写出变量，也可能受影响。

如果每次使用的构建器都没有可用缓存，或者锁文件、基础镜像也在变化，先解决这些差异。secret 挂载不会自动恢复已经丢失的缓存，更不会让不同依赖输入复用同一安装结果。

用临时 secret 文件提供认证

下面用 npm 私有模块说明具体改法。需要已有一致的 package.json 和 package-lock.json，并且构建环境支持 BuildKit 的 RUN --mount=type=secret。其他包管理器应把 secret 挂到其实际读取的认证配置路径，不能只照搬 npm 的文件名。

将以下内容保存为独立验证用的 Dockerfile.deps：

# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \
    npm ci

这是依赖安装阶段示例，没有包含应用源码、编译和运行入口。集成到项目时使用项目已经批准的 Node 镜像与构建阶段；多阶段构建中，凭据只挂到实际下载依赖的那条 RUN，后续阶段按项目约定复制构建产物。不要把这份示例镜像直接当成完整业务镜像部署。

npm ci 要求锁文件与包清单一致，不会代替你修复不一致的锁文件。若生成锁文件时使用了影响依赖树的选项，构建时仍需保留相同约定。认证配置文件中放正确的私有仓库地址与凭据，但不要把它复制进镜像。

以下路径是构建机上的占位路径，替换为现有的受保护 npm 配置文件；将文件放在构建上下文之外：

docker build --progress=plain \
  -f Dockerfile.deps \
  --secret id=npmrc,src=/secure/build/npmrc \
  -t app-deps:cache-check .

id=npmrc 与 Dockerfile 中的 ID 必须一致。required=true 表示需要执行这条安装指令时，缺少该 secret 应报错，避免悄悄退回未认证的安装方式；缓存命中不会重新执行安装，也不能用来验证认证配置是否有效。

示例安装步骤以 root 用户执行，所以使用 /root/.npmrc。如果项目在该步骤之前已经切换了 USER，应按实际用户的配置路径和 UID/GID 设置 secret 的 target、uid、gid 与必要权限。文件型 secret 默认归 UID 0/GID 0 所有、模式为 0400；不要用向所有用户放开权限的办法掩盖读取路径或用户不匹配。

secret 只在这条构建指令执行期间提供。不要再将其内容写入 ENV、复制到工作目录，或输出到日志。安装命令及它启动的脚本能够读取所挂载的秘密，因此仍需信任构建依赖与执行脚本；挂载机制不能阻止命令主动把凭据另存进产物。

令牌轮换和依赖更新分别验证

在同一构建器、同一基础镜像与相同构建输入下完成一次成功构建，再只替换认证文件里的令牌，重复上述构建。安装步骤具备可用缓存时应能显示 CACHED。这是检查认证内容没有继续作为普通构建参数参与缓存判断，不是检查新令牌能否登录。

还要检查原先传递秘密的 ARG 和 --build-arg 是否已经移除。只增加 secret 挂载，却继续保留每次变化的令牌参数，可能仍让后续 RUN 的缓存失效。

依赖发生变化时，更新 package.json、锁文件或项目明确的版本输入。由于示例在安装前复制了两个清单，文件内容改变会让后面的安装重新执行。secret 的内容不参与缓存失效，但 secret 的 ID、挂载路径等属性会参与。

如果认证文件同时改变了仓库地址或其他会影响安装结果的设置，仅更改它的内容可能仍命中旧缓存。需要有意重新取依赖时，可以在这次隔离验证构建中使用 --no-cache：

docker build --no-cache --progress=plain \
  -f Dockerfile.deps \
  --secret id=npmrc,src=/secure/build/npmrc \
  -t app-deps:auth-check .

这会重跑构建步骤，增加下载和磁盘开销，也能让安装实际使用当前凭据。频繁发布的项目可以用可公开的依赖配置修订号控制刷新；不要把秘密值或其变形重新当成缓存参数。令牌是否轮换与依赖是否需要刷新，是两个不同的判断。

保留构建和回退边界

验证安装结果后，再把变更合入原业务构建流程，检查完整镜像的应用启动与依赖功能。保留先前镜像与构建定义；出现兼容问题时可回到已验证镜像，不需要删除所有构建缓存或持久卷。

如果旧流程已经把令牌写入镜像、日志或构建产物，改用 secret 只影响后续构建，不会擦除旧记录。应按现有凭据管理流程撤销或轮换可能暴露的令牌，并处理旧产物的保留范围，不能靠在新 Dockerfile 末尾删除一个配置文件就认定旧秘密已消失。