Yarn 常用命令

Yarn 是一个快速、可靠、安全的 JavaScript 包管理器。目前有 Yarn Classic（1.x）和 Yarn Berry（2.x+）两个主要版本。

安装

bash

# 通过 npm 全局安装（Classic）
npm install -g yarn

# 查看版本
yarn -v

# 启用 Yarn Berry（Corepack 方式）
# Corepack 是 Node.js 内置的包管理器管理工具
corepack enable
yarn set version berry

# 回退到 Classic
yarn set version classic

项目初始化

bash

# 初始化新项目（交互式问答）
yarn init

# 跳过问答，生成默认配置
# -y 表示 yes，所有选项使用默认值
yarn init -y

依赖管理

四种依赖类型说明

类型	安装命令	说明	大白话解释	使用场景
`dependencies`	`yarn add <pkg>`	生产环境依赖	项目运行必须用到的包	vue、react、axios、lodash 等
`devDependencies`	`yarn add -D <pkg>`	开发环境依赖	只在开发时用，打包后不需要	vite、eslint、typescript、jest 等
`peerDependencies`	`yarn add -P <pkg>`	对等依赖	你的包「期望」使用者自己安装的依赖	组件库期望使用者已安装 vue
`optionalDependencies`	`yarn add -O <pkg>`	可选依赖	安装失败不会报错，项目照样能跑	跨平台兼容包、性能优化包

安装依赖

bash

# 安装所有依赖（根据 yarn.lock）
yarn install
yarn                        # 简写，效果一样

# 安装指定包（添加到 dependencies）
yarn add <package>

# 安装指定包（添加到 devDependencies）
# -D 是 --dev 的简写，表示只在开发环境使用
yarn add -D <package>

# 安装指定版本
yarn add <package>@1.2.3

# 安装最新版本
yarn add <package>@latest

# 安装到 peerDependencies
# -P 是 --peer 的简写
yarn add -P <package>

# 安装到 optionalDependencies
# -O 是 --optional 的简写
yarn add -O <package>

# 全局安装
# global add 表示全局安装，安装后可以在任何地方使用命令
yarn global add <package>

# 安装 Git 仓库（直接从 GitHub 安装）
yarn add <package>@github:user/repo
yarn add <package>@git+https://github.com/user/repo.git

# 安装本地包（本地开发调试）
yarn add file:../my-local-package

升级 & 卸载

bash

# 升级指定包（遵守 package.json 中的版本范围）
yarn upgrade <package>

# 升级到最新版本（忽略版本范围，直接装最新）
# --latest 表示忽略版本范围，使用 npm 上的最新版本
yarn upgrade --latest <package>

# 升级所有依赖
yarn upgrade

# 交互式升级（内置命令，交互式界面可以选择要升级的包）
yarn upgrade-interactive

# 卸载指定包
yarn remove <package>

# 全局卸载
yarn global remove <package>

查看依赖

bash

# 列出所有依赖（树形结构）
yarn list

# 列出顶层依赖（不显示嵌套的子依赖）
# --depth 控制显示层级，0 表示只显示顶层
yarn list --depth=0

# 列出指定包的依赖
# --pattern 按包名过滤
yarn list --pattern <package>

# 列出全局安装的包
yarn global list

# 查看某个包的详细信息（版本、依赖、仓库、作者等）
yarn info <package>

# 查看指定版本信息
yarn info <package> version

# 查看包的依赖关系（这个包依赖了哪些其他包）
yarn info <package> dependencies

# 查看为什么安装了某个包（显示依赖链，知道是谁引入的）
yarn why <package>

运行脚本

bash

# 运行 package.json 中定义的脚本
# yarn 不需要 run 关键字，直接 yarn <script-name>
yarn <script-name>

# 示例
yarn dev                       # 启动开发服务器
yarn build                     # 构建生产版本
yarn test                      # 运行测试

