Yarn 中文教程

1. 什么是 Yarn？

Yarn 是一个快速、可靠、安全的 JavaScript 包管理器，由 Facebook、Google、Exponent 和 Tilde 联合开发，于 2016 年发布。Yarn 旨在解决 npm 的一些痛点，如安装速度慢、依赖版本不一致等问题。

1.1 Yarn 的核心优势

速度快：Yarn 使用并行下载和缓存机制，大大提高了依赖安装速度。
可靠性：Yarn 使用 yarn.lock 文件确保依赖版本的一致性，避免了 "依赖地狱" 问题。
安全性：Yarn 在安装依赖前会验证包的完整性，防止恶意代码注入。
离线模式：Yarn 可以在离线环境下使用缓存的依赖，无需重新下载。
确定性：无论何时何地安装依赖，Yarn 都会生成相同的依赖树。

2. 安装 Yarn

2.1 使用 npm 安装

npm install -g yarn

2.2 使用 Homebrew 安装（macOS）

brew install yarn

2.3 使用 Chocolatey 安装（Windows）

choco install yarn

2.4 验证安装

yarn --version

3. Yarn 基本命令

3.1 初始化项目

yarn init

3.2 安装依赖

# 安装所有依赖
yarn

# 安装指定包
yarn add <package>

# 安装开发依赖
yarn add <package> --dev

# 安装全局包
yarn global add <package>

3.3 更新依赖

# 更新所有依赖
yarn upgrade

# 更新指定包
yarn upgrade <package>

# 更新到指定版本
yarn upgrade <package>@<version>

3.4 移除依赖

# 移除指定包
yarn remove <package>

# 移除全局包
yarn global remove <package>

3.5 查看依赖

# 查看项目依赖
yarn list

# 查看指定包的信息
yarn info <package>

# 检查依赖树
yarn why <package>

4. Yarn 核心功能

4.1 Workspaces

Yarn Workspaces 允许在单个代码仓库中管理多个包，共享依赖，减少重复安装。

配置示例：

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

使用方法：

# 在根目录安装所有工作区依赖
yarn

# 在指定工作区安装依赖
yarn workspace <workspace-name> add <package>

# 在所有工作区运行脚本
yarn workspaces run <script>

4.2 Plug'n'Play

Yarn Plug'n'Play (PnP) 是一种新的依赖管理方式，它不生成 node_modules 目录，而是使用单个 .pnp.cjs 文件来映射依赖关系，提高安装速度和减少磁盘占用。

启用方法：

yarn config set pnp true

使用 PnP 安装依赖：

yarn install

4.3 Zero-Installs

Yarn Zero-Installs 是一种将依赖缓存直接提交到版本控制系统的方法，使项目在克隆后无需运行 yarn install 即可直接使用。

配置示例：

// .yarnrc.yml
nodeLinker: pnp

// .gitignore
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

5. Yarn 脚本

Yarn 允许在 package.json 中定义自定义脚本，方便项目的构建、测试和部署。

配置示例：

// package.json
{
  "scripts": {
    "start": "node index.js",
    "build": "webpack",
    "test": "jest",
    "lint": "eslint ."
  }
}

运行脚本：

yarn start
yarn build
yarn test
yarn lint

6. Yarn 最佳实践

6.1 依赖管理最佳实践

使用 exact 版本：在 package.json 中使用精确的依赖版本，避免意外的版本更新。
定期更新依赖：使用 yarn upgrade-interactive 定期检查和更新依赖，确保使用最新的安全补丁。
锁定依赖版本：提交 yarn.lock 文件到版本控制系统，确保团队成员使用相同的依赖版本。
使用 peerDependencies：对于插件类库，使用 peerDependencies 声明对宿主库的依赖要求。

6.2 性能优化

使用缓存：Yarn 会自动缓存依赖，减少重复下载。
并行安装：Yarn 默认使用并行下载，提高安装速度。
离线模式：在无网络环境下，使用 yarn install --offline 安装缓存的依赖。
使用 PnP：对于大型项目，考虑使用 Yarn PnP 减少磁盘占用和提高安装速度。

6.3 安全最佳实践

定期检查安全漏洞：使用 yarn audit 检查依赖中的安全漏洞。
使用官方源：默认使用 Yarn 官方源，避免使用不可信的第三方源。
验证包完整性：Yarn 会自动验证包的完整性，确保包没有被篡改。

7. 常见问题与解决方案

7.1 依赖冲突

问题：安装依赖时出现版本冲突。

解决方案：

使用 yarn why <package> 查看依赖树，了解冲突原因。
使用 resolutions 字段在 package.json 中强制指定依赖版本。

// package.json
{
  "resolutions": {
    "<package>": "<version>"
  }
}

7.2 安装速度慢

问题：依赖安装速度慢。

解决方案：

使用国内镜像源，如淘宝镜像。

yarn config set registry https://registry.npmmirror.com

清理缓存，重新安装。
```
yarn cache clean
yarn install
```
考虑使用 Yarn PnP 或 Zero-Installs。

7.3 缓存问题

问题：缓存损坏导致安装失败。

解决方案：

清理缓存。
```
yarn cache clean
```
重新安装依赖。
```
rm -rf node_modules
yarn install
```

8. 总结

Yarn 是一个功能强大的 JavaScript 包管理器，它通过并行下载、缓存机制、版本锁定等特性，解决了 npm 的许多痛点，为开发者提供了更快速、更可靠、更安全的依赖管理体验。

随着 Yarn 2.x 和 3.x 的发布，Yarn 引入了更多先进的特性，如 Workspaces、Plug'n'Play 和 Zero-Installs，进一步提升了依赖管理的效率和可靠性。

无论是小型项目还是大型 monorepo，Yarn 都能为你提供出色的依赖管理解决方案。通过掌握 Yarn 的核心功能和最佳实践，你可以更高效地管理项目依赖，提高开发效率，确保项目的稳定性和安全性。