yarn

yarn 是 Facebook（现 Meta）开发的 JavaScript 包管理器，于 2016 年发布，旨在解决 npm 早期版本的性能和安全问题。

yarn 版本

yarn 有两个主要版本：

版本	说明
yarn 1 (Classic)	经典版本，稳定可靠
yarn 2+ (Berry)	现代版本，支持 Plug'n'Play (PnP)

安装

yarn 1 (Classic)

# 使用 npm 安装
npm install -g yarn

# 使用 Corepack（Node.js 16.10+）
corepack enable

# 使用 Homebrew（macOS）
brew install yarn

# 使用安装脚本
curl -o- -L https://yarnpkg.com/install.sh | bash

yarn 2+ (Berry)

# 在项目中启用 yarn 2
yarn set version berry

# 或指定版本
yarn set version 4.0.0

# 升级到最新版本
yarn set version latest

基本使用

初始化项目

# 创建 package.json
yarn init

# 使用默认值
yarn init -y

# 初始化 yarn 2 项目
yarn init -2

安装依赖

# 安装所有依赖
yarn

# 或
yarn install

# 安装生产依赖
yarn add lodash

# 安装指定版本
yarn add [email protected]

# 安装开发依赖
yarn add -D jest
yarn add --dev jest

# 安装 peer 依赖
yarn add -P react

# 安装可选依赖
yarn add -O eslint

# 全局安装
yarn global add typescript

# 安装精确版本
yarn add --exact lodash

删除依赖

# 删除依赖
yarn remove lodash

# 删除开发依赖
yarn remove -D jest

# 删除全局依赖
yarn global remove typescript

更新依赖

# 检查可更新的依赖
yarn outdated

# 更新依赖
yarn upgrade

# 更新到最新版本
yarn upgrade --latest

# 更新特定包
yarn upgrade lodash

# 交互式更新
yarn upgrade-interactive

yarn.lock

yarn 使用 yarn.lock 文件锁定依赖版本，确保团队成员安装的依赖完全一致。

# yarn.lock
lodash@^4.17.21:
  version "4.17.21"
  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz"
  integrity sha512-v3k...

注意事项

提交到版本控制
不要手动编辑
使用 yarn install 时自动更新

配置管理

.yarnrc.yml (yarn 2+)

# 设置镜像源
npmRegistryServer: "https://registry.npmmirror.com"

# 启用 Plug'n'Play
nodeLinker: pnp

# 使用 node_modules（兼容模式）
nodeLinker: node-modules

# 缓存设置
cacheFolder: "./.yarn/cache"

# 全局文件夹
globalFolder: "./.yarn/global"

# 压缩级别
compressionLevel: mixed

.yarnrc (yarn 1)

# 设置镜像源
registry "https://registry.npmmirror.com"

# 代理设置
proxy "http://proxy.example.com:8080"
https-proxy "http://proxy.example.com:8080"

# 缓存文件夹
cache-folder "./.yarn-cache"

# 离线镜像
offline-mirror "./offline-mirror"

常用配置命令

# 查看所有配置
yarn config list

# 查看特定配置
yarn config get registry

# 设置配置
yarn config set registry https://registry.npmmirror.com

# 删除配置
yarn config unset registry

Plug'n'Play (PnP)

yarn 2+ 引入了 Plug'n'Play 模式，完全消除了 node_modules 文件夹。

启用 PnP

# 设置 PnP 模式
yarn config set nodeLinker pnp

# 生成 .pnp.cjs 文件
yarn install

PnP 优点

安装速度极快
磁盘空间占用少
严格的依赖管理
确定性的依赖解析

PnP 兼容性

某些工具可能需要额外配置：

# 安装 VS Code 支持
yarn dlx @yarnpkg/sdks vscode

# 安装 TypeScript 支持
yarn dlx @yarnpkg/sdks base

切换回 node_modules

# 切换到 node_modules 模式
yarn config set nodeLinker node-modules