# 传递参数给脚本
# -- 是参数分隔符，用于区分 yarn 本身的参数和脚本的参数
# -- 之后的所有参数都会传递给脚本
yarn <script-name> -- <args>

# 示例
yarn test -- --watch
yarn build -- --mode production

# 可以传递多个参数
yarn build -- --mode production --verbose

# 常见工具参数示例：

# Vite 构建工具：
yarn dev -- --port 3001           # 指定开发服务器端口
yarn dev -- --host                # 允许外部访问（局域网其他设备可访问）
yarn build -- --mode staging      # 指定构建模式（staging 是预发布环境）
yarn build -- --outDir dist2      # 指定输出目录

# ESLint 代码检查：
yarn lint -- --fix                # 自动修复可修复的问题
yarn lint -- --ext .js,.ts        # 指定检查的文件扩展名（ESLint 9+ 已废弃此参数）
yarn lint -- --no-error-on-unmatched-pattern  # 无匹配文件时不报错

# Vitest 测试框架：
yarn test -- --watch              # 监听模式，文件变化时重新测试
yarn test -- --coverage           # 生成测试覆盖率报告
yarn test -- --reporter verbose   # 使用详细报告器
yarn test -- --bail 1             # 第一个测试失败后停止

# TypeScript 编译器：
yarn build -- --noEmit            # 只检查类型，不输出文件（常用于类型检查）
yarn build -- --sourceMap         # 生成 source map（调试时定位源码）
yarn build -- --watch             # 监听模式，文件变化时自动编译

📖 创建自定义脚本的详细方法请参考 npm 常用命令

yarn dlx（等同于 npx）

bash

# 直接运行包中的命令（无需安装，临时下载执行）
yarn dlx create-vite my-app
yarn dlx eslint --init
yarn dlx degit user/repo my-app

# 运行指定版本
yarn dlx <package>@<version>

依赖检查

bash

# 安全漏洞检查
yarn audit

# 查看审计报告（只显示中等及以上严重级别的漏洞）
# --level 可选：info、low、moderate、high、critical
yarn audit --level moderate

# 自动修复安全漏洞
yarn audit fix

CI/CD 安装

bash

# CI/CD 环境推荐使用 --frozen-lockfile
# 严格按 yarn.lock 安装，不更新 lock 文件，如果 lock 文件与 package.json 不一致则报错
yarn install --frozen-lockfile

# 等同于 npm ci 的效果
# 确保所有环境安装完全相同的依赖版本

yarn install vs yarn install --frozen-lockfile

特性	yarn install	yarn install --frozen-lockfile
lock 文件	可能更新	严格按 lock 安装，不修改
适用场景	本地开发	CI/CD、自动化部署
速度	较慢（需要解析依赖）	更快（跳过依赖解析）

工作空间（Monorepo）

什么是 Monorepo？

Monorepo（单一仓库）是一种项目管理方式：把多个相关的项目（包）放在同一个代码仓库中管理。

传统方式（Multirepo）：

repo-utils/          # 独立仓库
  └── package.json

repo-components/     # 独立仓库
  └── package.json

repo-app/            # 独立仓库
  └── package.json

Monorepo 方式：

my-project/          # 一个仓库
├── package.json     # 根配置
├── packages/
│   ├── utils/       # 工具库
│   │   └── package.json
│   └── components/  # 组件库
│       └── package.json
└── apps/
    ├── web/         # Web 应用
    │   └── package.json
    └── admin/       # 后台管理
        └── package.json

为什么用 Monorepo？

场景	传统方式	Monorepo
多个项目共享代码	需要发布 npm 包再引用	直接引用本地包，实时生效
修改一个库需要同时改多个项目	需要修改多个仓库	一个仓库内统一修改
统一代码规范和构建工具	每个仓库单独配置	根目录统一配置
查看某次修改影响了哪些项目	需要跨仓库搜索	一个仓库内搜索

什么时候用 Monorepo？

适合：

前端组件库 + 多个使用该组件库的项目
后端微服务（多个服务共享工具库）
全栈项目（前端 + 后端 + 共享类型定义）
工具库开发（一个仓库维护多个 npm 包）

