企业官网建设流程全解析

“Monorepo、pnpm、幽灵依赖、依赖隔离”，这组词近几年几乎成了前端进阶面试的必考题。项目问到“为什么用 Monorepo”，候选人答“代码复用”；问到“pnpm 相比 npm 的优势”，候选人答“速度快、节省磁盘、依赖隔离”。听起来都对，但面试官一旦追问“pnpm 怎么做到没声明就不能用”，很多人就开始含糊。有人说是用了软链接，有人说是把依赖放在全局目录，但真正能把“.pnpm 目录、符号链接、Node 模块解析规则”三件事串成完整因果链的，其实不多。我想从这套机制说起，把 Monorepo、pnpm 和幽灵依赖放到同一个问题背景下拆开讲，最后再落到实际工程里的安装、镜像、版本和构建部署。

1. 先想清楚：Monorepo 到底把问题变简单了，还是变复杂了

Monorepo 不是一个新概念，Linux 内核、Google 的大量代码都放在单一代码库里。但在前端领域，长期以来默认是 MultiRepo：每个项目一个 Git 仓库，组件库一个仓库，工具函数一个仓库。当你需要同时修改组件库和业务项目时，要经历发版、升级依赖、再部署这一整套流程。Monorepo 则是把多个相关包放进同一个仓库，用 workspace 机制统一管理。

很多人一说到 Monorepo 就想到“代码复用”，这没有错，但它只是表面收益。真正值得关注的是协作边界的改变：一次提交可以包含跨项目的代码变更，组件库和业务代码可以同时改、同时验、同时发布。这才是 Monorepo 对研发流程最有冲击力的地方。

1.1 代码复用不是重点，原子变更才是

在多仓库模式下，一个跨包改动通常长这样：先在组件库仓库改代码、发版本，再到业务项目里升级依赖、修兼容问题，然后部署。如果中间有任何一步发现新版本有 Bug，又要回滚组件库、重新发版、再升级。两三个包还能接受，包一多，这种串联等待会耗费大量时间。

Monorepo 的“原子变更”价值在于：一次提交把组件库、业务代码和测试用例一起改完，CI 可以基于这次提交做整体验证。如果构建失败，就不允许合入，避免了“单独看每个包都正常，组合在一起就出问题”的尴尬。

从这个角度看，代码复用只是把多包放进同一个仓库的副产品，真正解决的是“多个包需要一起演进”时的协作效率问题。面试题里只答“代码复用”，等于只看到了最浅的一层。

1.2 为什么过去 Monorepo 推行不起来

Monorepo 过去难做，主要卡在依赖管理和构建效率上。如果所有包都共享同一个 node_modules，依赖冲突会很难处理；如果每个包各自维护 node_modules，磁盘占用和安装时间又会成倍增长。用 npm 或 yarn classic 管理 workspace 时，“依赖提升”策略还会让包之间的边界变得模糊。

pnpm 之所以成为 Monorepo 的主流选择，不是因为它的安装命令写起来好看，而是因为它重新设计了 node_modules 布局，让“多个包共享同一份依赖”和“包之间依赖隔离”这两个看似矛盾的需求同时成立。理解了这一点，才能理解 pnpm 在 Monorepo 里的真正价值：它不是让代码复用变得更方便，而是让依赖关系变得可预测。

2. pnpm 的“快”和“省”，不是安装技巧，而是另一套存储模型

pnpm 经常被提到的两个词是“快”和“省磁盘”。这两个结论是对的，但很多人没有解释清楚背后的原因。pnpm 并不是通过多线程下载或者压缩体积做到这一点的，它改变的是依赖文件在磁盘上的组织方式。

2.1 npm 扁平化 node_modules 的代价

npm 在 v3 之后采用扁平化依赖策略：尽可能把所有包都提升到项目顶层的 node_modules。设计初衷是为了缩短模块解析路径，避免嵌套 node_modules 带来的深层路径问题。但副作用也很明显：一个项目里会有大量重复文件，不同项目之间又各自保有一份副本。装完一个项目可能 800MB，再装第二个项目还是 800MB，磁盘和时间都被浪费。

