Yarn Berry 从 Classic 到 Modern 的迁移指南

前言

Yarn Berry（也称为 Yarn Modern）是 Yarn 包管理器的下一代版本，它带来了许多改进和新特性。对于正在使用 Yarn Classic（1.x 版本）的项目来说，迁移到 Yarn Berry 是一个值得考虑的选择。本文将详细介绍如何将项目从 Yarn Classic 平滑迁移到 Yarn Berry。

迁移前的准备

系统要求

在开始迁移前，请确保满足以下条件：

• 已安装 Node.js 18 或更高版本
• 已在系统中启用 Corepack（Node.js 内置的包管理器管理器）

注意事项

1. 迁移过程会保留现有的 node_modules 目录，因此不必担心项目兼容性问题
2. 迁移完成后，你可以自行决定是否要使用 Yarn Plug'n'Play 特性
3. 所有迁移命令只需在项目中执行一次，团队成员拉取代码后会自动生效

详细迁移步骤

1. 启用 Corepack

corepack enable

Corepack 是 Node.js 自带的工具，用于管理不同版本的包管理器。

2. 进入项目目录

cd /path/to/your/project

3. 设置 Yarn Berry 版本

yarn set version berry

此命令会将项目切换到 Yarn Berry 版本。

4. 配置文件转换

将现有的 .npmrc 和 .yarnrc 文件转换为新的 .yarnrc.yml 格式。Yarn Berry 使用 YAML 格式的配置文件，旧格式的配置文件将被忽略。

5. 重新安装依赖

yarn install

此命令会迁移 lockfile 并安装依赖。

6. 提交变更

完成上述步骤后，将所有变更提交到版本控制系统。

主要变更点详解

配置文件的重大变化

1. 文件格式：从 .npmrc 和 .yarnrc 变为 .yarnrc.yml
2. 配置项重命名：
   • 自定义 registry 现在通过 npmRegistryServer 配置
   • 认证 token 现在通过 npmAuthToken 配置

脚本系统的变更

Yarn Berry 对生命周期脚本进行了简化：

1. 不再自动执行 pre/post 脚本：需要显式调用

   {
     "scripts": {
       "start": "yarn prestart && http-server",
       "prestart": "do-something"
     }
   }
   

2. 例外：preinstall、install 和 postinstall 仍保持自动执行

全局包管理的变化

Yarn Berry 移除了 yarn global 命令，改为使用 yarn dlx 来运行一次性脚本：

yarn dlx create-react-app my-app

bundleDependencies 的替代方案

bundleDependencies 已被弃用，替代方案包括：

1. 使用 file: 协议引用本地包
2. 使用 portal: 或 patch: 协议（仅适用于 Yarn 项目）
3. 使用打包工具（如 Webpack、Rollup）自行打包

nohoist 的替代方案

nohoist 被替换为更简单的 nmHoistingLimits 配置：

nmHoistingLimits: workspaces

命令行工具变更对照表

重命名的命令

Yarn Classic	Yarn Berry
yarn audit	yarn npm audit
yarn create	yarn dlx create-NAME
yarn info	yarn npm info
yarn list	yarn info -AR
yarn upgrade	yarn up

已移除的命令

命令	说明
yarn check	现在在常规安装时自动检查缓存完整性
yarn import	需要先导入到 Classic 再迁移
yarn licenses	可通过插件实现

尚未实现的命令

命令	状态
yarn owner	计划实现为 yarn npm owner
yarn team	计划实现为 yarn npm team

结语

迁移到 Yarn Berry 虽然需要一些调整，但带来的性能提升和新特性值得这些努力。按照本文的步骤操作，可以确保迁移过程顺利进行。如果在迁移过程中遇到问题，可以参考 Yarn 官方文档或社区资源寻求帮助。