3.1 锁定文件机制

3.1 锁定文件机制

本节摘要：锁文件是一份由包管理器自动生成、记录解析结果全貌的档案：每个依赖的精确版本、取件地址、完整性哈希与依赖关系，一样不少。本节解剖两种主流锁文件的真实片段，讲清生成与更新的触发时机，并给出"哪些操作动锁文件"的完整对照表。读完你应能把锁文件当成可审读的档案来用——排查依赖问题时，它是最忠实的第一证人。

先审读一份档案

空谈不如看实物。这是 package-lock.json 里一条完整的包记录（有删节）：

"node_modules/lodash": {
  "version": "4.17.21",
  "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
  "integrity": "sha512-v2kDEe57l2z4HhIqmvYnJRnr7H4A6CcgjJlbCqKBZGr3evmKNqtqvhAm9r2KJbYzh1A9bPKFfeXKvHdoGnxKyQw==",
  "dependencies": { "some-dep": "^1.0.0" }
}
​

四个字段各司其职，值得逐一圈注。version 记录解析器当时选定的精确版本——清单里的 ^4.17.21 到这里已经收敛成不带任何符号的事实。resolved 记录取件地址，它让"这个包从哪来"成为可追溯的问题，也是私有源迁移时最需要批量检查的字段。integrity 是压缩包的内容哈希，下载后重算比对，任何一位不符即拒绝安装——这是防篡改与防传输损坏的总闸，第六章供应链安全将赋予它更重的使命。dependencies 记录该包自身的依赖约束，正是 2.1 节解析演算里那些子约束的存档。

Yarn 的锁文件字段同源而形态不同，采用缩进式的条目写法：

lodash@^4.17.21:
  version "4.17.21"
  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz"
  integrity sha512-v2kDEe57...
​

注意条目键是 lodash@^4.17.21——以清单里的原始范围声明为键。这个设计让 Yarn 的锁文件可以直接回答"清单里这条声明当时解到了什么版本"，而 Npm 的锁文件键是物理路径，回答的则是"这个位置放了哪个版本"。两种视角没有优劣，但解释了为什么两份锁文件无法简单互相转换——第七章迁移实务里的换锁步骤，正是要处理这层差异。

图 3-1 锁文件记录的解剖与三道防线

生成与更新：把触发时机背下来

锁文件的存续规则可以压缩成一句话：没有则生成，有则核对，核对不过则回写。据此把高频操作归成四类，每一类对锁文件的影响完全确定：

表格最后一行值得单独骂一次：只改清单不更新锁文件，是锁文件事故里最常见的人祸。清单说"我要 ^5.0.0"而锁文件记录的还是 4.17.21 时，安装器陷入两难——不同工具的策略不同，有的报错、有的静默重求解并回写，后者意味着你下次安装时版本会悄悄变化。所以纪律只有一条：清单与锁文件是连体婴，永远同一次提交。

两个高频疑问的现场裁决

疑问一：锁文件该提交进版本库吗？ 应用类项目毫无悬念——提交，而且必须提交，这是可复现的前提。真正有讨论价值的是"库"类项目：有人主张库不提交锁文件，让使用者自行决定依赖版本。我的立场是也提交：锁文件不影响使用者的解析自由，却能让库自身的 CI 与贡献者环境保持确定，没有任何损失。所谓"锁文件限制使用者"的担心，源于把锁文件的职责误读成了强制——它锁的只是本仓库的安装事实，不是下游的选择。

疑问二：改了锁文件会怎样？ 答案取决于"改"的方式。用工具改（升级、加装），记录自洽，安全；用手改，几乎必然制造清单与锁文件的不一致，把安装器逼进重求解模式。第三章 3.3 的冲突实录里，我们会看到"手改"最典型的翻车现场。

锁文件的三个冷知识

冷知识一：文件头部的格式版本号是兼容性开关。 锁文件开头有个版本字段，标记这套记录的格式代次——工具升级时用它判断能否沿用旧格式。跨大代次的锁文件会被工具整体重新生成而非增量更新，这就是"升级工具后锁文件大改"的机理：不是安装错了，是格式换代。

冷知识二：锁文件里还有嵌套条目的形态。 2.3 节讲过降级嵌套的副本去哪了——它们在锁文件里以嵌套路径的条目单独记录，与顶层条目并存。勘验锁文件时看到带长路径的条目，对应的正是磁盘上的嵌套副本，两边可以互相印证，排查布局问题时尤其好用。

冷知识三：锁文件是可检索的审计对象。 排查"某个包从哪来"时，直接在锁文件里搜包名，往往比跑依赖树命令更快——条目附近同时记录着引入它的依赖方信息。资深工程师的锁文件用法接近数据库：按包名检索、按依赖方聚类、按哈希核对，一份文件当三份工具使。

本节要点回顾

• 锁文件四字段：version 冻结事实、resolved 追溯来源、integrity 防篡改、dependencies 存档子约束——排查依赖问题时按此顺序审读；
• 两种锁文件键形态不同：Npm 以路径为键、Yarn 以声明为键，视角差异导致不能直接互转，迁移必须走工具换锁；
• 存续规则一句话：没有则生成、有则核对、核对不过则回写——回写即漂移入口；
• 清单与锁文件必须同框提交，只改清单不更新锁是最常见的人祸；
• 应用与库都应提交锁文件：它锁的是本仓库的安装事实，不妨碍下游的自由。

锁文件是档案，但档案也有说不清的地方——下一节勘验"可复现"命题的真实边界：幂等性到底担保到哪一步，什么情况下照着锁文件装也会翻车。