2.3 node_modules 物理布局与提升算法

2.3 node_modules 物理布局与提升算法

本节摘要：解析器产出版本方案后，布局器负责把它摊到磁盘上。本节对照勘验嵌套与扁平两代布局的目录实拍，逐条拆解提升规则——什么条件下包会上顶层、顶层被占时怎么降级、deduped 在物理层对应什么。读完你应能拿着任何一个 node_modules 反推出它的生成规则，也为下一节的幽灵依赖事故备好了全部物理知识。

对照两组实拍：同一份清单的两种命运

布局演化的最好教材是把两代布局并排看。设清单只声明 A 与 B，两者各依赖同一版本的 C。先看嵌套时代的实拍：

node_modules/
├── A/
│   └── node_modules/
│       └── C/            # A 的私有副本
└── B/
    └── node_modules/
        └── C/            # B 的私有副本 —— 与上面内容完全相同
​

再看扁平时代的同一份清单：

node_modules/
├── A/
├── B/
└── C/                    # 全项目唯一一份
​

两组实拍的差异一目了然：嵌套布局里 C 被写入两遍，路径深度多了一层；扁平布局里 C 只有一份，A 与 B 通过 Node 的模块查找算法沿目录向上"够"到它。磁盘开销、安装时间、路径长度三项指标同时改善——这正是三代扁平化横扫历史舞台的原因。但第二张图里藏着一个语义变化：C 现在躺在顶层，意味着项目自己的代码也能直接 require 它，尽管清单从未声明。这颗雷下一节引爆，本节先把布局规则吃透。

提升规则的完整版

扁平化不是"一律平铺"，而是一套带降级路径的规则。把它拆成四条，任何目录形态都能对号入座：

规则一  顶层优先：解析出的每个包，先尝试放到顶层 node_modules
规则二  占位降级：顶层已有同包不同版本（或范围不兼容）时，
        该版本降级到"依赖它的那个包"自己的 node_modules 里
规则三  就近可寻：降级副本只对其宿主包可见，别的包依然向上够到顶层版
规则四  幂等重排：重复安装时布局与锁文件核对，能不动的尽量不动
​

用一个三方场景验证规则。清单声明 X（依赖 C 的 1.x）与 Y（依赖 C 的 2.x）：

node_modules/
├── X/
│   └── node_modules/
│       └── C@1.x         # 规则二：顶层被 2.x 占据，1.x 降级到 X 身上
├── Y/
└── C@2.x                 # 规则一：先到先得占据顶层
​

注意一个反直觉的细节：顶层归 2.x 还是 1.x，取决于谁先解析，而不是谁的语义"更该"在顶层。所以改变清单里依赖的声明顺序，理论上就能改变顶层归属——这也是为什么"重新安装后目录变了"经常不是玄学，只是解析顺序变了。deduped 判定同样由此而来：某个包声明 C 时，若沿目录向上能找到满足范围的版本，安装器就标记 deduped 不再落盘。

图 2-3 布局决策流程：从版本方案到磁盘落点

动手勘验自己的目录

规则背完，回到自己的项目验一遍。三组命令分别对应三条规则的现场取证：

# 取证一：谁被提升到了顶层（对照清单找"不认识的面孔"）
$ ls node_modules

# 取证二：某个包的完整落点树，看清提升与嵌套的分布
$ npm explain chalk
myapp@1.0.0
+-- my-ui@2.3.1
|   `-- chalk@5.3.0
+-- eslint@8.56.0
|   `-- chalk@4.1.2        # 双版本并存：5.x 与 4.x 各居其位
`-- jest@29.7.0
    `-- chalk@4.1.2 deduped

# 取证三：安装器视角的合法性与缺失检查
$ npm install              # 幂等核对：布局与锁文件不一致处会被修正
​

第二组输出是本节规则的全息照片：5.3.0 与 4.1.2 并存说明存在不兼容的范围声明；deduped 标记说明 jest 与 eslint 共用同一份 4.1.2。学会读这棵树，node_modules 就从黑盒变成了可解读的档案——遇到"引入报错找不到包"时，第一反应应当是跑一次 explain 看它到底被放哪了、还是压根没进来。

勘验附录：四个目录现象的成因速查

现象一：为什么有的包目录下还有自己的 node_modules，有的没有？ 有子目录说明该包的部分依赖与顶层版本不兼容，按规则二降级嵌套；没有则说明它的全部依赖都沿目录向上够到了。逐包勘验用 explain 命令核对，一眼看清。

现象二：依赖目录里那个点开头的隐藏文件是干什么的？ 那是安装器写的本地状态文件，记录当前目录的实际落盘形态，用于幂等核对与加速增量安装。可以把它理解为"锁文件的目录镜像"——删掉它无损正确性，但会让下次安装多做事。

现象三：同一个包为什么 deduped 与嵌套副本并存？ 说明依赖树里既有与顶层兼容的范围（deduped），也有不兼容的范围（物理嵌套）。这是合法状态，不必处理；若想消除双份，唯一路径是推动范围声明兼容——升级依赖方，让交集重新非空。

现象四：Windows 上偶尔仍报路径过长，扁平化不是已经治好了吗？ 扁平化把最常见的情形治好了，但深层嵌套的降级副本加上长包名仍可能超限。开启系统的长路径支持是环境层的根治手段；仓库层的预防则是控制依赖树深度——那正是 2.4 节幽灵依赖清理的附带收益。

性能视角：布局如何影响安装与启动

布局不只关乎"摆得整齐"，它直接写进两笔性能账。第一笔：安装期的写入量。 扁平化用去重把重复写入压到最低，提升与嵌套的分布决定了要写多少个文件——安装耗时的主要成分常常不是下载而是海量小文件的写入，这一点在 4.4 节的实验数据里有直接体现。第二笔：运行期的查找成本。 Node 的模块解析沿目录逐级向上找，嵌套越深、层级越多，每次引入的查找步数越多。单次查找是微秒级，但冷启动要解析成百上千个模块，累加起来就能在启动耗时里看到布局的影子。

把两笔账合起来看，还能解释一个选型争议：为什么 pnpm 的符号链接布局在超大仓库上收益显著——全局存储把跨项目的重复写入与重复存储一并消掉，等价于把第一笔账做到了理论下限。布局是"一次决定、长期计息"的架构选择，评估时要把安装与启动两条时间线都放上台面。

本节要点回顾

• 两代布局的分野：嵌套保隔离但重复且路径深，扁平去重且路径浅，但顶层让未声明包变得可引入；
• 提升四规则：顶层优先、占位降级、就近可寻、幂等重排——任何目录形态都能对号入座；
• 顶层归属由解析顺序决定，目录形态对清单声明顺序敏感，"重装后目录变了"多是顺序变化所致；
• deduped 的物理含义：沿目录向上能找到满足范围的版本，故不再落盘；
• 取证三板斧：ls 顶层找陌生面孔、explain 看落点树、幂等安装核对异常——排查目录问题的固定起手式。

布局规则吃透了，下一节把镜头对准这套规则最著名的副作用：幽灵依赖——它是怎么从"顶层可寻"这条无害规则里长出来的、怎么在CI上爆雷、又该怎么连根拔起。