Skip to content

构建可复现:依赖锁定与多阶段镜像 ​

本篇要点:让「同一个 commit 永远得到同一个镜像」从口号变成一条带校验的流水线。前置文章:[《GitLab CI 进阶》](/guide/cicd/gitlab-ci-advanced.html)我们把 GitLab CI 的 DAG 和缓存用起来了,这一章开始动手改造构建本身。

一、为什么需要它 ​

2026 年 3 月,一家做电子签的公司周五晚上回滚订单服务到 order:1.4.2。这个 tag 是两周前发布的,回滚完成后错误量反而上升,日志里反复出现 TypeError: Cannot read properties of undefined (reading 'region')。查了两天才弄清楚:1.4.2 在镜像仓库里被推过两次。发布后第十七天,有人为了热修在本地执行了 docker build -t order:1.4.2 && docker push,把同一个 tag 覆盖了。回滚上去的其实是带热修的那一份,而它依赖的一份共享库与当时的数据库结构不匹配。

一次覆盖,把回滚变成了又一次发布。失效的地方有三处。

依赖没锁。package.json 里写 "lodash": "^4.17.21",^ 允许 4.x 下任意小版本和补丁版。上游晚上发一个 4.17.22,第二天早上 CI 装到的就是新东西,而你一行代码没改。锁文件虽然提交了,但构建时跑的是 npm install 而不是 npm ci,npm 会按 manifest 重新解析,顺手把锁文件改写。

基础镜像没锁。FROM node:22 指向一个每天都在重建的 tag,上游合一次补丁,这个 tag 对应的镜像摘要(digest)就换一个。两次构建隔一天,操作系统层的软件包已经不同。

构建过程本身不确定。前端打包器把构建时间写进产物;COPY . . 带进了 .git 目录;apt-get update 拿到的包版本随时间变化;镜像里写入了构建机主机名。

可复现构建(reproducible build)处理的就是这一层:不是「大概一样」,而是能被验证的一样。

二、核心概念 ​

4.1 可复现构建的三级台阶 ​

拿烤面包作类比。食谱写「面粉适量、盐少许」,两个人做出来必然不同;写「高筋粉 500g、盐 3.0g」,才可能一致。可复现构建就是把「适量」全部称到克。

强度递增,成本也递增,分三级:

级别锁什么达成手段验证方式
L1 依赖可复现传递依赖的精确版本与内容哈希lockfile + 冻结安装manifest 与 lockfile 不一致时构建失败
L2 环境可复现基础镜像与工具链版本镜像用 digest,工具链用固定版本比对 imagetools inspect 的 digest
L3 产物可复现时间戳、文件顺序、绝对路径SOURCE_DATE_EPOCH、确定性打包两次构建的产物 sha256 相同

多数团队做到 L1 加 L2 就够用。L3 需要工具链配合,前端打包器对它的支持参差不齐,部分 Webpack 插件仍会写入时间戳。要紧的是知道自己在哪一级,而不是以为「用了 Docker 就复现了」。

反例很常见:Dockerfile 和 lockfile 都提交了,构建仍然不稳定,因为 Dockerfile 第一行是 FROM node:22,前两级里只做到了一半。

4.2 依赖锁定:锁版本、锁哈希、锁传递依赖 ​

锁文件(lockfile)的强度有三档,很多人只用到了第一档。

锁版本,是记录每个包解析到的确切版本号,比如 lodash@4.17.21。npm 的 package-lock.json、pnpm 的 pnpm-lock.yaml、Yarn 的 yarn.lock、Python 的 poetry.lock 与 uv.lock、Go 的 go.sum 都在做这件事。

锁哈希,是记录包的完整性校验值(integrity)。npm 系从 lockfileVersion 2 起在 integrity 字段写 sha512-...;Go 的 go.sum 每行形如 module version h1:base64hash=。有了哈希,源站被投毒或者镜像站返回了内容不同的包,安装会直接失败而不是装进去一个「同名不同物」。

