Yarn

经典 JavaScript 包管理器，以 Plug'n'Play 和零安装著称

技术简介

Yarn 由 Facebook（现 Meta）于 2016 年 10 月首次发布，旨在解决 npm 早期在性能、可靠性和离线支持方面的不足。发布之初，Yarn Classic（v1.x）凭借并行安装、确定性锁文件和全局缓存机制迅速获得社区采用，一度成为前端工程化事实上的标准工具之一。

然而 Yarn Classic 在架构层面仍然依赖传统的 node_modules 目录结构和 npm 注册表协议。为了从根本上解决依赖解析的复杂性问题，Yarn 团队在 2020 年完成了 Yarn Berry（v2+）的重写。Berry 版本引入了 Plug'n'Play（PnP）这一核心创新——它完全消除了 node_modules 目录，通过一个 JSON 映射文件（.pnp.cjs）让 Node.js 运行时直接定位到磁盘上的包缓存位置。这一改变带来了更快的安装速度、更低的磁盘占用，以及更严格的依赖隔离。

从 v2 到 v3 再到 v4，Yarn Berry 持续演进。截至 2026 年 6 月，Yarn Berry 最新版本为 v4.17.0，处于活跃开发状态；而 Yarn Classic（v1.22.22）已于 2024 年冻结，不再接受新功能，仅提供关键安全修复。

基本信息

快速上手

安装

方式一：通过 Corepack（推荐）

Node.js 16.13+ 内置的 Corepack 是管理 Yarn 版本的推荐方式，无需手动全局安装：

# 启用 Corepack
corepack enable
 
# 在项目根目录下指定 Yarn 版本（自动写入 package.json）
corepack use [email protected]
 
# 此后所有 yarn 命令均使用 4.17.0 版本

Corepack 会在项目中创建 package.json 的 packageManager 字段锁定版本，确保团队成员和 CI 使用完全一致的 Yarn 版本。

方式二：独立安装（Standalone CLI）

# macOS / Linux
curl -o- -L https://yarnpkg.com/install.sh | bash
 
# Windows（PowerShell）
Invoke-WebRequest -Uri https://yarnpkg.com/install.sh -OutFile install.sh
bash install.sh

方式三：通过 npm 全局安装（不推荐，仅供兼容）

npm install -g yarn

注意：此方式安装的可能是 Classic（v1），建议使用 Corepack 以明确控制版本。

基础配置

Yarn Berry 的核心配置文件为项目根目录下的 .yarnrc.yml。以下是一份典型配置：

# .yarnrc.yml
 
# 启用 PnP 模式（Berry 默认值）
nodeLinker: pnp
 
# 或退回 node_modules 模式（兼容性更好）
# nodeLinker: node-modules
 
# 插件列表
plugins:
  - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
    spec: "@yarnpkg/plugin-workspace-tools"
  - path: .yarn/plugins/@yarnpkg/plugin-typescript.cjs
    spec: "@yarnpkg/plugin-typescript"
 
# npm 注册表镜像（企业内网常用）
npmRegistryServer: "https://registry.npmmirror.com"
 
# 忽略 engines 检查
ignoreCpu: true

PnP 模式下，Yarn 会在项目根目录生成 .pnp.cjs 文件，Node.js 通过它定位所有依赖，无需 node_modules。若使用的第三方工具不支持 PnP，可将 nodeLinker 改为 node-modules 以回退到传统模式。

最小示例

# 初始化项目
mkdir yarn-demo && cd yarn-demo
corepack use [email protected]
 
# 添加依赖
yarn add lodash
yarn add -D typescript @types/node
 
# 运行脚本
yarn node -e "console.log(require('lodash').VERSION)"
 
# 执行项目脚本（等价于 npm run）
yarn run build
 
# 查看依赖树
yarn why lodash

核心概念与架构

Plug'n'Play（PnP）