不适合：

完全独立的项目（没有共享代码）
团队成员不熟悉 Monorepo
项目非常大（Git 仓库超过几个 GB）

yarn 工作空间配置

yarn 是最早支持工作空间的包管理器，通过 package.json 的 workspaces 字段配置：

json

{
  "private": true,                    // 私有项目，不发布到 npm
  "workspaces": ["packages/*", "apps/*"]  // 工作空间目录
}

或：

json

{
  "private": true,
  "workspaces": {
    "packages": ["packages/*"],
    "nohoist": ["**/react-native"]  // 不提升到根 node_modules
  }
}

💡 nohoist 用于某些不兼容 hoisting 的包（如 React Native），让它们在自己的 node_modules 中安装依赖。

常用命令

bash

# 安装所有工作空间的依赖（根目录执行一次即可，自动安装所有子项目的依赖）
yarn install

# 在指定工作空间中执行命令
# workspace 后面跟的是 package.json 中的 name 字段
yarn workspace <package-name> run build
yarn workspace @my-org/utils run test

# 在所有工作空间中执行
yarn workspaces run build
yarn workspaces run test

# 添加依赖到指定工作空间
yarn workspace <package-name> add <dependency>

# 添加公共依赖到根目录
# -W 表示根目录（workspace root）
yarn add -W -D <package>

# 查看工作空间信息
yarn workspaces info

工作空间之间互相引用

在 Monorepo 中，一个包可以引用另一个包：

json

// apps/web/package.json
{
  "dependencies": {
    "@my-org/utils": "*",       // 引用本地的 utils 包（* 表示使用本地最新版本）
    "@my-org/components": "*"   // 引用本地的 components 包
  }
}

* 表示使用本地最新版本，yarn 会自动创建软链接到 packages/utils，而不是从 npm 下载。

缓存管理

bash

# 查看缓存目录路径
yarn cache dir

# 列出缓存的包
yarn cache list

# 列出指定包的缓存
# --pattern 按包名过滤
yarn cache list --pattern <package>

# 清除所有缓存
yarn cache clean

# 清除指定包的缓存
yarn cache clean <package>

缓存的作用

提升安装速度：已下载的包会缓存，下次安装直接从缓存读取
离线安装：有缓存时可以离线安装（部分场景）
减少网络请求：避免重复下载相同的包

什么时候需要清理缓存？

安装失败且提示缓存相关错误
缓存占用空间过大
切换镜像源后需要清理旧缓存

配置管理

bash

# 查看所有配置
yarn config list

# 查看某个配置
yarn config get registry

# 设置配置（Yarn Berry）
yarn config set npmRegistryServer https://registry.npmmirror.com
yarn config set nodeLinker node-modules

# 删除配置
yarn config unset npmRegistryServer

# 编辑配置文件
yarn config edit

镜像源配置

bash

# Yarn Classic (1.x)：通过 .yarnrc 文件
echo 'registry "https://registry.npmmirror.com"' > .yarnrc

# Yarn Berry (2.x+)：通过 yarn config 命令
yarn config set npmRegistryServer https://registry.npmmirror.com

# 查看当前配置
yarn config get npmRegistryServer

# 恢复官方镜像源
yarn config set npmRegistryServer https://registry.yarnpkg.com

.yarnrc.yml（Berry 配置文件）

yaml

# .yarnrc.yml

# 镜像源配置（国内用户推荐使用淘宝镜像）
npmRegistryServer: https://registry.npmmirror.com

# 安装模式
# node-modules: 传统 node_modules 结构（推荐，兼容性最好）
# pnp: Plug'n'Play（无 node_modules，速度快但部分工具不兼容）
nodeLinker: node-modules

# 启用全局缓存（多个项目共享同一份依赖缓存）
enableGlobalCache: true

# 严格模式（禁止未声明的依赖，防止幽灵依赖）
pnpMode: strict