还有一个更隐蔽的问题：扁平化导致项目代码可以访问到很多没有在 package.json 中声明的包。这就是后面要讲的幽灵依赖。npm 的扁平化策略，本质上牺牲了“依赖可见性”来换取“安装简单”，而这个牺牲会在项目中型化以后逐渐变成成本。

2.2 全局 store 与硬链接：速度快省磁盘的真正原因

pnpm 的所有下载内容都会先保存到一个全局 store 中，存储方式是按文件内容哈希寻址。也就是说，同一个版本的同一个包，无论被多少个项目使用，在 store 里都只有一份。安装到某个项目时，pnpm 通过硬链接把 store 中的文件链接进项目目录，而不是重新复制文件。

因此第二次安装相同依赖时，根本不需要从网络下载，也不需要在磁盘上重新写入一遍，只需要创建链接。这在 Monorepo 场景下尤其有优势：多个 workspace 包引用同一个版本的 React、Vue、lodash 时，整个仓库只保存一份实际文件。

你可以用pnpm store path查看当前 store 的位置。CI 缓存 pnpm 安装速度时，缓存 store 目录往往比缓存 node_modules 更有效。

2.3 快是有边界的

需要说明的是，硬链接依赖文件系统和磁盘分区。如果项目挂载在容器卷、网络文件系统或一些特殊存储上，硬链接可能无法正常工作，pnpm 会退化成复制模式，这时安装速度和磁盘占用就未必能保持最优。换句话说，“pnpm 一定比 npm 快”这个结论，不是在所有环境下都成立。

所以在实际使用中，建议先在小项目里验证。如果当前环境恰好是网络存储或特殊 CI 文件系统，注意观察 pnpm 输出的链接方式或日志，必要时通过配置调整安装策略。这不是 pnpm 的问题，而是文件系统边界问题。

3. 幽灵依赖：npm 扁平化留下的雷，pnpm 为什么能拆掉它

如果说 Monorepo 是“为什么要重构工程结构”的宏观问题，那幽灵依赖就是“为什么旧的依赖管理方式不可持续”的微观证据。幽灵依赖是面试高频点，也是工程事故里不容易排查的一类问题。

3.1 幽灵依赖是怎么产生的

npm 的扁平化策略会把所有包的传递依赖尽量提升到顶层 node_modules。比如项目声明依赖 A，A 内部依赖 B。按 npm v3 之后的行为，B 可能被直接提升到项目顶层 node_modules。此时项目代码虽然没有安装 B，却可以直接import B。

这就是幽灵依赖：代码里用到的包，在 package.json 中“不存在”。它看起来很方便，因为省了一步显式声明，但隐患极大。B 是 A 的私有依赖，A 升级后 B 可能被换成新版本、被去重、甚至被移除。一旦结束，项目代码引用的“幽灵”就会消失，程序可能直接在线上运行时报Cannot find module 'B'。

3.2 为什么它比版本冲突更隐蔽

版本冲突通常能在安装阶段、类型检查阶段或构建阶段暴露出来，报错信息指向清晰，人工干预相对容易。幽灵依赖则不同：它在安装阶段一切正常，因为 node_modules 里确实存在那个包；在开发阶段也正常，因为 IDE 能解析到。直到部署到新环境、或者某个间接依赖升级后，突然崩溃。

排查时你会发现，node_modules 顶层有一个包，却说不清是谁安装的，也不敢删。你不知道它对应用代码意味着什么，只能沿着引用链一层层往上翻。这种不确定性，比一个明明白白的版本冲突更难处理。

3.3 pnpm 如何做到“没声明就不能用”

pnpm 解决幽灵依赖的核心策略很简单：不让传递依赖出现在项目顶层 node_modules。

项目顶层 node_modules 里只保留 package.json 中直接声明的依赖，而且这些依赖通常不是真实目录，而是指向.pnpm目录的符号链接。传递依赖被安置在.pnpm/<包名>@<版本>/node_modules/这样的内部路径下，只对真正需要它的父包可见。