PnP 是 Yarn Berry 最核心的架构创新。传统包管理器会将依赖解压到 node_modules 目录，Node.js 通过文件系统的逐级向上查找来解析模块路径。这种方式存在两个问题：

1. 幽灵依赖（Phantom Dependencies）：代码可以意外引用未声明的依赖（因为 node_modules 是扁平的）。
2. 重复安装：同一个包的不同版本可能重复存在于磁盘上。

PnP 通过 .pnp.cjs 文件彻底解决了这两个问题。该文件是一个 JSON 映射表，记录了每个包的精确物理路径。Node.js 通过 --require ./.pnp.cjs 钩子劫持模块解析流程，直接跳转到磁盘上的包缓存位置。

.pnp.cjs 映射表示例（简化）：

[email protected] → .yarn/cache/packageA-npm-1.0.0-xxx.zip/node_modules/packageA/
[email protected] → .yarn/cache/packageB-npm-2.3.1-yyy.zip/node_modules/packageB/

内容寻址存储（Content-Addressable Storage）

Yarn Berry 将下载的包存储在 .yarn/cache/ 目录中，文件名包含包名、版本和内容哈希。这意味着：

• 相同内容的包只存储一份，跨项目共享
• 文件完整性通过哈希自动校验，无需额外的 integrity 字段
• 缓存目录可以直接提交到 Git，实现零安装（Zero-Install）

零安装（Zero-Install）

零安装是 Yarn Berry 的标志性特性。当 .yarn/cache/ 和 .pnp.cjs 都被提交到版本控制后，新开发者克隆仓库后无需运行 yarn install 即可直接运行项目。这不仅加速了环境搭建，更消除了"在我机器上能跑"的问题。

# 启用零安装：提交缓存目录
git add .yarn/cache/ .pnp.cjs .pnp.loader.mjs
git commit -m "feat: enable zero-install"
 
# 新开发者克隆后直接运行
git clone <repo>
yarn node src/index.js   # 无需 yarn install

工作空间（Workspaces）

Yarn Berry 原生支持 Monorepo 工作空间，在根 package.json 中声明：

