Yarn 包管理器速查指南：常用命令、依赖管理与 Workspaces 实战-开发者社区

Yarn 包管理器速查指南：常用命令、依赖管理与 Workspaces 实战

【免费下载链接】reference面向开发者的技术速查清单（Cheat Sheets）集合，整理常见技术、工具与开发流程，帮助快速查阅关键信息，提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference

本篇技术指南以仓库中的 Yarn 备忘清单为主体，系统梳理 Yarn 包管理器的常用命令、安装选项、依赖类型分类、Workspaces 工作区与选择性版本解析等核心能力，并结合 package.json 备忘清单与 npm 备忘清单中的字段定义和命令对照进行纵深讲解。读完本篇，你将能够熟练地在日常开发中用 Yarn 完成依赖安装、版本锁定、多包仓库管理与子依赖版本覆盖等任务。

入门：Yarn 与 npm 命令对比

Yarn 与 npm 在功能上有大量一一对应的命令，绝大多数 npm 使用习惯可以平滑迁移到 Yarn。下表基于 Yarn 备忘清单整理，列出两套命令的对应关系：

值得注意的两点差异：

yarn（不带任何参数）与yarn install等价，会依据package.json一次性安装全部依赖；而yarn add <pkg>是「安装 + 写入 package.json」的组合操作，对应 npm 的npm install <pkg> --save。
npm 侧运行本地二进制文件需要显式书写./node_modules/.bin/xxx，而 Yarn 提供yarn run <script>或yarn <script>直接执行scripts字段中定义的任务。关于scripts的更多约定（如preinstall、postinstall等生命周期钩子），可参考 package.json 备忘清单。

有关 npm 侧的完整命令细节与.npmrc配置，可继续查阅 npm 备忘清单。

yarn install：按锁定文件精确还原依赖

yarn install是 Yarn 中最核心的命令，用于根据package.json安装项目所需的全部依赖，并可配合大量选项控制安装行为。以下是备忘清单中列出的全部选项及其作用：

--no-lockfile # 不要读取或生成 yarn.lock 锁定文件 --pure-lockfile # 不要生成 yarn.lock 锁定文件 --frozen-lockfile # 不更新 yarn.lock，若需要更新则直接安装失败 --silent # 静默执行，不输出日志 --offline # 触发远程请求时以缓存数据代替 --update-checksums # 更新 yarn.lock 中的校验和 --check-files # 检查 node_modules 中已安装的文件是否完整 --flat # 在整个依赖树中只允许一个版本的依赖 --force # 强制重新获取所有包，即使它们已在缓存中 --ignore-scripts # 不执行 package.json 中定义的脚本 --modules-folder <path> # 指定 node_modules 的安装位置 --production[=true|false] # 仅安装 dependencies，跳过 devDependencies

几个高频场景的选项解读：

CI/CD 环境：推荐使用--frozen-lockfile，保证每次安装严格按照yarn.lock还原依赖，一旦锁定文件需要变更就立即失败，从而暴露依赖漂移问题。
离线安装：--offline配合缓存使用，适合网络受限的构建环境；缓存会在首次安装时自动填充。
生产部署：--production（等价于--production=true）只安装dependencies，不安装devDependencies，从而精简生产环境的依赖体积。
强制单版本：--flat会强制整个依赖树中同一包只允许一个版本，若出现冲突，Yarn 会交互式询问并自动在package.json的resolutions字段中写入选择结果——这一点在 package.json 备忘清单中有明确说明。

yarn add：安装依赖并写入 package.json

yarn add <pkg>会在安装包的同时将其写入package.json的对应依赖分组。根据目标分组不同，可以使用以下选项：

--dev, -D # 安装到 devDependencies（开发期依赖，生产不安装） --peer, -P # 安装到 peerDependencies（对等依赖，声明与宿主包的兼容版本） --optional, -O # 安装到 optionalDependencies（可选依赖，安装失败不阻断流程） --exact, -E # 安装为精确版本（不带 ^ / ~ 前缀） --tilde, -T # 安装为同次要版本的最新版本（~ 前缀）

依赖分组的语义（结合 package.json 备忘清单中的字段定义）：

devDependencies：仅在开发期需要、生产环境不安装的包，如测试框架、构建工具、Lint 工具等，对应 package.json.md#devdependencies。
peerDependencies：声明你的包与宿主项目其他包的版本兼容性，例如 React 插件声明其支持的 React 版本范围，对应 package.json.md#peerdependencies。
optionalDependencies：可选用但非必需的包，安装失败不会中断整个安装流程，对应 package.json.md#optionaldependencies。

版本控制选项是日常最常踩坑的点：

默认情况下yarn add react会写入^18.2.0这类带^前缀的范围版本，安装时解析到该范围内的最新版本；
使用-E, --exact则写入18.2.0，精确锁定，避免后续yarn install因范围内版本升级而变化；
使用-T, --tilde则写入~18.2.0，锁定到当前次要版本，只允许补丁版本升级。

语义化版本号的^、~、>=等范围规则属于 semver 规范的范畴，仓库中还有一份独立的 Semver 语义化版本备忘清单可供交叉查阅。

Workspaces：从单包走向 Monorepo

Workspaces 是 Yarn 1.0 引入的多包管理能力，允许在一个顶级根包中管理本地文件系统中的多个子包，实现依赖共享与统一安装。配置方式是在根package.json中添加workspaces字段（对应 package.json.md#workspaces）：

{ "workspaces": [ "packages/*" ] }

典型的目录结构（以 jest 为例）：

jest/ ├─ package.json └─ packages/ ├─ jest-matcher-utils/ │ └─ package.json └─ jest-diff/ └─ package.json