# 自动安装 Peer Dependencies
autoInstallPeers: true

# 压缩安装日志（过滤掉指定类型的日志）
logFilters:
  - code: YN0006
    level: discard

yarn.lock 文件

什么是 yarn.lock 文件？

yarn.lock 是 Yarn 自动生成的依赖锁定文件，记录了每个依赖的精确版本和下载地址。

为什么需要 yarn.lock？

问题	没有 lock 文件	有 lock 文件
版本不一致	不同环境安装的版本可能不同	所有环境安装完全相同的版本
构建失败	依赖更新导致构建失败	依赖版本固定，构建稳定
协作问题	团队成员依赖版本不一致	团队成员使用相同版本

yarn.lock 必须提交到 Git

bash

# .gitignore 中不要忽略 yarn.lock
# 但要忽略 node_modules
node_modules/

yarn.lock 冲突解决

bash

# 方案一：删除重新安装（简单粗暴，推荐新手）
rm -rf node_modules yarn.lock
yarn install

# 方案二：只更新 lock 文件（不安装依赖）
yarn install --mode update-lockfile

# 方案三：强制解析版本冲突（自动合并重复依赖）
yarn dedupe

# 使用最高版本策略去重
yarn dedupe --strategy highest

Yarn Berry 特性

Plug'n'Play（PnP）

什么是 PnP？

传统方式下，npm install 或 yarn install 会创建一个巨大的 node_modules 目录，里面包含了所有依赖包。PnP 模式完全不同：它不创建 node_modules，而是把依赖信息记录在一个 .pnp.cjs 文件中，告诉你每个包在哪里。

为什么用 PnP？

安装速度快：不需要复制文件到 node_modules，只需生成一个配置文件
磁盘占用小：依赖包存在全局缓存中，多个项目共享同一份
解决幽灵依赖问题：幽灵依赖是指你没有在 package.json 中声明，但因为 npm 扁平化 node_modules 结构而能意外引用到的包。PnP 通过严格隔离解决了这个问题

PnP 的问题：

部分工具不兼容（需要安装兼容包）
IDE 需要插件支持（VSCode 需要安装 ZipFS 扩展）

bash

# 启用 PnP
yarn set version berry
yarn config set nodeLinker pnp

# 安装依赖（生成 .pnp.cjs）
yarn install

# 运行项目（自动使用 PnP 解析）
yarn dev

Zero-Installs

什么是 Zero-Installs？

Zero-Installs 是 PnP 的进阶用法：把依赖缓存直接提交到 Git 仓库中。这样团队成员 clone 代码后，无需执行 yarn install，直接就能运行项目。

为什么用 Zero-Installs？

省去安装步骤：clone 后直接运行，不用等 install
CI/CD 更快：跳过安装步骤，构建速度更快
保证一致性：所有人用的都是完全相同的依赖

缺点：

仓库体积会变大（依赖缓存会占用几十到几百 MB）
每次更新依赖都要提交缓存文件

bash

# 将依赖缓存提交到 Git，实现零安装
yarn config set nmMode hardlinks-local
yarn install

# 提交以下文件到 Git
# .yarn/cache/     → 依赖缓存
# .pnp.cjs         → PnP 解析器
# .pnp.loader.mjs  → ESM 加载器

常见问题

EACCES 权限错误（全局安装）

bash

# 修改全局安装目录
yarn config set prefix ~/.yarn-global

# 将路径加入 PATH 环境变量
export PATH="$HOME/.yarn-global/bin:$PATH"

安装速度慢

bash

# Yarn Classic (1.x)：配置镜像源
echo 'registry "https://registry.npmmirror.com"' > .yarnrc

# Yarn Berry (2.x+)：配置镜像源
yarn config set npmRegistryServer https://registry.npmmirror.com

node_modules 依赖冲突

bash

# 清理后重新安装
rm -rf node_modules yarn.lock
yarn install

# 使用 dedupe 去重（自动合并重复依赖）
yarn dedupe