项目代码试图 import 一个未声明包时，Node 会在当前目录向上查找 node_modules，顶层没有这个包，解析就会失败。于是“没声明就不能用”变成了一种物理隔离效果，而不是某个 lint 规则或团队约定。

4. 把 .pnpm 目录拆开看，依赖隔离模型到底是什么样子

理解 pnpm 的关键，是理解.pnpm目录的布局和符号链接在其中的作用。光记住“pnpm 用了符号链接”不够，要能说清楚链接从哪里来、链到哪个位置、Node 又按什么规则解析它。

4.1 一张目录结构图看清 .pnpm

假设项目只安装了 express 和 lodash 两个直接依赖，express 内部依赖 send。简化后的 node_modules 结构如下：

node_modules ├── .pnpm │ ├── express@4.18.2 │ │ └── node_modules │ │ ├── express │ │ └── send -> ../../send@0.18.0/node_modules/send │ ├── send@0.18.0 │ │ └── node_modules │ │ └── send │ └── lodash@4.17.21 │ └── node_modules │ └── lodash ├── express -> .pnpm/express@4.18.2/node_modules/express └── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash

顶层express和lodash是符号链接，真实文件在.pnpm目录里。express自己的依赖send不会出现在顶层 node_modules，只存在于express@4.18.2/node_modules/send这个内部路径下。

4.2 Node 的模块解析为什么会顺着符号链接找到包

Node.js 在解析模块时，会从当前文件所在目录开始，逐级向上查找node_modules目录。项目顶层代码执行require('express')，会找到顶层符号链接，进入真实路径.pnpm/express@4.18.2/node_modules/express。

当 express 内部执行require('send')时，Node 会从 express 的真实位置开始，向上一级找到.pnpm/express@4.18.2/node_modules，发现 send 符号链接存在，于是解析成功。而项目顶层代码执行require('send')时，Node 从项目根目录向上找，顶层 node_modules 里没有 send，所以直接报错。

这就是 pnpm 严格模式的本质：不是文件不存在，而是“对谁可见”被精确控制。每个包只能看到自己声明过的依赖，以及这些依赖自己的内部依赖关系。

4.3 peer dependencies：严格模型的边界

越是严格的模型，越需要处理例外情况。peer dependencies 就是典型的例外：它要求两个包共享同一个外部依赖实例，比如 React 组件库要求使用方提供 React 作为 peer dependency。

pnpm 在解析 peer dependencies 时，会根据使用方的实际依赖情况为每个上下文生成对应的链接。如果同一个仓库里不同包对 peer 的版本要求不一致，就可能出现同一个库的多份实例。这在 React、Vue 这类要求“全局单例”的生态里尤其要小心。

所以 pnpm 并不是万能银弹。它把“依赖可见性”管得很严，但开发者也必须理解 Node 模块解析、理解 peer dependency 的语义。依赖隔离解决的是可见性问题，运行时单例问题还得靠规范和使用方配合解决。

5. 从“会用”到“能落地”：用 pnpm workspace 搭建 Monorepo 的完整路径

前面讲了机制和原理，接下来是实操路径。pnpm workspace 是 Monorepo 的常用实现方式，下面是一个最小可跑的流程。

5.1 最小目录结构与 workspace 声明

先创建一个 Monorepo 根目录：

mkdir monorepo-demo cd monorepo-demo pnpm init

在根目录创建pnpm-workspace.yaml，声明哪些目录属于 workspace 包：