锁传递依赖,是最容易漏的一档。requirements.txt 只写顶层依赖时,每次解析出来的传递依赖可能不同。要锁全,要么 pip-compile --generate-hashes 生成完整清单,要么用 uv lock、poetry lock 这类解析整棵树的工具。

到 CI 上,安装命令必须用冻结模式,否则锁文件等于摆设:

包管理器冻结安装命令不冻结会怎样
npmnpm cinpm install 按 manifest 重解析并改写 lockfile
pnpmpnpm install --frozen-lockfile自动补写 lockfile,构建偏离仓库状态
Yarn Berryyarn install --immutable同上
Python (pip)pip install -r requirements.txt --require-hashes只校验版本,不校验哈希
Python (uv)uv sync --frozen自动更新 uv.lock
GoGOFLAGS=-mod=readonlygo build 可能隐式改写 go.sum

4.3 私有源:企业内网的第二个坑 ​

内网一般不让直连公网仓库,要经过 Nexus、Artifactory、Verdaccio、Harbor 这类私有源(private registry)。

这里有个具体麻烦:lockfile 里的 resolved 字段写死了下载地址。如果锁文件是在开发者机器上生成的,里面是 https://registry.npmjs.org/...,到了内网 CI 就拉不动,报 ETIMEDOUT 或 407。

三种处理方式按可靠性排序。第一种是让所有人生成锁文件时就指向私有源,在仓库里放一份 .npmrc;缺点是换源要重新生成。第二种是用 pnpm 的 replace-registry-host 配置,让 pnpm 忽略锁文件里的 host 只保留路径,pnpm 8 之后可用。第三种是在 CI 里 sed 替换,脆,只应急。

.npmrc 里的 token 绝不能进仓库:

ini
registry=https://nexus.corp.example.com/repository/npm-group/
//nexus.corp.example.com/repository/npm-group/:_authToken=${NPM_TOKEN}
strict-ssl=true

预期输出:本地或 CI 环境下 ${NPM_TOKEN} 由 secret 注入,pnpm install 输出中出现 GET 200 而不是 GET 401;如果 token 缺失,报错是 ERR_PNPM_FETCH_401 ... Unable to authenticate。把真实 token 写进这个文件再提交,就是《供应链安全:SBOM、签名与扫描》讲供应链扫描时最先被扫出来的那一类问题。

4.4 多阶段构建:只留运行时需要的东西 ​

多阶段构建(multi-stage build)把编译环境和运行环境拆成两个 FROM,最后一个 stage 才是产物。

图 4-1 多阶段构建的产物边界:builder 里的东西默认全部消失,除非显式 COPY --from

如图 4-1 所示,那条从 E 指向 F 的虚线是理解多阶段的关键:没有被 COPY --from=builder 点名的东西一律不进最终镜像。所以 builder 里装多少工具都不影响镜像大小,只影响构建时间。

写法上有四个决定成败的细节。

一,层顺序按变更频率排。COPY package.json pnpm-lock.yaml 在前,COPY . . 在后。依赖没变时 RUN pnpm install 这一层直接命中缓存,省掉几分钟。

二,用 .dockerignore 挡住 node_modules、.git、dist、.env。否则 COPY . . 会把本地 1GB 的 node_modules 拷进去,再被 RUN install 覆盖一遍,构建时间接近翻倍,还顺手把 .env 里的密钥烧进镜像层。

三,运行时用非 root 用户。distroless 的 :nonroot tag、Node 官方镜像内置的 node 用户都是现成的。不写 USER 就等于用 root 跑生产进程,一旦容器被突破,代价完全不同。

四,基础镜像用 digest 而不是 tag,这是 L2 的全部内容。写成 FROM node:22.20.0-bookworm-slim@sha256:...。代价是升级要手动改,收益是升级变成一次可 review 的 commit,而不是某天早上自己发生的事故。

