第五章 工作区与高级特性

第五章 · 工作区与高级特性

章节摘要：当项目从"一个包"长成"一个仓库里互相依赖的一群包"，包管理器就要回答新问题：本地包怎么互相引用、顶层锁文件怎么管全部子包、依赖声明的类型怎么各就各位。本章三节依次勘验：工作区与 Monorepo 的完整实战（含拓扑图与常见坑）、Yarn 免安装实验的机制与代价、以及五种依赖字段的精确语义。读完本章，多包仓库的依赖治理应当从"凭感觉"变成"按规则"。

学习目标（读完应能做到）

1. 为一个多包仓库设计工作区结构：顶层声明、子包清单、内部互相引用各怎么写；
2. 说清工作区对锁文件、安装命令与发布流程的影响，列出至少三个从单包仓库迁移时的坑；
3. 解释免安装模式如何用映射文件替代 node_modules，以及它的兼容性代价从哪来；
4. 对 dependencies、devDependencies、peerDependencies、optionalDependencies、bundledDependencies 五种字段，给出精确语义与典型用例；
5. 判断一个 peer 依赖警告该忽略还是该修，并知道修复动作落在哪个清单里。

核心概念速览

一句总纲：工作区把包管理器从"依赖安装器"升级成"仓库拓扑管理器"——它管理的不再只是第三方依赖，还包括仓库内部包与包之间的关系。免安装模式则把这场升级推到极致：连"安装"这个动作本身都试图取消。

这张拓扑图里的两条线型是全章的钥匙：实线是包与包的依赖关系（代码层面的引用），虚线是锁文件的管辖范围（安装层面的冻结）。工作区的全部便利与全部坑，都长在这两种关系的交织处。

子章节导航

5.1 Workspaces 与 Monorepo 实战：从一个真实的多包仓库出发，走完工作区搭建、内部引用、命令分发、发布协作的全程，并列出迁移时的三个高频坑。本章的主干节。

5.2 Yarn 免安装 PnP 机制：勘验最激进的实验路线——用映射文件取代 node_modules，安装动作退化为"生成一张查找表"。重点讲它的两个动机（根治幽灵依赖、砍掉安装 IO）与代价（生态兼容）。

5.3 依赖类型深度区分：五种依赖字段的精确语义、典型用例与常见误用，peer 依赖警告的处置决策。这一节是写库、写插件、写组件库的人的必修课。

子章节之间的逻辑关系

[5.1 工作区实战] —— 多包仓库的组织形态
      |
      v
[5.2 免安装实验] —— 布局哲学的激进分支：干脆不要 node_modules
      |
      v
[5.3 依赖类型]   —— 回到声明层：把"谁依赖谁"写精确
​

三节是"组织 → 布局 → 声明"的三层递进：5.1 在仓库尺度上组织包，5.2 在文件系统尺度上重新发明布局，5.3 回到清单文件把关系写准。5.2 相对独立，赶时间的读者可以最后读；但 5.1 与 5.3 建议连读——工作区仓库里，依赖类型的误用会被放大（子包互相把对方写进错误的字段，是 Monorepo 高频事故）。

前置知识与后续延伸

前置：第二章的布局规则（5.2 的价值恰恰要用 2.3 的提升副作用来对照才看得懂）、第三章的锁文件机制（工作区锁文件是其形态变体）。

后续延伸：5.2 的免安装模式与 2.4 的幽灵依赖根治直接衔接——那里说的"第三档根治"就是它；5.3 的 peer 依赖语义在插件化架构（第六章供应链的审计对象）里反复出现；本章的发布协作话题在第七章迁移实务里还有跨工具的对账。

本章金句：单包仓库里依赖类型写错的代价是偶发报错，Monorepo 里写错的代价是发布事故——规模会放大一切马虎。