企业官网建设流程全解析

第一次被问到“pnpm 怎么做到没声明就不能用”时，我其实也答得不够好。当时面试官先问“项目为什么用 Monorepo”，我按常见套路回答代码复用、统一管理、构建效率高；又追问“pnpm 的优势是什么”，我说依赖隔离、安装快、节省磁盘；对方继续追问“那 pnpm 是怎么做到‘没声明就不能用’的”，我卡住了。

现在回头看，这道题真正考察的不是“能不能背出结论”，而是“能不能把包管理器的依赖解析机制讲清楚”。这也是很多候选人容易吃亏的地方：名词都会说，但落到原理层面，讲不出依赖提升、符号链接、全局存储之间的关系。只要把 Monorepo 的背景、pnpm 的 node_modules 结构、幽灵依赖的成因这三件事串起来，这个问题就会变得很顺。这篇文章把三个问题放在一起拆，同时结合我在实际仓库里切换到 pnpm 时踩过的坑，最后给一套可以直接用的面试答题框架。

1. 面试官问这个问题，不是让你背概念

1.1 表面问题背后的考察点

面试官问“项目为什么用 Monorepo”，表面上是问工程架构选型，实际上是在考察你对代码组织和依赖管理的理解深度。很多项目确实在用 Monorepo，但如果候选人只是因为在网上看到“Monorepo 好”就写进简历，那这个问题就会变成一面照妖镜。

真正需要回答清楚的是三层逻辑：

• 第一层：Monorepo 解决什么问题，适合什么团队。
• 第二层：多个包放在同一个仓库后，依赖管理会遇到什么新问题。
• 第三层：为什么选择 pnpm，它的工作机制相比 npm 和 yarn 做了哪些核心改变。

这三层一层比一层深。只答第一层，面试官会觉得你有经验但没复盘；能答到第三层，才会让对方觉得你真的在思考依赖管理这件事。

“pnpm 的优势是什么”也一样。候选人最常见的回答是“安装速度快、节省磁盘空间、依赖隔离”，这三个方向没有问题，问题在于这些只是结果，不是原因。面试官想知道的是：速度快是因为什么？省磁盘是因为什么？依赖隔离又是靠什么机制实现的？如果答不出“内容寻址存储”和“符号链接”，这个回答就停留在表面。

1.2 常见答案差在哪

我在真实面试里听过很多类似回答。候选人说“Monorepo 方便代码复用”，这个说法本身对吧？对，但太笼统。什么样的代码可以被复用？怎么复用？是直接 import 源码还是发私有包？版本怎么同步？如果这些细节答不出来，这句话就只是一句广告语。

再比如“pnpm 依赖隔离”，这句话也偏模糊。隔离的是什么？是磁盘存储还是依赖之间的可见性？pnpm 的隔离模式和 npm 的隔离模式有什么区别？如果不清楚 node_modules 里到底长什么样，面试官就会继续追问，直到问出“幽灵依赖”这个词。

所以，一个能让面试官满意的回答，至少要包含四件事：

• Monorepo 的收益边界，包括什么时候不建议用。
• pnpm 的存储引擎，包括全局 store、硬链接、符号链接。
• pnpm 的依赖可见性规则，也就是“声明了才能用”。
• 幽灵依赖的成因和危害，能讲出一个具体事故案例。

1.3 “怎么做到”这个问题到底在问什么

面试官追问“pnpm 怎么做到‘没声明就不能用’”，其实是在问两件事：

1. pnpm 的 node_modules 目录结构是什么样的。
2. Node.js 的模块解析机制在这种结构下如何工作。

只要能把这两点讲明白，对方就会认为你是真正理解 pnpm 的，而不是背了几个关键词。这也是这篇文章后续要重点展开的内容。

我的建议是，面试前不要在纸上画几个箭头就算复习完，最好找个空目录模拟一次 pnpm install，然后打开 node_modules 看一遍。看一遍目录结构，比背十篇面试题都有用。

2. Monorepo 的价值和边界：先想清楚为什么聚，再谈怎么管

2.1 Monorepo 的核心收益