PnP 模式下工具报错

bash

# 方案一：切换到 node-modules 模式（推荐，兼容性最好）
yarn config set nodeLinker node-modules
yarn install

# 方案二：安装兼容包
yarn add -D @yarnpkg/pnpify
yarn pnpify --sdk vscode

与 npm 的命令对照

操作	npm	yarn	pnpm	cnpm
安装依赖	`npm install`	`yarn install`	`pnpm install`	`cnpm install`
添加包	`npm install <pkg>`	`yarn add <pkg>`	`pnpm add <pkg>`	`cnpm install <pkg>`
添加开发依赖	`npm i -D <pkg>`	`yarn add -D <pkg>`	`pnpm add -D <pkg>`	`cnpm install -D <pkg>`
删除包	`npm uninstall <pkg>`	`yarn remove <pkg>`	`pnpm remove <pkg>`	`cnpm uninstall <pkg>`
运行脚本	`npm run <script>`	`yarn <script>`	`pnpm run <script>`	`cnpm run <script>`
全局安装	`npm i -g <pkg>`	`yarn global add <pkg>`	`pnpm add -g <pkg>`	`cnpm install -g <pkg>`
npx	`npx <pkg>`	`yarn dlx <pkg>`	`pnpm dlx <pkg>`	`npx <pkg>`
审计	`npm audit`	`yarn audit`	`pnpm audit`	`npm audit`
CI/CD 安装	`npm ci`	`yarn --frozen-lockfile`	`pnpm install --frozen-lockfile`	`npm ci --registry=https://registry.npmmirror.com`

Yarn 常用命令 ​

安装 ​

项目初始化 ​

依赖管理 ​

四种依赖类型说明 ​

安装依赖 ​

升级 & 卸载 ​

查看依赖 ​

运行脚本 ​

yarn dlx（等同于 npx） ​

依赖检查 ​

CI/CD 安装 ​

yarn install vs yarn install --frozen-lockfile ​

工作空间（Monorepo） ​

什么是 Monorepo？ ​

为什么用 Monorepo？ ​

什么时候用 Monorepo？ ​

yarn 工作空间配置 ​

常用命令 ​

工作空间之间互相引用 ​

缓存管理 ​

缓存的作用 ​

什么时候需要清理缓存？ ​

配置管理 ​

镜像源配置 ​

.yarnrc.yml（Berry 配置文件） ​

yarn.lock 文件 ​

什么是 yarn.lock 文件？ ​

为什么需要 yarn.lock？ ​

yarn.lock 必须提交到 Git ​

yarn.lock 冲突解决 ​

Yarn Berry 特性 ​

Plug'n'Play（PnP） ​

Zero-Installs ​

常见问题 ​

EACCES 权限错误（全局安装） ​

安装速度慢 ​

node_modules 依赖冲突 ​

PnP 模式下工具报错 ​

与 npm 的命令对照 ​

参考 ​

Yarn 常用命令

安装

项目初始化

依赖管理

四种依赖类型说明

安装依赖

升级 & 卸载

查看依赖

运行脚本

yarn dlx（等同于 npx）

依赖检查

CI/CD 安装

yarn install vs yarn install --frozen-lockfile

工作空间（Monorepo）

什么是 Monorepo？

为什么用 Monorepo？

什么时候用 Monorepo？

yarn 工作空间配置

常用命令

工作空间之间互相引用

缓存管理

缓存的作用

什么时候需要清理缓存？

配置管理

镜像源配置

.yarnrc.yml（Berry 配置文件）

yarn.lock 文件

什么是 yarn.lock 文件？

为什么需要 yarn.lock？

yarn.lock 必须提交到 Git

yarn.lock 冲突解决

Yarn Berry 特性

Plug'n'Play（PnP）

Zero-Installs

常见问题

EACCES 权限错误（全局安装）

安装速度慢

node_modules 依赖冲突

PnP 模式下工具报错

与 npm 的命令对照

参考