多阶段构建需将私有依赖获取严格限定在builder阶段，通过build-arg或临时COPY传入凭证并立即清理，禁止任何凭证、配置或包管理命令进入runner阶段，确保运行镜像纯净隔离。
多阶段构建本身不自动解决私有依赖包的跨阶段引入问题，关键在于**把私有依赖的获取逻辑放在构建阶段，并确保它不被复制到运行阶段**。私有包（如私有 npm registry、pypi 仓库、maven 私服、或本地 git 仓库）的认证凭据、配置文件、缓存目录等，必须严格限制在 builder 阶段内，且不能通过 copy 或环境变量意外泄露。
私有依赖必须在构建阶段完成安装
私有依赖无法像公开包那样被预装进基础镜像，因此必须在 builder 阶段显式拉取。但要注意方式：
- Node.js：在 builder 阶段的 Dockerfile 中，先 COPY .npmrc（含 auth token）和 package*.json，再执行 npm ci；构建完成后立即删除 .npmrc（
RUN rm -f .npmrc），避免残留 - Python：在 builder 阶段使用 pip install --index-url https://your-private-pypi/simple/ --trusted-host your-private-pypi -r requirements.txt，不写入全局 pip.conf；也可用
--find-links指向私有 wheel 目录 - Java/Maven：在 builder 阶段 COPY settings.xml（含 server credentials），并指定
-s /app/settings.xml；构建完清理该文件，不带入 runner 阶段
禁止在运行阶段重新拉取或安装
runner 阶段绝不能执行任何包管理命令，否则会触发二次认证失败、网络超时或暴露密钥风险：
- 不要在 runner 阶段 COPY .npmrc、.pypirc、settings.xml 等配置文件
- 不要在 runner 阶段执行
npm install、pip install、mvn dependency:copy-dependencies等命令 - runner 阶段只做一件事：COPY --from=builder 复制已安装好的依赖目录（如 node_modules、site-packages）或打包产物（如 jar、dist）
安全传递凭证，不硬编码不挂载
构建阶段需要访问私有源，但密钥不能写死在 Dockerfile 或镜像层中：
- 使用 build-arg 传入临时 token（如
--build-arg NPM_TOKEN=xxx），并在 builder 阶段用 RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc；注意 build-arg 不会进入镜像历史，但需确保 CI 环境不打印日志 - 更推荐方式：在 CI 中生成临时 .npmrc 并通过 COPY --chown=node:node 加入 builder 阶段，构建后立即删除
- 绝对避免将 ~/.m2/settings.xml 或 ~/.npmrc 挂载进容器——这会绕过多阶段设计，让凭证直接暴露在 runner 镜像中
验证私有依赖是否真正隔离
构建完成后，快速检查 runner 镜像是否干净：
- 运行
docker run --rm <image> ls -A /root/.npm，应返回“no such file” - 检查
docker run --rm <image> cat /app/.npmrc，不应存在 - 对 Python 镜像，执行
docker run --rm <image> python -c "import requests; print(requests.__file__)"，确认路径指向 COPY 进来的 site-packages，而非 pip 动态安装路径