Monorepo 的核心思路是把多个包、多个应用放在同一个 Git 仓库里统一管理。它带来的收益不是“代码放在一起”这么简单，而是几个非常实际的工程价值：

第一是代码复用。多个应用共享的 UI 组件、工具函数、类型定义，可以直接通过源码引用或者 workspace 协议引用，不需要每次改动都发一个 npm 包、再跑一遍发布流程。这一点在业务代码多、依赖关系复杂的团队里尤其明显。

第二是原子提交。一个需求可能同时要改公共库、后端接口、前端页面。在独立仓库的模式下，得拆成多个仓库、多个 MR，对应关系靠人肉维护；在 Monorepo 模式下，一次提交可以同时覆盖所有相关改动，回滚也更方便。

第三是统一的依赖管理和脚本流程。根目录一份配置可以管理所有子包的依赖版本，公共的 CI 流程、代码检查、构建工具只需要维护一份。团队新成员加入时不需要逐一了解每个仓库的构建差异。

第四是变更影响可视化。通过依赖图分析，可以很容易看出某个公共模块被哪些包依赖，改了它到底影响什么范围。

2.2 不是每个团队都适合 Monorepo

Monorepo 也有很多边界。一个只有两个应用、几乎不共享代码的团队，上 Monorepo 不一定是增值，可能只是增加仓库体积和 CI 时间。团队规模如果很大，权限管理也会变复杂——原本不同团队各自掌握自己的仓库，现在所有人都要在一个仓库里协作。

我见过一些团队冲进 Monorepo 之后发现的问题：

• 仓库越来越大，Git 操作越来越卡。
• CI 上任何一个小改动都跑全量检查，等待时间偏长。
• 子包之间的隐式依赖太多，甚至出现循环依赖。
• 老项目从 npm 迁移到 pnpm 时，很多包没有正确声明依赖，一上隔离模式就报错。

这几点不等于 Monorepo 不好，而是要说明：Monorepo 不是银弹。选择它之前必须确认，代码共享和跨项目协作确实是团队的痛点。

2.3 Monorepo 对包管理提出了新要求

多个包放在同一个仓库后，最直接的问题是依赖管理。如果每个子包都各自 install 一遍，会产生大量重复安装，磁盘和多项目缓存都无法复用。如果采用 npm 的扁平化依赖提升，包之间的依赖边界又会变得模糊。

这时 pnpm workspace 的优势就体现出来了。它可以做到：

• 多个 workspace 子包共享同一个全局依赖存储。
• 同一个版本的依赖只要下载一次，其他包通过硬链接复用。
• 每个子包仍然保持独立的依赖声明，不允许访问自己没有声明的包。

换句话说，Monorepo 需要“既能一起管理，又要彼此隔离”，pnpm 的机制正好同时满足了这两点。

3. pnpm 的优势不只是快：内容寻址存储和链接机制

3.1 npm 和 yarn 的 node_modules 到底浪费在哪

要理解 pnpm 的做法，得先看 npm 和旧版 yarn 的问题。

npm 使用扁平化的 node_modules 结构。安装依赖时，它会把所有依赖的依赖都尽量提升到顶层 node_modules 目录下。这样做的好处是兼容性好，坏处也很明显。

假设项目 A 和项目 B 都安装了自己独立的依赖，两个项目各有一份 node_modules。如果两个项目都依赖同一个版本的 lodash，那磁盘上就会存在两份 lodash 文件。项目多了之后，这种重复会非常夸张。

更麻烦的是依赖提升的不确定性。npm 提升哪些依赖到顶层，取决于安装顺序和版本冲突。同一个项目在不同的环境中安装，得到的目标目录结构可能不一样，这给复现和排错增加了难度。

3.2 pnpm 的内容寻址存储和硬链接

pnpm 的思路完全不同。它使用一个全局的 store 目录来保存所有下载过的包文件。这个 store 不放在项目内部，而是放在用户目录下，所以多个项目可以共享同一份包内容。

安装依赖时，pnpm 并不会把包文件完整复制到项目里，而是通过硬链接把文件从全局 store 链接到项目的 node_modules/.pnpm 目录中。硬链接的意思是，多个路径指向磁盘上同一份物理数据，项目里看到的其实是同一个文件的另一个入口。

