3.4 npm ci 与可复现安装

3.4 npm ci 与可复现安装

本节摘要：流水线里的安装与开发者机器上的安装不该是同一个动作：前者要的是"严格照抄、绝不求解、干净落盘"，ci 类命令为此而生。本节逐条对照 install 与 ci 的语义差异，给出可复现安装的完整 checklist——锁文件在场只是及格线，环境固定、缓存校验、审计关卡、供给固化四件事配齐才算达标。读完你应能为任何一条流水线写出经得起审计的安装步骤。

从一条流水线事故说起

事故现场：某团队的构建流水线某天开始间歇性失败，报错指向一个依赖包的内部文件缺失。排查发现，有人一周前在本地装过一个新工具包，顺手提交了清单更新，但锁文件的对应条目在合并时被冲掉了。此后流水线的 install 每次都进入重求解模式，装到那个包的新版本——恰好该版本发布有缺陷。间歇性失败了一周，根因是流水线用了"开发者语义"的安装命令。

修复动作只有一行：把 install 换成 ci。但这一行背后是一整套语义差异，值得逐条摊开。

install 与 ci：逐条对照

两个命令共享同一套解析与落盘引擎，差异全在"纪律"上：

Yarn 侧的对应物是给 install 加参数的形态：frozen-lockfile 参数开启后，语义与 ci 高度对齐——锁文件被视为不可变契约，任何不一致都以失败告终。pnpm 同样提供 ci 语义的命令形态。三大工具在这个问题上的趋同，本身就是可复现已成行业底线的又一证物（呼应 1.3 节的范式转移）。

# 流水线标准写法（Npm 系）
$ npm ci
# added 1187 packages in 14s  —— 每次输出应当完全一致

# 流水线标准写法（Yarn 系）
$ yarn install --frozen-lockfile
# => Done in 9.42s
​

注意 ci 输出的一个细节：耗时与包数在多次运行间应当几乎不变。输出不稳定本身就是警报——说明某个环节仍在漂移，应停下来查，而不是当作噪音忽略。流水线日志是最好的幂等性监测仪，这个用法很多团队还没用起来。

图 3-4 两条安装路径的分叉与结局

可复现安装的完整 checklist

ci 命令解决的是"照抄纪律"，但可复现是一个系统工程。完整标准有五项，逐项自查：

一 锁文件在场且入库 —— 及格线，3.1 节已勘验
二 运行时版本固定   —— 清单里声明 node 版本约束，配合版本管理工具生效
三 缓存过校验       —— 命中缓存不跳过完整性核对，防止缓存投毒
四 审计设关卡       —— 高危漏洞直接失败，不放行进构建
五 供给可固化       —— 关键依赖进私有源，远端撤版不影响重放
​

第二项最常被漏：node 运行时本身也是依赖环境的一部分，运行时不同，同版本依赖也可能走出不同分支（3.2 节环境差异脚本的情形）。声明运行时约束的成本几乎为零，漏掉它的代价却是"查了一周的间歇性失败"。第三项与第五项分别在第四章 4.4 与第六章 6.3 展开，这里先立标准。

# 一个可审计的流水线安装段（示意）
$ corepack enable                          # 固定包管理器自身的版本
$ node --version                           # 显式输出运行时，日志留痕
$ npm ci                                   # 严格照抄安装
$ npm audit --audit-level=high             # 高危漏洞即失败
​

第一行值得单独解释：包管理器自己也有版本，且不同版本行为有差异（比如清单解析规则的演进）。用核心包管理器工具把"哪一版包管理器"也固定下来，才是把可复现闭环到了头——连安装器的版本都成了锁定的依赖。

可复现性的四级阶梯

五项标准还能再升一层视角——把可复现看成四级阶梯，团队照级定位自己。零级：有锁文件。 安装结果不再随时间漂移，这是及格线，3.1 节已覆盖。一级：环境固定。 运行时与包管理器版本锁定，跨机器的执行差异被消除——本节的运行时声明与版本固定工具在这一级生效。二级：供给固化。 依赖快照存在自己可控的存储里，远端变化不再影响重放——6.3 节的私有源是这一级的标准答案。三级：全链路证明。 从源码到构建产物全程有可验证的信任链，供应链安全领域的分级标准描述的就是这个终态。

分级模型的价值在于沟通：说"我们要可复现"是口号，说"我们从一级升到二级"是计划。多数团队的真实位置在一级半——锁与环境都管了，供给还托付给远端。第六章会给出补完二级与三级的具体设施，届时可以带着这把梯子去对号。

从 install 切到 ci 的五个注意点

命令替换只有一行，切换的坑都在周边。其一：先在分支演练。 失洽报错是 ci 的第一反应——先在分支上跑一遍，把所有清单与锁不一致的历史欠账暴露完，再动流水线主干。其二：凭据注入方式核对。 私有源的令牌在 ci 环境的注入方式要与 ci 的环境约定匹配，别让"严格模式"变成"无源模式"。其三：缓存对象要分清。 缓存的是包管理器的缓存目录，不是依赖目录——ci 会先清空依赖目录，缓存对象配错等于白配。其四：peer 冲突会浮出水面。 install 时代被静默容忍的 peer 不一致，ci 下会直接报错——这些报错是真问题，修声明而不是绕检查。其五：留意特殊平台。 精简发行版的流水线镜像对某些原生包的支持有差异，切换后第一次全量构建要盯一眼原生依赖的安装日志。

本节要点回顾

• install 与 ci 的分野：调和与严格——install 允许吸收环境现状，ci 只认锁文件、先清后装、绝不回写；
• 失洽时 ci 直接报错：这不是缺陷而是设计，报错把"清单与锁不一致"提前暴露在流水线而非生产环境；
• ci 输出是幂等监测仪：包数与耗时应逐次一致，输出抖动即漂移警报；
• 可复现五项标准：锁入库、运行时固定、缓存过校验、审计设关卡、供给可固化，缺一即留缺口；
• 包管理器自身版本也要锁定，可复现的最后一环是固定安装器本身。

到这里，"确定性"的机制与制度都勘验完了。第四章换镜头：沿着安装流水线本身走一遍全程——取件、编译、脚本、缓存，看包管理器在落盘的每一分钟里还替你做了什么。