镜像瘦身的数量级(以 Node 服务为例,2026 年 11 月官方镜像的未压缩大小):node:22 约 1.1GB,node:22-bookworm-slim 约 220MB,node:22-alpine 约 135MB,gcr.io/distroless/nodejs22-debian12 约 120MB。多阶段把 devDependencies 挡在外面,通常还能再省三到五成,具体看项目。

4.5 产物校验:用 digest 说话 ​

构建完必须回答一个问题:我部署的到底是不是我构建的那一份。

镜像摘要(digest)是内容寻址的,sha256:... 只要内容差一个字节就变;tag 是可变的指针。所以部署清单里应该写 digest,回滚就是改回上一个 digest,改的是一个 diff 可见的 commit。

校验有三层落点:构建后把 digest 写进制品元数据;构建产物本身算 sha256sum;需要更强保证时由构建平台签发来源证明(provenance attestation),《供应链安全:SBOM、签名与扫描》讲 SBOM 与 SLSA 时会回到这里。

三、动手实践 ​

下面四步可以在任意一个 Node 项目里复现。环境为 Docker 27 以上(含 buildx)、Node 22、pnpm 10。

步骤一:验证冻结安装真的会拦住漂移 ​

先故意让 manifest 和 lockfile 不同步:

bash
npm pkg set dependencies.express="^5.1.0"
npm ci

运行结果:

text
npm error `npm ci` can only install packages when your package.json and
package-lock.json or npm-shrinkwrap.json are in sync. Please update your
lock file with `npm install` before continuing.
npm error Missing: express@5.1.0 from lock file
npm error A complete log of this run can be found in: /home/runner/.npm/_logs/...

这正是想要的失败。换成 npm install,它会静默改写 lockfile 并继续,于是 CI 和开发者机器装出两套依赖,第二个坑从这里开始。

步骤二:写一个可复现的多阶段 Dockerfile ​

dockerfile
# syntax=docker/dockerfile:1.7
FROM node:22.20.0-bookworm-slim AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml .npmrc ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build && pnpm prune --prod

FROM gcr.io/distroless/nodejs22-debian12:nonroot
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./
EXPOSE 3000
CMD ["dist/main.js"]

预期输出:docker build 的日志分两组 stage 出现,[builder] 段约有 6 层,[stage-1] 段只有 4 层;最终镜像约 180–220MB,docker run -p 3000:3000 后 curl localhost:3000/healthz 返回 {"status":"ok"}。

三处值得单独指出。.npmrc 跟 manifest 一起 COPY,否则私有源配置缺失会让 pnpm install 直接 401。pnpm prune --prod 在 builder 内就把开发依赖删掉,拷进 runtime 的 node_modules 已经是精简过的。distroless 镜像没有 /bin/sh,所以 CMD 必须用 exec 形式(JSON 数组),shell 形式会以 exec: "/bin/sh": stat /bin/sh: no such file or directory 失败——这是从 alpine 迁到 distroless 时最常见的第一个报错。

步骤三:构建两次,比 digest ​

bash
docker buildx build --platform linux/amd64 -t pay:1.4.2 --iidfile /tmp/a.id .
sleep 1
docker buildx build --platform linux/amd64 -t pay:1.4.2 --iidfile /tmp/b.id .
diff /tmp/a.id /tmp/b.id && echo REPRODUCIBLE

运行结果(第一次通常是失败):

text
1c1
< sha256:8f2b1d4e0a6c...
---
> sha256:3a91e6f8c4d2...

两次构建出不同镜像是常态。先查基础镜像 tag 有没有漂移:docker buildx imagetools inspect node:22.20.0-bookworm-slim 看 digest 是否变化。digest 一致还不同,就用 --progress=plain 看哪一层没命中缓存,最常见的原因是 COPY . . 把 .git 带了进去,而 .git/index 每次 git status 都会改。