这样带来两个直接效果：

• 节省磁盘空间。同一份文件在磁盘上只存一次，多个项目引用时不会重复占用。
• 安装速度快。硬链接是本地文件系统操作，比从网络下载快得多；只有在全局 store 中没有对应版本时，才需要真正去 registry 拉取。

注意，这里说硬链接是“节省磁盘”的关键手段，但并不是说每个文件都一定要用硬链接。某些情况下 pnpm 会退回复制方式，比如不同磁盘分区之间无法创建硬链接时。实际使用中看到“重新链接”而不是“重新下载”，可以判断安装过程确实复用了存储。

3.3 符号链接如何构造依赖树

pnpm 除了用硬链接关联 store 中的真实文件，还需要用符号链接来组织依赖树。

符号链接和硬链接不同。硬链接是文件系统层面的别名，符号链接则是一个路径指向另一个路径。pnpm 用符号链接解决的核心问题是：让每个包只能找到自己声明的依赖，同时保证代码运行时不依赖顶层提升。

安装结果可以简单理解成：项目 node_modules 顶层只放了直接在 package.json 里声明过的依赖，每个依赖是一个符号链接，指向 .pnpm 目录里对应的真实包目录。真实包目录里，这个包自身的依赖又通过下一层符号链接指向 .pnpm 中的其他包目录。

这种结构让 pnpm 既能做到统一存储、节省空间，又能做到依赖隔离：包 A 内部有一套自己的依赖链接，包 B 内部也有一套，互不干扰。

4. 幽灵依赖：依赖提升制造的假成功

4.1 什么是幽灵依赖

幽灵依赖这个词听起来很玄，其实非常具体。它指的是：代码里 import 了一个包，但这个包并没有在项目 package.json 的 dependencies 或 devDependencies 中声明，却能正常运行。

这种“没声明但能用”的依赖，就是幽灵依赖。它的存在是 npm 依赖提升机制的直接产物。

npm 在安装时会做依赖提升。项目声明了依赖 A，A 又依赖 B。npm 把 A 和 B 都放到了项目根目录的 node_modules 顶层。此时项目代码虽然只声明了 A，却可以直接 import B，而且能跑起来。

4.2 一个非常常见的场景

我自己在接手一个老项目时遇到过类似问题。项目 package.json 里声明了 axios，但代码里还用了几个 lodash 的工具函数。当时所有人都以为 lodash 在依赖里，直到某次 npm install 之后版本变化，lodash 没有被提升到顶层，项目瞬间跑不起来了，一堆 import 报错。

去看 package.json 才发现，lodash 从头到尾都没被声明过。它以前能被 import，只是因为某个间接依赖把 lodash 带到了顶层 node_modules。一旦这个间接依赖升级或者移除，幽灵依赖就会立刻现形。

如果把幽灵依赖暴露在面向用户的流程里，后果会更严重。比如 CI 上安装规律和本地不一致，本地能跑，CI 上构建失败；或者测试环境能跑，生产环境打包失败。这种问题非常让人头疼，因为它不报“缺依赖”，而是报出一堆看起来和依赖无关的错误。

4.3 幽灵依赖的真实危害

幽灵依赖的主要危害可以归纳成三块。

第一是版本失控。幽灵依赖的版本不由你的项目决定，而是由别人的依赖传递规则决定。你无法锁定它，也就无法保证项目长期可复现。

第二是升级恐惧。当某个间接依赖升级后不再提供你 import 的 API，项目会突然崩溃。排查时很难第一时间想到“我根本没声明它”。

第三是迁移成本。从 npm 切换到 pnpm 后，很多“能跑的项目”会突然报错，原因就是以前被提升到顶层的幽灵依赖，在 pnpm 的隔离结构下不再对项目根目录可见。

从 npm 迁移到 pnpm 时，我通常建议先做一次依赖完整性检查。把所有代码里出现过的 import 来源全部提取出来，和 package.json 逐一核对，找到未声明的依赖再补进去。这一步虽然繁琐，但能在真正迁移前把隐患暴露清楚。

5. pnpm 怎么做到“没声明就不能用”：目录结构和解析机制