{
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

Yarn 会自动识别各子包之间的依赖关系，使用符号链接或 PnP 映射实现本地包的互相引用。结合 workspace: 协议可以显式声明内部依赖：

{
  "dependencies": {
    "@my-org/ui": "workspace:^",
    "@my-org/utils": "workspace:*"
  }
}

约束系统（Constraints）

Yarn Berry 引入了独特的 Constraints 机制，允许团队在 .yarn/constraints.js 中定义依赖解析的全局规则：

// .yarn/constraints.js
const { workspace, dependency } = require('yarn/constraints')
 
// 所有工作空间使用统一的 lodash 版本
workspace.byName('apps/web').tap(workspace => {
  workspace.dependencies.set('lodash', '4.17.21')
})
 
// 禁止使用特定包
workspace.each(workspace => {
  for (const [name] of workspace.dependencies) {
    if (name === 'moment') {
      workspace.reportError(
        `不允许使用 moment，请改用 dayjs`
      )
    }
  }
})

核心特性

Plug'n'Play 依赖解析

PnP 模式消除了 node_modules 目录，通过 .pnp.cjs 映射文件实现依赖解析，杜绝幽灵依赖，提升安装速度和确定性。

零安装（Zero-Install）

.yarn/cache/ 和 .pnp.cjs 提交到版本控制后，新开发者克隆仓库即可直接运行项目，无需执行任何安装命令。这是 Yarn 独有的工程化优势。

工作空间（Workspaces）

原生支持 Monorepo 结构，结合 workspace: 协议实现精确的版本引用，支持依赖提升和包间协同。

插件系统

Yarn Berry 提供灵活的插件架构，官方插件包括：

自定义插件可以拦截命令、修改解析逻辑、集成内部工具链。

便携式归档（Portable Archives）

Yarn 的包缓存文件（.yarn/cache/*.zip）是标准 ZIP 归档，可以在项目间直接拷贝或通过网络分发，无需重新从注册表下载。

延迟解析（Lazy Unplugging）

对于不支持 PnP 的包，Yarn 提供 dependenciesMeta.unplugged 机制，将特定包解压到 .yarn/unplugged/ 目录。这种"按需不插拔"的方式在兼容性和性能之间取得平衡。

协议扩展

Yarn Berry 引入了多种自定义协议：

yarn patch 命令

允许你修改已安装依赖的源码，生成补丁文件并提交到版本控制。其他开发者拉取代码后，补丁会自动应用：

# 打开包的源码进行编辑
yarn patch lodash@npm:4.17.21
 
# 编辑完成后提交补丁
yarn patch-commit -s /tmp/xfs-xxx
 
# 生成的补丁文件：.yarn/patches/lodash-npm-4.17.21-xxx.patch

yarn npm stage 命令

v4.17.0 新增的命令，用于在发布流程中将包暂存到 npm 注册表，简化多包发布的工作流。

Catalog 支持

Yarn Berry 支持在 .yarnrc.yml 中定义 Catalog，统一管理 Monorepo 中所有工作空间的共享依赖版本，避免版本分散。

devEngines.packageManager 支持

通过在 package.json 中声明 devEngines.packageManager，可以在 CI 和开发环境中自动验证包管理器版本的一致性。

生态图

Yarn Berry 生态系统
├── 核心层
│   ├── Yarn CLI（berry）         ← 主入口，命令行工具
│   ├── PnP 运行时                 ← .pnp.cjs 模块解析钩子
│   ├── Content-Addressable Cache ← .yarn/cache/ 包缓存
│   └── Constraints Engine        ← 全局依赖规则引擎
│
├── 插件层
│   ├── plugin-workspace-tools    ← 工作空间批量操作
│   ├── plugin-typescript         ← 类型声明自动生成
│   ├── plugin-interactive-tools  ← 交互式升级界面
│   ├── plugin-constraints        ← 约束系统
│   └── 自定义插件                 ← 开放插件 API
│
├── IDE 与编辑器支持
│   ├── VS Code + Yarn SDK        ← PnP 下的编辑器智能提示
│   ├── TypeScript PnP Patch      ← tsc 兼容 PnP 解析
│   └── EditorConfig / ESLint     ← 工具链 PnP 适配
│
├── 注册表与镜像
│   ├── npm Registry              ← 默认注册表
│   ├── 私有注册表                 ← Verdaccio / Nexus / Artifactory
│   └── 国内镜像                   ← npmmirror / Tencent Mirror
│
├── 版本管理
│   ├── Corepack                  ← Node.js 内置版本管理器
│   ├── Release Workflow          ← @yarnpkg/builder 构建发布
│   └── Changesets / Lerna        ← Monorepo 版本协调
│
└── CI/CD 集成
    ├── Zero-Install Pipeline     ← 跳过 yarn install
    ├── Cache Optimization        ← .yarn/cache/ 作为 CI 缓存
    └── Matrix Testing            ← 多 Node 版本测试矩阵

Corepack 关系

Corepack 是 Node.js 内置的包管理器版本管理工具，与 Yarn Berry 深度集成。通过 Corepack，项目可以精确锁定 Yarn 版本（packageManager 字段），团队成员和 CI 无需手动安装特定版本的 Yarn。

IDE PnP 支持

PnP 模式下，编辑器的 TypeScript 服务器需要理解 .pnp.cjs 解析逻辑。Yarn 官方提供了 VS Code 集成方案：

# 生成 VS Code SDK 补丁
yarn dlx @yarnpkg/sdks vscode

该命令会在 .yarn/sdks/ 下生成适配 PnP 的 TypeScript、ESLint、Prettier 等工具包装器，确保编辑器的智能提示正常工作。

适用场景

零安装项目团队

当团队规模较大、开发者环境差异明显时，零安装是 Yarn 最突出的优势。新成员克隆仓库后无需执行任何安装命令即可运行项目，彻底消除环境配置问题。

适合：大型团队、开源项目、快速 Onboarding 场景。

Monorepo 工程

Yarn Berry 的工作空间支持与 Constraints 系统配合，可以在 Monorepo 中统一管理数百个子包的依赖版本和依赖策略。

适合：多包仓库、共享组件库、微前端架构。

确定性构建环境

PnP 模式下，每个依赖都必须显式声明，杜绝了幽灵依赖。结合锁文件和缓存哈希，确保构建结果在任意环境完全一致。

适合：对构建确定性要求极高的场景（如合规审计、金融系统）。

磁盘空间受限环境

Yarn Berry 的内容寻址存储使全局缓存只保存一份包副本，跨项目共享。配合零安装模式，单项目可节省约 85% 的磁盘空间。

适合：SSD 空间紧张的开发者、CI 缓存有限的环境。

开发与工程化

开发工作流

# 1. 项目初始化
corepack use [email protected]
yarn init
 
# 2. 添加开发依赖
yarn add -D typescript @types/node vitest eslint prettier
 
# 3. 配置工作空间（Monorepo）
# 在 package.json 中声明 workspaces 字段
 
# 4. 日常开发
yarn install              # 安装 / 同步依赖
yarn run dev              # 启动开发服务器
yarn test                 # 运行测试
yarn lint                 # 代码检查
 
# 5. 依赖管理
yarn upgrade-interactive  # 交互式升级依赖
yarn why <pkg>            # 查看依赖引用链
yarn dedupe               # 去重依赖版本

CI 优化（零安装模式）

零安装模式下的 CI 流水线可以完全跳过 yarn install：

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      # 启用 Corepack 以匹配 packageManager 字段
      - name: Enable Corepack
        run: corepack enable
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
 
      # 零安装：无需 yarn install！
      - name: Type Check
        run: yarn run typecheck
 
      - name: Test
        run: yarn test
 
      - name: Build
        run: yarn build

提示：零安装模式要求 .yarn/cache/ 和 .pnp.cjs 已提交到 Git。如果项目依赖有更新，记得重新提交缓存目录。

CI 优化（非零安装模式）

当未使用零安装时，可以通过缓存 .yarn/cache/ 加速安装：

- name: Get Yarn cache directory
  id: yarn-cache
  run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
 
- name: Cache Yarn dependencies
  uses: actions/cache@v4
  with:
    path: ${{ steps.yarn-cache.outputs.dir }}
    key: yarn-${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
 
- name: Install dependencies
  run: yarn install --immutable

工作空间管理

# 列出所有工作空间
yarn workspaces list
 
# 在特定工作空间执行命令
yarn workspace @my-org/ui run build
 
# 批量执行命令（需要 workspace-tools 插件）
yarn workspaces foreach -A run build
yarn workspaces foreach -Apt run test
 
# 添加依赖到特定工作空间
yarn workspace @my-org/web add lodash

性能与安全

性能基准（2026 年数据）

Yarn Berry 4 PnP 在标准基准测试中相较 npm 11 展现出显著优势：

注：以上数据基于社区基准测试和官方发布说明，实际性能因项目规模、网络环境和硬件而异。

安全特性

Yarn Berry 在安全方面提供了多层防护：

依赖完整性校验：所有包通过内容寻址缓存，文件名包含 SHA 哈希，自动检测下载损坏或被篡改的包。

审计命令：

# 检查已知漏洞
yarn npm audit
 
# 自动修复
yarn npm audit --fix

PnP 依赖隔离：PnP 模式天然阻止了幽灵依赖的访问。代码只能引用在 package.json 中显式声明的依赖，避免了供应链攻击中"通过扁平 node_modules 注入恶意包"的风险。

严格的 node_modules 限制：即使在 node-modules 模式下，Yarn Berry 也通过 .pnp.cjs 进行额外的访问控制，限制未声明依赖的访问。

安全策略（Yarn 3.3+）：支持 .yarnrc.yml 中的安全相关配置，包括注册表锁定、HTTPS 强制和证书校验。

技术对比

对比要点

• Yarn Berry vs pnpm：两者都强调磁盘效率和严格的依赖隔离。Yarn 通过 PnP 彻底消除 node_modules，pnpm 通过硬链接和符号链接保持 node_modules 结构但避免重复。Yarn 的零安装是独有优势。
• Yarn Berry vs npm：Yarn 在速度、磁盘占用和确定性构建方面有明显优势。npm 生态最成熟、工具兼容性最好。
• Yarn Berry vs Bun：Bun 是运行时 + 包管理器一体化方案，速度极快但生态尚不成熟。Yarn 专注于包管理，生态更稳定。

最佳实践

PnP 模式使用建议

启用 PnP 的场景：

• 新项目，从第一天开始使用 Yarn Berry
• 团队愿意投入时间适配工具链（ESLint、Prettier、TypeScript）
• 追求极致的安装速度和磁盘效率

使用 node-modules 模式的场景：

• 依赖了大量不支持 PnP 的第三方工具
• 从 Yarn Classic 或 npm 迁移，需要渐进过渡
• 团队对 PnP 不熟悉，短期无法完成工具链适配

从 Classic 迁移到 Berry

Yarn 官方提供了迁移工具和详细的迁移指南：

# 1. 升级到 Berry（自动迁移配置）
corepack use [email protected]
 
# 2. 运行导入命令（迁移 Classic 配置）
yarn import
 
# 3. 检查 PnP 兼容性
yarn dlx @yarnpkg/doctor
 
# 4. 处理不兼容的包（按需）
# 在 .yarnrc.yml 中添加 packageExtensions 修复缺失的 peerDependencies

迁移 Checklist：

1. 更新 .yarnrc.yml 格式（Classic 和 Berry 配置格式不同）
2. 重新生成 yarn.lock
3. 运行 yarn dlx @yarnpkg/doctor 检查兼容性问题
4. 为 IDE 生成 SDK 补丁：yarn dlx @yarnpkg/sdks vscode
5. 更新 CI 配置以使用 Corepack
6. 处理不支持 PnP 的依赖（使用 nodeLinker: node-modules 或 dependenciesMeta.unplugged）

零安装模式实践

# 1. 确保 .yarn/cache/ 被 Git 跟踪
git add .yarn/cache/ .pnp.cjs .pnp.loader.mjs
 
# 2. 在 .gitignore 中排除不需要的目录
# .gitignore
.yarn/*
!.yarn/cache/
!.yarn/patches/
!.yarn/plugins/
!.yarn/releases/
!.yarnrc.yml
 
# 3. 配置 precommit 钩子自动更新缓存
# 使用 husky + lint-staged 确保缓存同步

依赖管理技巧

# 使用 patch 协议修复第三方包的 bug
yarn patch lodash@npm:4.17.21
# 编辑后提交补丁
yarn patch-commit -s /tmp/xfs-xxx
 
# 使用 packageExtensions 修复缺失的 peerDependencies
# .yarnrc.yml
packageExtensions:
  "some-package@*":
    peerDependencies:
      "react": "*"
 
# 去重依赖
yarn dedupe
 
# 查看特定依赖为什么被安装
yarn why lodash

技术局限与边界

PnP 兼容性挑战

PnP 模式虽然带来了诸多优势，但也是 Yarn Berry 最大的争议点：

• 部分 npm 工具不兼容 PnP：某些工具直接操作 node_modules 文件系统，不通过 Node.js 的 require.resolve API 解析模块。这类工具在 PnP 模式下会失败。
• IDE 需要额外配置：VS Code、WebStorm 等编辑器需要生成 SDK 补丁才能在 PnP 模式下正常工作。
• 原生 Node.js 模块：部分依赖文件系统路径的原生模块（如 .node 二进制文件）可能需要 unplugged。

常见的 PnP 兼容性问题工具：

• jest（需要 @yarnpkg/jest 适配）
• webpack（需要 PnP 兼容的 resolve 插件）
• 部分 ESLint 插件（依赖 node_modules 路径）

Node.js 版本兼容

• Yarn Berry v4 要求 Node.js >= 18.12.0
• Node.js v22.22+ 和 v24.16+ 已官方支持 PnP
• Node.js v25.7+ 存在已报告的 PnP 兼容性问题，建议在该版本上暂使用 nodeLinker: node-modules 或等待修复

学习曲线

相较于 npm 和 pnpm，Yarn Berry 的概念体系更复杂：

• PnP 的模块解析机制需要理解
• .yarnrc.yml 配置选项较多
• 插件系统和约束系统有额外的学习成本
• 从 Classic 迁移到 Berry 需要处理配置差异

社区与生态规模

• Yarn Berry 的社区规模小于 npm 和 pnpm
• 部分文档和社区资源仍以英文为主，中文资料相对较少
• 插件生态虽在增长，但不如 npm 的脚本生态丰富

不适合的场景

• 极简项目：对于只有一个 package.json 的小型项目，Yarn Berry 的 PnP 和零安装带来的复杂度收益不大。
• 深度依赖原生模块：大量使用需要编译的 Node.js 原生模块的项目，可能会频繁遇到 PnP 兼容性问题。
• 不愿投入工具链适配的团队：如果团队不愿花时间配置 IDE SDK、ESLint 适配等，node-modules 模式虽然可用但放弃了 PnP 的核心优势。

学习资源

官方资源

进阶资源

社区资源

2026 年现状

版本状态

• Yarn Berry（v4.17.0）：2026 年 6 月发布的最新版本，处于活跃开发状态。持续引入新特性如 Package Map 生成、yarn npm stage 命令、Catalog 支持、devEngines.packageManager 支持等。
• Yarn Classic（v1.22.22）：已于 2024 年冻结。不再接受新功能和常规 bug 修复，仅提供关键安全补丁。官方强烈建议所有用户迁移到 Berry。

生态定位

Yarn Berry 在 2026 年的包管理器格局中占据独特的技术定位：

• PnP 的先行者：Yarn 是唯一将 PnP 作为默认安装策略的主流包管理器。这一创新虽然面临兼容性挑战，但代表了"去 node_modules 化"的前沿探索。
• 零安装的标杆：零安装模式在大型团队和 CI 环境中获得了切实的认可，是 Yarn 最难以替代的差异化优势。
• Monorepo 的有力竞争者：结合工作空间、约束系统和 workspace: 协议，Yarn Berry 在 Monorepo 场景中提供了完整的治理能力。

采用情况

• Yarn Berry 在大型技术公司和创新驱动的团队中采用率较高
• 中小型项目和传统团队中，npm 和 pnpm 的市场份额更大
• PnP 的兼容性问题是阻碍更广泛采用的主要因素
• 随着 Corepack 的普及，Yarn Berry 的版本管理和采用门槛正在降低

未来展望

• PnP 兼容性将随着更多工具的适配持续改善
• Node.js 新版本（v22.x、v24.x）的官方 PnP 支持将降低使用门槛
• 零安装模式有望成为行业最佳实践的参考标准
• Yarn Berry 的插件系统和约束系统可能影响未来包管理器的设计方向

总结：Yarn Berry 通过 Plug'n'Play 和零安装两项核心创新，在 JavaScript 包管理领域开辟了独特的技术路线。它在安装速度、磁盘效率和构建确定性方面优势显著，尤其适合大型团队、Monorepo 和对环境一致性要求高的场景。PnP 兼容性仍是其主要挑战，但在 Corepack 和工具链适配的持续改善下，Yarn Berry 正朝着更广泛采用的方向发展。