当子包之间相互依赖时，Yarn 会通过符号链接（symlink）将node_modules中的包指向本地的packages/*目录，而不是重新下载远程副本，从而让多个子包在开发时「相互共享」。这也意味着：

在根目录执行一次yarn install即可为所有工作区子包统一安装依赖；
各子包公共的依赖会被提升（hoist）到根级node_modules，减少重复安装；
本地子包的修改即时生效，无需反复yarn add本地路径。

workspaces字段支持数组形式精确罗列多个子包路径，例如["packages/a", "packages/b"]，详细示例同样可见 package.json.md#workspaces。

选择性版本解析：用 resolutions 覆盖子依赖

实际项目中经常会遇到「间接依赖」的版本问题：你的直接依赖又依赖了某个有安全漏洞或行为异常的第三方包，而你无法直接控制它。Yarn 的选择性版本解析（Selective Version Resolutions）正是为解决这一问题而生，它在package.json的resolutions字段中配置：

{ "resolutions": { "**/sass-brunch/node-sass": "4.5.2" } }

**/sass-brunch/node-sass表示「任意层级下的 sass-brunch 所依赖的 node-sass」，即只覆盖这条特定依赖链上的版本，而不是全局强制；
也可以写成"transitive-package-1": "0.0.29"这种不带路径前缀的形式，表示覆盖所有位置的该包版本，详见 package.json.md#resolutions；
resolutions的值除了语义化版本，还支持本地路径（如file:./local-forks/transitive-package-2），常用于「本地 fork 一个包并替换远程版本」的场景。

需要留意的是，前面提到的yarn install --flat在发生版本冲突时，会自动把解析结果写入resolutions字段，两者是配套使用的机制。

yarn create：一条命令初始化项目

yarn create是 Yarn 提供的脚手架命令，它会先安装指定的create-xxx初始化工具，再以初始化的方式运行它。例如：

yarn create react-app hello

该命令等价于「先安装create-react-app，再运行create-react-app hello」两个步骤的合并，省去了全局安装脚手架的麻烦，且每次都能拉取工具的最新版本。这一模式与 npm 侧npm init <pkg>（等价于npx <pkg>）的机制类似，可参考 npm 备忘清单中的 init/exec 章节。

常用操作示例

安装包

# 将包添加到“dependencies” $ yarn add <package> # 将包添加到“devDependencies” $ yarn add -D <package> # 将软件包添加为确切版本 $ yarn add -E <package> # 在您的操作系统上全局安装软件包 $ yarn global add <package>

yarn global是全局包管理的命名空间，除了global add，还配套global list、global remove、global upgrade等子命令。

移除包

$ yarn remove <package>

该命令会从dependencies、devDependencies、peerDependencies、optionalDependencies等所有类型的依赖项中删除指定包，并同步更新package.json与yarn.lock。

查看包

# 列出已安装的软件包 $ yarn list # 列出顶级安装包 $ yarn list --depth=0 # 列出已安装的顶级全局包 $ yarn global list --depth=0 # 列出带有过滤字符串和深度级别的包 $ yarn list --pattern "gulp|grunt" --depth=1

--depth控制依赖树的展示层级，--pattern支持正则过滤包名，是排查依赖树结构的常用组合。

清除与过时检查

# 从包依赖项中清理并删除不必要的文件 $ yarn autoclean # 检查过时的包依赖项 $ yarn outdated

yarn autoclean用于清理依赖中不必要的文件以减小体积；yarn outdated用于列出落后于 registry 最新版本的依赖，便于决定何时升级。

信息：追溯依赖来源

$ yarn why <query> $ yarn why jest

yarn why是排查依赖来源的利器，它会显示「某个包为何被安装、由谁依赖、处于哪条依赖链上」，在 node_modules 出现重复版本或意外依赖时非常有用。

清理缓存

$ yarn cache clean

运行此命令将清除全局缓存。下次运行yarn或yarn install时，它会重新填充缓存。此外，还可以在命令后指定一个或多个包名，仅清理这些包的缓存。与之对应，npm 侧的缓存管理命令（npm cache clean等）见 npm 备忘清单。

与 package.json 的协同要点

Yarn 的所有依赖管理行为最终都落回package.json这份清单文件上，除上文涉及的字段外，还有几个值得了解的协同点：

flat字段：在package.json中设置"flat": true，可强制整个依赖树只允许给定依赖的一个版本，行为等价于命令行yarn install --flat；但需要注意，若你的包作为库被其他包依赖，对方也需要同样声明flat: true或使用--flat安装，详见 package.json.md#flat。
engines字段：可声明包所要求的 Node 与 Yarn 版本范围，Yarn 会基于当前环境进行检查，例如"yarn": "^0.14.0"、"node": ">=4.4.7 <7.0.0"，参见 package.json.md#engines。
registry 配置：Yarn 与 npm 共用 registry 概念，默认官方源为https://registry.yarnpkg.com/；国内开发者常配置 npmmirror（淘宝）镜像加速安装，相关配置方式（.npmrc或npm config set registry）在 npm 备忘清单的配置章节中有完整说明。

小结

Yarn 作为与 npm 高度兼容又各具特色的包管理器，其日常使用可以归纳为一条主线：yarn（安装）→yarn add（新增依赖）→yarn remove（移除依赖）→yarn upgrade（升级依赖），再辅以--exact/--tilde控制版本精度、resolutions覆盖子依赖版本、workspaces组织多包仓库。本文中的命令与选项均可直接复制使用，若要进一步深挖package.json各字段的完整语义（如exports条件导出、peerDependenciesMeta、publishConfig等），可继续阅读 package.json 备忘清单；如需对比 npm 侧的命令体系与 npx 机制，可参阅 npm 备忘清单。