5.1 从一次 install 后的 node_modules 看起

直接看目录结构是最容易理解的。假设项目声明了 lodash 和 axios，其中 axios 依赖 follow-redirects，pnpm 安装后的 node_modules 大概长这样：

node_modules ├── .pnpm │ ├── lodash@4.17.21 │ │ └── node_modules │ │ └── lodash -> <store>/lodash@4.17.21 │ ├── axios@1.7.2 │ │ └── node_modules │ │ ├── axios -> <store>/axios@1.7.2 │ │ └── follow-redirects -> ../../follow-redirects@1.15.6/node_modules/follow-redirects │ ├── follow-redirects@1.15.6 │ │ └── node_modules │ │ └── follow-redirects -> <store>/follow-redirects@1.15.6 │ └── ... ├── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash └── axios -> .pnpm/axios@1.7.2/node_modules/axios

项目根目录的 node_modules 顶层只有 lodash 和 axios 这两个符号链接，因为它们出现在 package.json 的 dependencies 中。follow-redirects 虽然也被安装到了 .pnpm 目录里，但它只出现在 axios 的依赖链接中，不会暴露在项目顶层。

这就是“没声明就不能用”的第一个关键：项目代码在模块解析时，沿着当前目录向上查找 node_modules，却发现顶层只有一个又一个你声明过的包的符号链接。如果你直接写import 'follow-redirects'，Node 在项目 node_modules 下找不到对应的顶层入口，就会继续往上层的 node_modules 找，最终大概率报错。

5.2 为什么代码找不到未声明的包

Node.js 的模块解析规则是：从当前文件所在目录开始，逐级向上查找 node_modules 目录，并在 node_modules 下匹配包名。pnpm 把未声明的包藏在 .pnpm 目录里，但这并不是一个 Node 正常解析时会扫描的目录。

有人可能会问：.pnpm 目录下的包确实存在，为什么不能直接找到？因为 Node 解析时去找的是node_modules/follow-redirects，而不是node_modules/.pnpm/follow-redirects@1.15.6/node_modules/follow-redirects。包名对应的顶层入口不存在，解析就会中断，除非你手动写完整路径，但那已经偏离了正常用法。

所以 pnpm 的隔离并不仅仅是“把文件藏起来”，而是通过符号链接改变了 node_modules 的可见性。每一层符号链接都严格对应声明关系，这让“未声明不可见”成为默认规则。

5.3 peerDependencies 和公共提升怎么处理

看到这里你可能会有疑问：pnpm 做得这么严格，那 peerDependencies 怎么办？很多插件库要求在宿主项目里拿到某个依赖，比如 React 组件库需要拿到 React 实例。如果完全隔离，插件就无法访问宿主项目的依赖。

pnpm 的处理方式是把 peerDependencies 也以符号链接形式放到对应包目录下的 node_modules 中。这样，插件在自己的依赖搜索路径里能找到 React，但这些 React 并不会暴露到项目顶层，其他未声明 React 的包依然不能随意引用。

另外，pnpm 默认也可能对少量工具做公共提升，比如 eslint、prettier 这类需要被插件加载的工具。这是通过.npmrc中的public-hoist-pattern控制的。默认提升范围一般比较克制，主要面向工具链，而不是业务依赖。

如果某些老项目实在无法彻底清理幽灵依赖，pnpm 也提供了shamefully-hoist=true配置，开启后会让 node_modules 结构退化成 npm 式的完全提升。这是一个兼容方案，可以用于过渡，但不建议长期开启，因为一旦开启就等于放弃了 pnpm 的依赖隔离优势。

真正生产项目中，我更建议先花时间补齐依赖声明，而不是一上来就开shamefully-hoist。隔离带来的初期迁移成本，往往能避免后续更隐蔽的运行时问题。

6. 实战：pnpm workspace 搭建 Monorepo 的落地步骤

6.1 初始化工程结构和 workspace 配置

如果从零开始搭一个 pnpm workspace 的 Monorepo，步骤其实很直接。先创建一个根目录，在里面放一个pnpm-workspace.yaml，声明哪些子目录属于 workspace：

packages: - 'apps/*' - 'packages/*'