packages: - packages/*

然后把根 package.json 改为"private": true，避免整个仓库被意外发布到 npm。

在 packages 目录下创建两个包，比如ui和app。app需要依赖ui时，通过 workspace 协议安装：

pnpm add ui --filter app

pnpm 会识别ui是 workspace 内的包，并建立本地链接。打开packages/app/package.json，会看到类似"ui": "workspace:*"的声明。发布会时，pnpm 会把workspace:*替换成真实版本号，这个机制让本地开发和发布之间不需要手动切换。

5.2 用 filter 和排序控制构建

Monorepo 里最容易出现的操作是“构建某一个包”和“按依赖顺序构建所有包”。

只构建 app：

pnpm --filter app run build

按依赖顺序构建所有包：

pnpm -r --sort run build

--sort很重要。它会让被依赖的包先构建，依赖方后构建。如果没有这个参数，当 app 依赖 ui 时，很可能 ui 还没构建完，app 就开始构建，最后拿到旧的产物或直接失败。

实际执行时，可以根据项目规模选择是否需要并行。pnpm 的--parallel会并发执行，但并发也会带来输出混乱和资源竞争。我更建议先按依赖顺序串行跑通，再根据耗时决定要不要优化成并行。

5.3 锁文件、CI 缓存与版本策略

pnpm 使用pnpm-lock.yaml作为锁文件。它必须提交到 Git，并且在 CI 或生产环境安装时使用锁定模式：

pnpm install --frozen-lockfile

这样能保证线上安装的依赖版本和本地开发完全一致，避免出现“本地能跑，线上报错”的经典问题。

CI 加速时，缓存pnpm store path比缓存 node_modules 更有效。因为多个分支、多个项目可以复用同一份 store 内容。值得注意的是，如果 CI 用了缓存，偶尔会遇到 store 内容过期或权限问题，这时可以清理 store 缓存重新安装验证。

6. 实际工程里绕不开的问题：安装、镜像、版本、运行和排查链路

原理讲清楚了，最终还是要回到“我往服务器一跑就报错”的日常。下面这些问题是 pnpm 使用者最常遇到的，也是热搜词里高频出现的内容。

6.1 pnpm 不是内部或外部命令，先查 PATH

很多人在 Windows 上安装 pnpm 后，终端提示“pnpm 不是内部或外部命令，也不是可运行的程序”。这类问题的根源几乎都是 PATH 没有配置好，而不是 pnpm 没有安装成功。

先用npm prefix -g查看 npm 全局安装路径，Windows 上通常需要把这个路径加入系统 PATH，然后重新打开终端。如果使用 corepack 启用 pnpm，则要确认corepack enable是否执行成功，以及 Node 版本是否自带核心包。还有一种常见情况是终端缓存了旧 PATH，重新打开终端或执行 shell 的重新加载即可。

6.2 Node 版本与 pnpm 版本不匹配

较新版本的 pnpm 对 Node.js 版本有最低要求。常见报错是：

this version of pnpm requires at least node.js v22.13

看到这类错误，先用node -v和pnpm -v检查当前版本，不必急着升级 pnpm。如果项目使用的 Node 版本偏旧，直接升级 pnpm 可能会带来更多兼容问题。更稳妥的做法是固定一套经过验证的 Node 和 pnpm 版本组合，在团队内用.nvmrc或 volta 统一管理。

6.3 install 卡住、下载失败，先查镜像和并发

pnpm install长时间停在某个包，绝大多数是网络问题，而不是 pnpm 本身出了问题。先查当前 registry：

pnpm config get registry

如果确实需要使用国内镜像，可以设置：

pnpm config set registry https://registry.npmmirror.com

也可以只在当前项目下创建.npmrc文件，避免影响全局配置。另一个常见原因是并发过高，导致网络连接不稳定，可以尝试降低并发：

pnpm install --network-concurrency 4

如果 install 之前能正常运行，突然开始卡住，优先检查网络、镜像源和 lockfile 是否被修改，这比盲目删除 node_modules 更有效。

6.4 依赖构建脚本被 pnpm 默认阻止

较新版本的 pnpm 为了安全，默认不会执行依赖包里的 postinstall 脚本。安装时如果提示运行pnpm approve-builds，表示某些依赖需要构建脚本才能正常工作，比如 esbuild、sharp 这类包含原生代码的包。

遇到这种情况不要直接跳过。需要确认哪些依赖确实需要构建，然后执行：

pnpm approve-builds

按提示选择或配置允许名单。长期使用可以在 package.json 或 pnpm 配置中维护一份允许执行构建脚本的依赖列表，避免每次安装都重复交互。

6.5 构建产物如何交给 Nginx

Monorepo 的构建产物位置并不是固定的，取决于子包的构建配置。常见情况下，pnpm --filter app run build会输出到packages/app/dist目录。

部署时不是把整个 Monorepo 推到服务器，而是只复制构建产物到 Nginx 站点目录，或者把 Nginx root 指向对应的 dist 目录。前后端分离时，还需要处理 SPA fallback 和 API 反向代理。

如果pnpm run build正常但 Nginx 打开是空白页，先看 dist 目录是否真的生成，再看 Nginx 配置的 root、try_files 和静态资源路径是否有误，最后看浏览器 Console 里具体是哪个资源 404。

6.6 一套通用排查顺序

这个顺序背后的逻辑是：先确认命令本身能运行，再检查环境是否匹配，接着看依赖来源和网络，最后才考虑构建和部署配置。不要一遇到问题就直接删除 node_modules，那会把真正的原因掩盖掉。

7. 到底要不要上 Monorepo：适用边界与工程化判断

原理和实操都聊完了，最后回到一个更现实的问题：你的项目真的适合 Monorepo + pnpm 吗？技术选型不能只看趋势，要看团队、项目规模和维护成本。

7.1 适合 Monorepo + pnpm 的团队特征

适合的场景通常有这些特征：

• 多个包或应用需要频繁协同修改，比如组件库和业务项目同时演进。
• 共享逻辑被多个项目复用，且不希望每次都走“发版、安装、升级”流程。
• 团队已经有统一的代码规范、CI 流程和发布制度。
• 依赖关系复杂，希望用严格模式避免幽灵依赖带来的隐性风险。

如果你所在项目满足两到三条，Monorepo 是值得考虑的。

7.2 不适合的情况

反过来，如果项目之间几乎没有共享代码，只是想把多个仓库堆到一个目录里，那 Monorepo 带来的是负担而不是收益。“统一工具链”对规范性强的团队是帮助，对本来就各自为战的团队则是额外的束缚。

如果团队很小，只有两三个不相关的项目，维护 workspace、CI 缓存、依赖隔离的成本可能大于收益。如果没有自动化测试和统一规范，先把基础环境理顺，比直接上 Monorepo 更重要。

7.3 迁移前问自己三个问题

可以用一个简单框架来判断：

1. 一次功能改动，是否经常需要跨多个包同时修改？
2. 这些包是否需要同时发布、同时验证？
3. 团队是否愿意接受统一工具链和统一代码规范？

如果三个答案都是“是”，Monorepo 值得入场；如果有一半是“否”，建议先小范围试点，而不是把全部代码一次性压进一个仓库。从单个复杂项目开始做 workspace，再逐步扩展，通常比一步到位更稳妥。

7.4 长期维护要注意什么

Monorepo 不是“迁完就结束”，它需要持续维护。以下是几个容易忽略的点：

• lockfile 必须提交到 Git，CI 使用--frozen-lockfile安装。
• Node 和 pnpm 的版本要用.nvmrc或 volta 固定，避免团队环境不一致。
• CI 可以缓存 pnpm store，但要注意缓存失效策略，不要长期使用损坏的缓存。
• 所有包都要显式声明依赖，禁止“依赖恰好存在的传递依赖”。
• 定期执行pnpm store prune，清理不再被引用的文件。
• 代码规范要前置，否则 Monorepo 会把混乱放大而不是消化。

说到底，pnpm 在 Monorepo 里被选中，不是因为“安装速度快”这个浅层优点，而是因为它用一套严格的依赖隔离模型，让多个包可以在一个仓库里既共享存储、又保持边界清晰。理解了这一点，再回头看面试题“pnpm 怎么做到没声明就不能用”，答案其实就是一句话：它通过内容寻址存储和符号链接，把每个依赖的可见范围精确限制在声明它的包内部。而“没声明就不能用”这句话，恰好也是 Monorepo 工程化里最值得长期坚持的一条守则。