# 重新安装
yarn install

工作区 (Workspaces)

yarn 原生支持单体仓库管理。

配置

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

workspace 命令

# 安装所有 workspace 依赖
yarn install

# 在特定 workspace 执行命令
yarn workspace @myproject/core run build

# 添加依赖到特定 workspace
yarn workspace @myproject/core add lodash

# 在所有 workspace 执行命令（yarn 1）
yarn workspaces run build

# 在所有 workspace 执行命令（yarn 2+）
yarn workspaces foreach run build

workspace 协议 (yarn 2+)

{
  "dependencies": {
    "@myproject/core": "workspace:*",
    "@myproject/utils": "workspace:^"
  }
}

协议	说明
`workspace:*`	使用精确版本
`workspace:^`	使用兼容版本
`workspace:~`	使用近似版本

脚本命令

定义脚本

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack --mode production"
  }
}

运行脚本

# 运行脚本
yarn start
yarn test
yarn build

# 运行自定义脚本
yarn run custom-script

# 传递参数
yarn test --coverage

# 并行运行（yarn 2+）
yarn workspaces foreach -p run test

# 按拓扑顺序运行（yarn 2+）
yarn workspaces foreach -t run build

发布包

# 登录
yarn login

# 发布前检查
yarn pack --dry-run

# 发布
yarn publish

# 发布到指定镜像源
yarn publish --registry https://registry.npmjs.org

# 发布 scoped 包
yarn publish --access public

# 发布 beta 版本
yarn publish --tag beta

# 发布新版本
yarn version patch  # 1.0.0 -> 1.0.1
yarn version minor  # 1.0.0 -> 1.1.0
yarn version major  # 1.0.0 -> 2.0.0

yarn dlx

类似于 npx，用于执行包命令：

# 创建项目
yarn dlx create-react-app my-app
yarn dlx create-vite my-app

# 使用特定版本
yarn dlx [email protected] my-app

# 从 GitHub 执行
yarn dlx github:user/repo

# 执行本地包
yarn dlx ./local-package

常用命令速查

yarn 1

命令	说明
`yarn init`	初始化项目
`yarn` / `yarn install`	安装所有依赖
`yarn add <pkg>`	安装依赖
`yarn add -D <pkg>`	安装开发依赖
`yarn remove <pkg>`	删除依赖
`yarn upgrade`	更新依赖
`yarn outdated`	检查过期依赖
`yarn run <script>`	运行脚本
`yarn list`	查看已安装依赖
`yarn global add <pkg>`	全局安装
`yarn global list`	查看全局依赖
`yarn why <pkg>`	查看依赖原因
`yarn cache clean`	清除缓存
`yarn check`	检查依赖

yarn 2+ 额外命令

命令	说明
`yarn set version <version>`	设置 yarn 版本
`yarn plugin import <plugin>`	安装插件
`yarn workspaces foreach`	遍历所有 workspace
`yarn npm audit`	安全审计
`yarn npm info <pkg>`	查看包信息
`yarn rebuild`	重新构建依赖

与 npm 命令对比

npm	yarn 1	yarn 2+
`npm install`	`yarn`	`yarn`
`npm install <pkg>`	`yarn add <pkg>`	`yarn add <pkg>`
`npm install -D <pkg>`	`yarn add -D <pkg>`	`yarn add -D <pkg>`
`npm uninstall <pkg>`	`yarn remove <pkg>`	`yarn remove <pkg>`
`npm run <script>`	`yarn <script>`	`yarn <script>`
`npm list`	`yarn list`	`yarn info`
`npm outdated`	`yarn outdated`	`yarn upgrade-interactive`
`npm update`	`yarn upgrade`	`yarn up`
`npm ci`	`yarn install --frozen-lockfile`	`yarn install --immutable`
`npx <cmd>`	`yarn dlx <cmd>`	`yarn dlx <cmd>`

Yarn 4 新特性