这个配置表示apps和packages下的所有子目录都会被识别为独立的包。根目录的 package.json 可以放一些公共脚本和公共依赖。

子包之间如果要互相引用，可以直接使用workspace:*协议。比如packages/utils的 package.json 中声明：

{ "name": "@my-app/utils", "version": "1.0.0", "main": "src/index.ts" }

另一个应用apps/web要使用它，可以在 dependencies 中写：

{ "dependencies": { "@my-app/utils": "workspace:*" } }

workspace:*的意思是：这个依赖在工作区内找当前版本，而不是去 npm registry 下载。本地实时调试非常方便，改动 utils 源码后，web 应用会直接使用最新源码。

6.2 安装依赖、过滤命令和批量脚本

安装所有子包依赖，只需要在根目录执行：

pnpm install

给某个具体包添加依赖时，用--filter指定包名：

pnpm add lodash --filter @my-app/web

运行某个子包的命令：

pnpm --filter @my-app/web run dev

批量执行所有子包的构建：

pnpm -r run build

过滤命令还可以配合范围使用，比如只跑受影响包相关命令。实际项目中，pnpm 会分析 workspace 内的依赖图，执行时能够减少很多无谓的重复构建。

pnpm -r run build会按照依赖顺序自动从底向上执行。也就是说，先构建被依赖的公共包，再构建依赖它们的应用，省去手动排列顺序的麻烦。

6.3 从 npm 迁移时的关键注意点

从 npm 切换到 pnpm，最稳的路径是先在分支上操作，不要直接在生产主流程里切换。

需要做几件事：

• 备份并删除旧依赖锁定文件，例如package-lock.json、yarn.lock。
• 删除所有子包和根目录的node_modules。
• 确认 Node 版本满足当前 pnpm 版本的要求。
• 在根目录执行pnpm install。
• 全局搜索代码中是否有未声明的幽灵依赖，提前补齐。

迁移过程中最容易报错的就是幽灵依赖。因为 npm 的扁平化结构让很多包在顶层可用，切换到 pnpm 后这些包不再暴露。看到ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND或模块找不到之类的错误时，先不要怀疑 pnpm 有问题，优先检查 packages 路径配置和依赖声明。

如果是老项目，建议在项目根目录生成一个.npmrc配置文件，把必要的基础配置统一放到这里：

registry=https://registry.npmmirror.com/ fetch-retries=5 fetch-timeout=60000 network-concurrency=8

这是一个通用的配置示例。registry 改成你团队实际使用的镜像源即可。fetch-timeout和network-concurrency是为了应对安装超时和下载并发过高的情况。不同网络环境需要调多少参数，实际操作时按报错情况调整。

7. 面试答题框架与高频坑位

7.1 面试时的一分钟版本和两分钟版本

如果面试官只给一分钟，我会这样回答：

Monorepo 解决的是多包代码复用和统一管理的问题，但多个包放一起后，需要包管理工具同时支持共享存储和依赖隔离。pnpm 用全局 store 加硬链接解决重复下载和磁盘占用，用符号链接把每个包自己的依赖关系组织在.pnpm目录中，项目根目录只暴露 package.json 中声明过的依赖。因此未声明的依赖在模块解析时找不到入口，也就不能被代码直接引用。这从根本上避免了幽灵依赖。

如果面试官没有打断，可以继续补充两分钟版本：

pnpm 的 node_modules 不是扁平化的，而是三层结构。全局 store 保存真实文件，硬链接保证同一文件只在磁盘放一份。.pnpm目录中是每个包的真实模块目录，包内部再通过符号链接连接自己的声明依赖和 peerDependencies。项目根目录顶层只放直接依赖的符号链接。这种结构保证了依赖可见性边界非常清楚，同时让安装变得更快。

回答时尽量把“符号链接”“全局 store”“依赖提升”这几个关键词自然说出来，它们能证明你真的了解原理。

7.2 面试官可能继续追问的方向

追问题不一定难，但需要准备：