改到真正输出 REPRODUCIBLE 的项目有一个前提:RUN 步骤里不联网装东西、不写时间戳。前端构建补一句 ENV SOURCE_DATE_EPOCH=$(git log -1 --format=%ct),让打包器用固定的构建时间。

步骤四:把 digest 钉进部署清单 ​

bash
digest=$(docker buildx imagetools inspect \
  registry.corp.example.com/pay:1.4.2 --format '{{json .Manifest.Digest}}' | tr -d '"')
sed -i.bak "s|image: registry.corp.example.com/pay:.*|image: registry.corp.example.com/pay@${digest}|" \
  deploy/prod.yaml
grep 'image:' deploy/prod.yaml

运行结果:

text
image: registry.corp.example.com/pay@sha256:6d1f0a3c9b8e4f27a5d6c1e8b3f790a2c...

从此 1.4.2 这个 tag 再被谁覆盖都不影响生产,部署清单不认 tag。回滚是改回上一个 digest,动作和发布走同一条路。

四、常见误解 ​

很多人以为提交了 lockfile 就叫锁住了依赖。实际上锁文件要被冻结安装读到才生效:npm install、不带 --require-hashes 的 pip install -r、不加 -mod=readonly 的 go build,都可能在解析阶段改掉锁文件。判断标准很直接:CI 里把 lockfile 设成只读,或者构建后跑 git diff --exit-code,能过才算数。

很多人以为多阶段构建必然减小镜像,其实它减的是「不被 COPY 的文件」,前提是你真的没把它们拷进去。见过 COPY --from=builder /app /app 这种一把梭写法,builder 里的源码、测试、.cache 全进了 runtime,镜像 1.9GB,和单阶段没区别。收益来自精确的 COPY 列表,不来自 FROM 的个数。

很多人以为换成 alpine 一定更小更好。alpine 用 musl libc,某些原生模块(旧版 sharp、bcrypt、部分 Python C 扩展)没有预编译的 musl 包,pnpm install 要现场编译,构建从 40 秒涨到 6 分钟,还得在 builder 里装 python3 make g++。这类项目用 -slim 的 glibc 版本更省事。选基础镜像要看原生依赖,不只看 tag 后面的字数。

五、小结 ​

[《GitLab CI 进阶》](/guide/cicd/gitlab-ci-advanced.html)把流水线的骨架和缓存配好了,这一章把「构建」这个黑盒打开,要求它每次给出同一个结果。

  • 可复现分三级:依赖可复现(lockfile 加冻结安装)、环境可复现(基础镜像用 digest)、产物可复现(去掉时间戳与文件顺序依赖)。先确认自己在哪一级。
  • 锁文件的强度从「锁版本」到「锁哈希」再到「锁传递依赖」递增,Python 与 Go 项目最容易只做到第一档。
  • 私有源的真实麻烦是锁文件里的 resolved 写死了 host;token 走 secret 注入,不进仓库。
  • 多阶段构建省空间靠精确的 COPY --from、.dockerignore 和层顺序;alpine 不是万能解,原生模块多的项目用 -slim。
  • 部署清单写 digest 不写 tag。tag 会被覆盖,digest 不会。

六、相关文章 ​

这一章的代价很实在:基础镜像用 digest 之后不会自动升级,每次都要手动改;pnpm prune --prod 和全量 COPY 也让构建变慢;冻结安装不能靠缓存走捷径。稳妥和快之间这笔账要怎么算?[《流水线提速:并行、缓存与增量》](/guide/cicd/pipeline-speed-optimization.html)讲流水线提速:先把耗时拆开看清楚,再用并行、缓存和镜像层复用压缩墙钟时间,最后算出这次优化到底值多少钱。

继续阅读:[《流水线提速:并行、缓存与增量》 流水线提速:并行、缓存与增量](/guide/cicd/pipeline-speed-optimization.html)