我第一次在同事的.npmrc里看到shamefully-hoist=true这行配置时，第一反应是：这玩意怎么自带情绪。后来翻 pnpm 官方文档才明白，名字真没开玩笑——在 pnpm 作者眼里，把依赖全部“提”到node_modules顶层这件事，本质上就是一种有失优雅的妥协，所以开关被命名为“shamefully-hoist”，翻译过来就是“羞耻地提升”。它的作用也很直白：关闭 pnpm 默认的严格依赖隔离，把所有依赖都暴露到根目录的node_modules里，模拟出 npm 那种扁平结构。
如果你正准备把老项目从 npm 迁移到 pnpm，或者已经迁移完毕但是疯狂报Cannot find module，大概率会在各种解决方案里撞见这行配置。而很多人的第一反应就是：先抄上再说。我劝你别急，这行配置背后藏着整个包管理器设计哲学的分歧，也藏着一堆“当时能跑、过两天突然挂掉”的风险。
1. 一个自带嘲笑气质的开关，解决的是什么问题
1.1 从 Node.js 的模块查找规则说起
要想搞懂shamefully-hoist，得先明白两个基础机制。第一个是 Node.js 的模块查找规则：当你写require('lodash')时，Node 会从当前文件所在目录开始，一层一层往上级目录找node_modules/lodash，一直找到文件系统根目录为止。这个规则是包管理器一切行为的地基——谁能被你 require 到，取决于某个node_modules目录里有没有对应包。
第二个机制是 npm 从早期就开始使用的“依赖提升”。npm 安装依赖时，会把整棵依赖树分析一遍，尽量把包平铺到根目录的node_modules里。比如项目依赖webpack，webpack依赖acorn，npm 很可能把acorn也放到顶层。这种做法的初衷是减少重复安装、让 Node 查找更方便，但副作用非常明显：所有间接依赖都以一种“没有身份证的状态”躺在根目录，代码想用就能用，哪怕package.json里根本没有声明它们。
1.2 “提升”为什么在 pnpm 语境里不光荣
pnpm 走的是另一条路。它会在node_modules下建一个.pnpm虚拟存储目录，把每个依赖按包名@版本号拆开放好，然后只在项目根目录保留“直接依赖”的符号链接。当一个包需要它的依赖时，pnpm 会把依赖的符号链接放到那个包的私有node_modules里，严格隔离，纵使间接依赖和业务代码近在咫尺，也碰不到。
在这种设计下，“提升”已经不再是一种优化手段，而是为了兼容旧世界而存在的补救方案。pnpm 的作者给这个开关起名shamefully-hoist，多少带点“我知道你要给项目上呼吸机，但这也太不体面了”的意味。了解这层背景后，你再看到.npmrc里的shamefully-hoist=true，就知道这通常意味着：项目刚从 npm 迁移过来、某条工具链在 pnpm 严格模式下彻底跑不通、团队决定先让项目能启动再说。
2. pnpm 默认的 node_modules，靠符号链接维持秩序
2.1 虚拟存储：node_modules/.pnpm 里到底是什么
直观对比一下两种结构。假设项目只安装了express，而express有一堆依赖，npm 的node_modules大概是扁平的一大片：
node_modules/ express/ accepts/ bytes/ mime-types/ ...pnpm 则长这样：
node_modules/ .pnpm/ express@4.19.2/node_modules/ express/ accepts/ bytes/ ... accepts@1.3.8/node_modules/ accepts/ mime-types/ negotiator/ bytes@3.1.2/node_modules/ bytes/ express -> .pnpm/express@4.19.2/node_modules/express根目录只有一个指向虚拟存储的express符号链接。当express内部的代码require('accepts')时，Node 会从.pnpm/express@4.19.2/node_modules/这个真实路径里向上找，正好看到 pnpm 放在该目录下的accepts符号链接，于是解析成功。如果项目业务代码想直接require('accepts')，它从自己文件路径往上找，最终只看到根目录的node_modules，里面只有express，没有accepts，于是立刻报错。
这套机制最大的意义在于：直接依赖之外的包，业务代码是看不到的。换句话说，你可能依赖了accepts，但你从来没有权利直接使用它。
2.2 严格隔离带来的三个好处
pnpm 用这套严格结构换来了几个实打实的收益。
一是版本冲突不再失控。不同包对同一个依赖的版本要求可能不同，npm 扁平化只能选择一个版本提升到顶层，另一个版本被迫嵌进深层目录；一旦两个包恰好都调用了这个公共依赖，锁文件的变化可能导致某段代码突然解析到另一个版本。pnpm 则让foo@1和foo@2各自待在自己的.pnpm目录下，谁也不干扰谁。
二是磁盘占用明显下降。pnpm 有全局 store，相同版本的包在不同项目间通过硬链接共享，不需要在硬盘上放多份真实副本。严格的结构让这种复用可以放心进行，而一旦全局提升，包可能被以乱七八糟的方式链接到各处，存储复用的收益会大打折扣。
三是强制依赖声明必须诚实。package.json里写了什么，代码才能用什么。这不是团队规范，而是机制本身。它逼着开发者审视自己的依赖，把那些“碰巧能用”的间接依赖彻底清理掉。
但问题也在这。现实世界的项目恰恰没那么诚实，尤其老项目，代码里使用未声明依赖的现象比比皆是。pnpm 接管之后，这些隐藏依赖就像一夜之间被没收了钥匙，全部现出原形。
3. 幽灵依赖，正是提升被人诟病的那颗牙
3.1 幽灵依赖到底是怎么来的
“幽灵依赖”（Phantom Dependency）这个概念，维护过 npm 项目的人多少听过，但真正被它咬到，往往是在切换包管理器的瞬间。
一个典型场景长这样：项目package.json里只声明了webpack和webpack-cli，但某天有人在build/util.js里顺手require('lodash')。在 npm 扁平结构下，lodash作为某个间接依赖早就被提升到了根目录，所以require完全不会报错。没人觉得有问题，因为代码能跑，测试能过，上线也没炸。
直到迁移 pnpm。pnpm 严格模式下，lodash不再出现在公共可见的范围里，build/util.js直接抛错：
Error: Cannot find module 'lodash'此时你一脸懵，因为 package.json 里没有lodash，锁文件里却有几千个包。你以为自己低估了项目复杂度，实际上是项目在一开始就欠下了“幽灵依赖”的债。这种债在 npm 时代不会被追讨，换到 pnpm 时代会被连本带利清算。
更隐蔽的坑在于工具链的隐式查找。有些工具不是从业务代码出发去 require 模块，而是从“约定”出发找插件。比如eslint要去找eslint-plugin-*，babel要去解析babel-preset-*，postcss要自动加载autoprefixer。这些包往往不是项目的直接依赖，而是某个脚手架套件带进来的间接依赖。npm 扁平时它们躺在根目录，工具能找到；pnpm 严格隔离后，工具顺着约定路径一路找过去，发现目标根本不在，于是构建链当场罢工。
3.2 版本冲突的隐雷
幽灵依赖更让人头疼的是版本不确定性。npm 在提升时做的是“尽可能少放重复副本”，这会导致一个现象：两个依赖链分别需要同一个包的不同版本，根目录只保留一个，另一个被嵌进深层。代码在没声明的情况下require这个包，会解析到哪个版本，取决于提升博弈的结果。这个结果一旦随着 lockfile 更新而改变，代码就可能悄悄从使用foo@1.x跳到foo@2.x，行为完全不可控。
这种故障在 npm 时代时有发生，但因为它间歇性出现、不容易复现，很难定位。pnpm 通过隔离把这个问题消解掉了，你用shamefully-hoist=true又把问题请了回来。所以每当我看到有人建议“直接把提升全开就好了”时，都会补一句：你确定你的项目能承受这种不确定性吗？
4. 哪些场景会让你含着泪打开 shamefully-hoist
4.1 三类注定要开全局提升的项目
虽然全局提升不优雅，但确实有一些场景，它是最先能跑通的方式。我从实际帮团队迁移的经验里，总结了三种典型情况。
第一类是历史遗留老项目。这类项目可能运行了几年甚至更久，node_modules里积累了上千个间接包，业务代码里到处是幽灵依赖，依赖声明本身已经失真。即便你想认真治理，工作量也不是一两天能完成的。为了让业务先跑起来，团队往往会选择临时开启shamefully-hoist=true，把兼容性问题先压住，后续再排期治理。这个思路可以理解，但一定要有后续，否则就变成了债务延期。
第二类是工具链必须“向上看”的项目。某些构建工具会从根目录的node_modules寻找插件或加载器。webpack的 loader 配置里写了babel-loader，但项目没有把它显式声明为直接依赖；storybook要加载各种addon，这些 addon 分布在依赖树的深层位置。pnpm 的隔离结构让这些工具无法解析到目标插件，构建链会直接断掉。这种情况用public-hoist-pattern白名单通常能解决，但面对一个混合依赖极多、报错一片的项目，你很难在一开始就精准判断需要放开哪些包，于是先全局提升了再说。
第三类是 monorepo workspace 的特殊洁癖。子包之间如果没有通过workspace:*显式声明互相依赖，而是默认根目录node_modules里能看到所有 workspace 包，pnpm 会让这些“默契失效”。全局提升可以瞬间抹平这个问题，但同样，也只是抹平，并没有解决依赖声明不诚实的事实。
4.2 短期救火与长期代价
把shamefully-hoist=true打开，效果肉眼可见：所有依赖都以符号链接形式出现在根目录node_modules，绝大多数“找不到模块”的报错会消失。但这种消失是有代价的。
最容易想到的代价是幽灵依赖回归。根目录什么都有，开发者在写代码时可以随手 require 任何传递依赖，依赖关系变得彻底不可信。半年后如果有人做依赖清理，只按package.json分析项目，会漏掉一大批实际在用的包，升级或者删除一个看似无关的依赖，可能引发连锁爆炸。
还有一个容易被忽略的代价是安全边界。严格隔离下，一个包只能暴露自己的直接依赖，攻击面相对可控；全局提升后，所有包对业务代码可见，任何一个被间接引入的可疑依赖都可能成为利用链的一部分。在供应链安全问题频发的今天，这不是一个可以随便忽略的点。
所以我的态度很明确：shamefully-hoist=true是一台急用呼吸机，不是长期生命维持系统。你可以用它让项目先喘上气，但接下来的事比打开开关更重要。
5. 配置方式与替代方案，先看白名单
5.1 最小可行的配置：public-hoist-pattern 白名单
如果你确认自己的项目必须通过提升来解决兼容性，我的建议是先别直接按核弹开关，试试更精准的方案。
.npmrc里可以这样配：
public-hoist-pattern[]=*eslint* public-hoist-pattern[]=*prettier* public-hoist-pattern[]=*babel*shamefully-hoist本质上等价于把public-hoist-pattern设置成*，也就是全部依赖都提升。而白名单模式只把符合匹配规则的包提升到根目录，比如*eslint*会把所有包含eslint字样的依赖目录暴露出去，让 eslint 插件机制能正常工作，同时其他包仍然保持严格隔离。
还有另一个配置hoist-pattern，也能实现类似的提升效果，但在可见范围上和public-hoist-pattern有细微差别。具体选择需要看你的工具链解析机制到底找的是哪一层目录，我一般会以public-hoist-pattern作为首选，因为它更贴近“公共可见”这个语义。
如果连白名单都救不了，还有一个终极兼容方案：node-linker=hoisted。这个配置会让 pnpm 在安装时直接生成传统意义的扁平node_modules目录，几乎百分百兼容 npm 时代的依赖解析习惯。但代价是彻底放弃 pnpm 的严格结构和大部分优化收益，我只建议把老项目临时当作“更快一点的 npm”用，不适合长期冷战。
5.2 从宽松到严格的落地顺序
我在实际操练项目中，通常会按下面这个顺序落地：
- 先不开任何提升，直接跑
pnpm install； - 把报错信息收集起来，逐个把缺失的包补进
package.json的dependencies或devDependencies； - 对工具链插件这类需要向上查找的包，用
public-hoist-pattern补白名单； - 如果剩余报错仍然太多，再临时开启
shamefully-hoist=true，同时记录一个技术债，安排时间逐步收窄； - 每次收窄后，把这轮改动提交前先跑一遍完整构建和测试。
这个顺序的核心逻辑是：每一条报错都是一个线索，它告诉你项目里有哪些依赖是不诚实的。一开始就开启全局提升，等于把这些线索全部掩埋，后续再也无从查起。
6. 一次实际迁移：从全面提升到逐步收紧
去年我帮一个老 Vue 项目迁移 pnpm，完整经历了一遍从“含泪开启”到“小范围白名单”的复盘，很多感受写出来给同样要踩坑的人参考。
那个项目是两年前的 Vue CLI 构建链，核心依赖是webpack、vue-loader、vue-template-compiler，下面还挂了一串 redux、postcss 和 babel 包。我一开始就把.npmrc写成了最简单粗暴的形式：
shamefully-hoist=true第一轮安装很快完成，构建也能跑通。但我知道这种成功是虚幻的，所以等应用稳定跑了一段时间后，我花了一个下午做了三件事。
第一件事，拉出全量依赖关系。用pnpm list --depth 4看依赖树，配合在src目录里全局搜索from 'xxx'和require('xxx')，把每个模块名和package.json的dependencies字段做对比。如果用的是 TypeScript，还可以用knip这类工具自动检测未声明的依赖，效率高很多。
第二件事，逐项补齐。lodash、moment这类通用工具包，直接补进dependencies；autoprefixer、postcss-preset-env这类构建期依赖，补进devDependencies。eslint 生态的插件则比较特殊，它们依赖的是“工具向上查找插件”的约定，我最终决定保留对这些插件目录的提升。
第三件事，关闭全局提升。把.npmrc里的shamefully-hoist=true删掉，换成：
public-hoist-pattern[]=*eslint* public-hoist-pattern[]=*prettier*去掉shamefully-hoist后重新安装，项目依然能跑。那一刻我才确定，这个项目的依赖声明已经恢复到可以审计的状态，报错信息也不再是被掩盖的定时炸弹。
经历这轮折腾，我最大的感触是：shamefully-hoist=true本身不是错误，它只是一个工具型开关，错误在于很多人把它当成默认配置而不是应急方案。如果你正打算给老项目引入 pnpm，先别急着把这行配置抄进.npmrc。认真看一遍安装报错，那些报错会告诉你项目在依赖治理上欠了哪些账；还清这笔债，比永远开着一个“羞耻开关”要踏实得多。