Yarn 4 于 2023 年发布，带来了显著的性能提升和多项新功能。

安装方式变更

从 Yarn 4 开始，官方推荐使用 Corepack 来管理 Yarn 版本：

# 使用 Corepack 启用 Yarn
corepack enable

# 设置 Yarn 版本
corepack use yarn@4

# 或使用 yarn 命令设置
yarn set version 4

package.json 中会添加 packageManager 字段：

{
  "packageManager": "[email protected]"
}

Hardened Mode（加固模式）

Yarn 4 引入了 Hardened Mode，提供额外的安全保护：

功能：

验证锁文件中的解析结果是否与版本范围一致
验证锁文件中的包元数据是否与远程仓库一致
防止攻击者通过修改锁文件注入恶意模块

启用方式：

# 通过环境变量启用（推荐用于 CI）
export YARN_ENABLE_HARDENED_MODE=1

# 或在 .yarnrc.yml 中配置
enableHardenedMode: true

自动启用：当 Yarn 检测到在公开的 GitHub PR 中运行时，会自动启用加固模式。

性能影响：加固模式会显著降低安装速度，因为需要进行额外的网络请求验证。不建议在开发环境默认启用。

JavaScript Constraints（约束系统）

Yarn 的约束系统允许你定义项目必须满足的规则。从 Yarn 4 开始，约束使用 JavaScript 编写（替代了之前的 Prolog 语法）。

配置约束：

// constraints.pro 或 constraints.js
module.exports = async ({ constraints }) => {
  // 确保所有 workspace 使用相同的依赖版本
  constraints.enforcedDependency({
    name: "typescript",
    version: "^5.0.0",
  });

  // 禁止特定的依赖
  constraints.forbiddenDependency({
    name: "lodash",
  });

  // 确保所有包都有指定的字段
  constraints.enforcedField({
    field: "license",
    value: "MIT",
  });
};

运行约束检查：

# 检查约束
yarn constraints

# 在安装时自动检查
# .yarnrc.yml
enableConstraintsChecks: true

常见约束示例：

module.exports = async ({ constraints, workspace }) => {
  // 禁止 moment.js（推荐使用 date-fns）
  constraints.forbiddenDependency({ name: "moment" });

  // 强制 React 版本一致
  constraints.enforcedDependency({
    name: "react",
    version: workspace.root.manifest.dependencies.react,
  });

  // 确保所有包有描述
  constraints.enforcedField({
    field: "description",
    require: true,
  });
};

内置插件

从 Yarn 4 开始，之前需要单独安装的官方插件现在都内置了：

功能	命令
TypeScript 集成	自动管理 `@types` 包
交互式更新	`yarn upgrade-interactive`
暂存文件	`yarn stage`
版本管理	`yarn version`

TypeScript 集成：

当使用 yarn add 或 yarn remove 时，Yarn 会自动添加或删除对应的 @types 包：

# 安装 lodash 时自动安装 @types/lodash
yarn add lodash

# 删除 lodash 时自动删除 @types/lodash
yarn remove lodash

性能改进

Yarn 4 的性能相比 3.x 有显著提升：

安装速度提升 3-4 倍：新的包元数据缓存大幅提升重复安装速度
内存使用优化：更高效的数据结构
并行处理改进：更好的网络和磁盘 I/O 并发

改进的用户界面

更清晰的输出：

➤ YN0000: · Yarn 4.0.0
➤ YN0000: ┌ Resolution step
➤ YN0085: │ + next@npm:13.5.4, react-dom@npm:18.2.0, and 24 more.
➤ YN0000: └ Completed in 0s 280ms
➤ YN0000: ┌ Fetch step
➤ YN0013: │ 22 packages were added to the project (+ 177.72 MiB).
➤ YN0000: └ Completed in 3s 723ms
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed
➤ YN0000: · Done with warnings in 4s 123ms

配置命令改进：