第一，pnpm 会不会也做依赖提升？这个问题很重要。pnpm 默认不会做 npm 那种完全的扁平化提升，但public-hoist-pattern和shamefully-hoist可以影响提升行为。回答时要说明，默认的依赖隔离是强约束，如果遇到兼容性问题，可以做有限度的公共提升，完全提升是一个逃生舱口。

第二，peerDependencies 怎么解析？可以按照 5.3 节的逻辑回答，peerDependencies 会被链接到对应包的依赖搜索路径中，但不会暴露到项目顶层。

第三，workspace 的workspace:*协议怎么工作？本地用 workspace 版本，发布时会被替换为实际版本号。这一点能体现你是否真正用过 pnpm workspace。

第四，CI 中如何利用 pnpm 缓存？核心思路是让 pnpm store 在 CI 中保留，配合硬链接减少重复下载。具体缓存策略取决于 CI 平台，可以提到“可以在 CI 中复用 store 目录”，但不要给出不存在的官方数据。

7.3 开发环境里的几个高频坑

我在实际使用 pnpm 时遇到最多的问题，反而不是依赖隔离本身，而是几个很基础的环境问题。

第一个是 Windows 下提示“pnpm 不是内部或外部命令”或者“无法识别 pnpm 项”。这个问题通常是安装方式导致的。如果使用 corepack，可以先执行：

corepack enable

然后重新打开终端，执行pnpm -v。如果是通过 npm 全局安装的，要确认 npm 全局 bin 目录已经加入了系统 PATH：

npm config get prefix

然后把输出目录加到 PATH 里。排查顺序应该是：先确认安装是否成功，再确认 PATH 是否正确，最后重新打开终端验证。

第二个是 Node 版本不满足。新版本 pnpm 对 Node 有最低版本要求，比如安装一个较新的 pnpm 版本，可能要求 Node 版本在 v22 以上。启动项目时如果看到类似this version of pnpm requires at least node.js v20的错误，说明本地 Node 版本偏旧，先升级 Node 再继续，不要急着重装 pnpm。

第三个是安装超时和下载慢。这个问题在依赖源不稳定时很常见。可以在.npmrc里配置更稳定的 registry 镜像，也可以调大fetch-timeout和重试次数。要注意，不同环境的网络差异很大，配置值没有统一标准，按实际报错调整。

第四个是原生依赖构建被拦截。pnpm 出于安全考虑，默认会阻止依赖安装脚本执行。安装某些含原生代码的包时，终端可能提示需要运行pnpm approve-builds。这时候按指示执行，选择允许哪些依赖运行安装脚本即可。这个问题很容易被误判成“pnpm 无法安装某个包”，其实只是安全策略需要确认。

第五个是构建产物部署到 nginx。前面走pnpm build得到的只是静态文件目录，部署时要确认后端服务和 nginx 配置指向正确的 dist 目录。这一环节如果出问题，根因通常是路径配置或前端路由使用 history 模式导致的回退问题，和 pnpm 的关系不大。

7.4 遇到问题时的通用排查顺序

最后给一个我自己比较常用的问题排查顺序：

1. 先看报错类型。是命令识别不了，还是安装失败，还是运行时模块找不到。
2. 再确认 Node 版本和 pnpm 版本，是否满足项目要求。
3. 然后检查.npmrc中的 registry、超时、并发参数。
4. 再检查pnpm-workspace.yaml的路径配置，是不是包没有进入 workspace 识别范围。
5. 如果运行时报模块找不到，优先查 package.json 里有没有声明该依赖，再查 node_modules 的链接是否正确。
6. 最后检查是否涉及依赖安装脚本的执行权限，必要时执行pnpm approve-builds。

这个顺序可以解决大部分 pnpm 相关的环境问题。核心原则是先区分“环境问题”和“依赖声明问题”，不要把所有报错都归因到 pnpm 本身。

回到最开始的问题。面试官问“pnpm 怎么做到没声明就不能用”，最直接的回答是：pnpm 通过符号链接改变了 node_modules 的可见性，顶层只暴露声明过的依赖，未声明的包在正常模块解析路径中不存在入口。理解到这一层，就已经超过了“背概念”的阶段。如果还能在实战中讲清楚依赖提升、幽灵依赖、workspace 配置和迁移坑点，这道题基本就稳了。