深入理解npm、pnpm和yarn的lock文件，我发现了一些细节

作为组长，我在Code Review里，最常跟新人强调的一句话就是："不要忘了提交lock文件！ "

为什么？因为lock文件是保证我们团队成员、测试环境、线上服务器，能安装完全一致的依赖版本的"契约"，它是实现"可复现构建"（Reproducible Build）的基石，能从根本上避免"在我电脑上是好的啊"这种经典问题。

但我们每天都在git add这个文件，有多少人真正打开看过它？package-lock.json, yarn.lock, pnpm-lock.yaml，它们到底长什么样？它们之间有什么本质区别？

前段时间，因为排查一个棘手的依赖问题，我花时间深入研究了一下这三个文件，发现了一些非常有意思的细节。这些细节，恰恰揭示了不同包管理工具的运作方式。

npm：`package-lock.json`

我们先来看大家最熟悉的npm的lock文件。

打开package-lock.json（v2/v3版本），第一感觉就是"大"和"全"。它是一个巨大的JSON文件，里面密密麻麻记录了所有信息。
它的核心是packages这个字段。你会发现，它是一个扁平的列表 ，把你项目node_modules里的每一个包，无论层级多深，都列了出来。

JSON 复制代码

{
  "name": "my-project",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": { // 项目根目录
      "name": "my-project",
      "version": "1.0.0",
      "dependencies": {
        "vue": "^3.4.21"
      }
    },
    "node_modules/@vue/compiler-core": { // 一个被提升的依赖
      "version": "3.4.21",
      "resolved": "https://registry.npmjs.org/@vue/compiler-core/-/compiler-core-3.4.21.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "@vue/shared": "3.4.21"
      }
    },
    "node_modules/vue": { // 你直接安装的依赖
      "version": "3.4.21",
      "resolved": "https://registry.npmjs.org/vue/-/vue-3.4.21.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "@vue/compiler-core": "3.4.21",
        "@vue/runtime-dom": "3.4.21",
        // ...
      }
    }
    // ... 还有成百上千个类似的条目
  }
}

package-lock.json的结构，几乎就是你node_modules目录的一份完整快照。npm通过"提升（hoisting）"机制把大部分依赖都平铺在node_modules根目录，而lock文件就记录下了这个结果。这也是为什么它看起来有点"乱"------因为它反映的就是那个复杂的、经过计算后的扁平化目录结构。这种结构，某个依赖的依赖被提升了，lock文件里也记录了，所以它就存在了。

Yarn：`yarn.lock`

接下来看Yarn v1（Classic）的lock文件。

比npm的清爽很多。它不是JSON，而是一种自定义的、类似YAML的格式。没有那么多层级嵌套。
它不是以路径为索引，而是以 "包名 + 版本范围" 为索引。

YAML 复制代码

# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1

"@babel/helper-plugin-utils@^7.0.0":
  version "7.24.7"
  resolved "https://registry.yarnpkg.com/@babel/helper-plugin-utils/-/helper-plugin-utils-7.24.7.tgz#..."
  integrity sha512-...

vue@^3.4.21:
  version "3.4.21"
  resolved "https://registry.yarnpkg.com/vue/-/vue-3.4.21.tgz#..."
  integrity sha512-...
  dependencies:
    "@vue/compiler-core" "3.4.21"
    "@vue/runtime-dom" "3.4.21"
    // ...

yarn.lock的核心，是一种 版本解析契约。它只关心一件事：对于vue@^3.4.21这个版本范围的请求，我最终给你锁定到3.4.21这个确切的版本。

它不像npm那样，详细描述每个包最终被放在node_modules的哪个位置。它只负责定义"版本解析"的结果。至于这些确定了版本的包，最后如何被提升、被组织到node_modules里，那是Yarn安装算法自己的事。这种关注点分离，让lock文件本身变得非常简洁，但也让它和最终的目录结构的对应关系，显得不那么直观。

pnpm：`pnpm-lock.yaml`

最后，是我认为设计得最优雅的pnpm的lock文件。

可读性极高。它是YAML格式，结构清晰，带有缩进，完美地反映了依赖关系。
它的结构，就是pnpm实现其node_modules链接机制的一份 设计蓝图。

YAML 复制代码

lockfileVersion: '6.0'

importers:

  .:
    dependencies:
      vue:
        specifier: ^3.4.21
        version: 3.4.21

packages:

  /@vue/compiler-core@3.4.21:
    resolution: {integrity: sha512-...}
    dependencies:
      '@vue/shared': 3.4.21
    dev: false

  /vue@3.4.21:
    resolution: {integrity: sha512-...}
    dependencies:
      '@vue/compiler-core': 3.4.21
      '@vue/runtime-dom': 3.4.21
      '@vue/shared': 3.4.21
    dev: false

# ...

pnpm-lock.yaml里最关键的细节，是packages下的那些路径格式的键，比如/vue@3.4.21。这个路径，直接对应了包在node_modules/.pnpm这个虚拟存储目录下的真实存放路径。

更重要的是，在每个包的条目下，它都明确地列出了它自己 的dependencies。这是一个严格的、非扁平化的、能够真实反映包与包之间依赖关系的结构。

打开这个lock文件，你马上就能理解为什么pnpm能杜绝"幽灵依赖"------因为你的项目代码，只能访问到importers下声明的依赖（比如vue），而vue自己所依赖的@vue/compiler-core，你的代码根本够不着。lock文件的结构，从设计上就保证了这种隔离性。

研究完这三个文件，我有一个很深的感触：Lock文件，就像是一个包管理工具的灵魂，它的结构，直接反映了其底层的设计理念。

包管理器	Lock文件	结构风格	设计理念
npm	`package-lock.json`	扁平的、基于路径的	`node_modules`目录的"快照"，真实的记录提升后的结果
Yarn v1	`yarn.lock`	分组的、基于版本范围的	版本解析契约，只负责锁定版本，不关心物理布局
pnpm	`pnpm-lock.yaml`	嵌套的、严格的、基于依赖的	链接式`node_modules`，结构即规范

作为团队的负责人，我现在更倾向于pnpm，不仅仅因为它快，更是因为它这种严谨的、可预测的设计哲学，能从根本上避免很多依赖问题。

下次像其它很多同学遇到"为什么CI上的依赖和本地不一致"的问题时，别只是rm -rf node_modules然后重新install。尝试去读一读你的lock文件，也许答案，就藏在这些细节里。

分享完毕，谢谢大家😄

深入理解npm、pnpm和yarn的lock文件，我发现了一些细节

npm：package-lock.json

Yarn：yarn.lock

pnpm：pnpm-lock.yaml

npm：`package-lock.json`

Yarn：`yarn.lock`

pnpm：`pnpm-lock.yaml`