# 树形显示配置
yarn config

# 查看特定配置
yarn config cacheFolder npmRegistryServer

从 Yarn 3 迁移

主要变更：

需要 Node.js 18+
yarn init 不再默认启用 Zero-Install
yarn workspaces foreach 语法略有变化

迁移步骤：

# 1. 确保 Node.js 版本 >= 18
node -v

# 2. 更新 Yarn 版本
yarn set version 4

# 3. 更新配置（如果使用 yarnPath）
# 改为使用 Corepack：
corepack enable
corepack use yarn@4

# 4. 如果使用 Prolog 约束，迁移到 JavaScript
# 5. 重新安装依赖
yarn install

插件系统 (yarn 2+)

yarn 2+ 支持插件扩展功能。从 Yarn 4 开始，官方插件已内置，无需单独安装。

常用插件

# 安装第三方插件
yarn plugin import <plugin-name>

# 从 URL 安装
yarn plugin import https://example.com/plugin.js

# 查看已安装插件
yarn plugin runtime

常用插件功能

插件	功能	Yarn 4 内置
`typescript`	TypeScript 支持，自动管理 @types	✓
`interactive-tools`	交互式工具	✓
`workspace-tools`	workspace 工具	✓
`version`	版本管理	✓

最佳实践

1. 使用 Zero-Install

yarn 2+ 支持 Zero-Install 模式，将缓存提交到仓库：

# .yarnrc.yml
pnpEnableInlining: false

# .gitignore
.pnp.*
!.yarn/cache
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

2. 使用约束

# .yarnrc.yml
enableConstraints: true

# constraints.pro
gen_enforced_dependency(DEV, "jest", null, null).

3. 安全审计

# yarn 1
yarn audit

# yarn 2+
yarn npm audit

# 检查许可证
yarn licenses list

4. 使用 .yarnignore

# .yarnignore
*.test.js
*.spec.js
coverage/
docs/
.DS_Store

5. 缓存管理

# 查看缓存路径
yarn cache dir

# 清除缓存
yarn cache clean

# 清除特定包缓存
yarn cache clean lodash

从 yarn 1 迁移到 yarn 2+

# 1. 安装 yarn 2
yarn set version berry

# 2. 更新配置
# 将 .yarnrc 转换为 .yarnrc.yml

# 3. 重新安装依赖
yarn install

# 4. 检查兼容性
yarn install --check-resolutions

了解更多

yarn 官网：https://yarnpkg.com
yarn 1 文档：https://classic.yarnpkg.com/docs
yarn 2+ 文档：https://yarnpkg.com/getting-started
yarn GitHub：https://github.com/yarnpkg/berry

yarn 版本​

安装​

yarn 1 (Classic)​

yarn 2+ (Berry)​

基本使用​

初始化项目​

安装依赖​

删除依赖​

更新依赖​

yarn.lock​

注意事项​

配置管理​

.yarnrc.yml (yarn 2+)​

.yarnrc (yarn 1)​

常用配置命令​

Plug'n'Play (PnP)​

启用 PnP​

PnP 优点​

PnP 兼容性​

切换回 node_modules​

工作区 (Workspaces)​

配置​

workspace 命令​

workspace 协议 (yarn 2+)​

脚本命令​

定义脚本​

运行脚本​

发布包​

yarn dlx​

常用命令速查​

yarn 1​

yarn 2+ 额外命令​

与 npm 命令对比​

Yarn 4 新特性​

安装方式变更​

Hardened Mode（加固模式）​

JavaScript Constraints（约束系统）​

内置插件​

性能改进​

改进的用户界面​

从 Yarn 3 迁移​

插件系统 (yarn 2+)​

常用插件​

常用插件功能​

最佳实践​

1. 使用 Zero-Install​

2. 使用约束​

3. 安全审计​

4. 使用 .yarnignore​

5. 缓存管理​

从 yarn 1 迁移到 yarn 2+​

了解更多​