分步说明

提示

你可能听说过 Yarn Plug'n'Play，并担心你的项目尚不兼容。别担心！

¥You may have heard about Yarn Plug'n'Play and be worried that your project isn't compatible yet. Don't worry!

此迁移将允许你保留 node_modules 文件夹。只有在我们完成后，你才必须决定是否要花时间迁移到 Yarn PnP。无论你这样做还是留在 node_modules 上，迁移到 Yarn Modern 都会有 许多好处。

¥This migration will let you keep your node_modules folder. It's only once we're done that you'll have to decide whether you want to spend time migrating to Yarn PnP. Whether you do it or stay on node_modules, migrating to Yarn Modern will have many benefits.

信息

请注意，这些命令只需为整个项目运行一次，并且只要启用了 Corepack，这些命令就会在你的所有贡献者拉取分支后自动生效。

¥Note that those commands only need to be run once for the whole project and will automatically take effect for all your contributors as soon as they pull the branch, as long as they have Corepack enabled.

迁移步骤

¥Migration steps

1. 确保你使用的是 Node 18+

   ¥Make sure you're using Node 18+

2. 运行 corepack enable 以激活 Corepack

   ¥Run corepack enable to activate Corepack

3. 进入你的项目目录

   ¥Go into your project directory

4. 运行 yarn set version berry

   ¥Run yarn set version berry

5. 将你的 .npmrc 和 .yarnrc 文件转换为 .yarnrc.yml（详情见 此处）

   ¥Convert your .npmrc and .yarnrc files into .yarnrc.yml (details here)

6. 运行 yarn install 来迁移锁定文件

   ¥Run yarn install to migrate the lockfile

7. 提交所有更改

   ¥Commit all changes

很好，你现在应该有一个可以正常工作的 Yarn 安装！有些事情可能仍需要对 CI 脚本进行一些调整（例如弃用 任意 pre/post 脚本，或将 --frozen-lockfile 重命名为 --immutable），但至少我们有一个可运行的项目。

¥Good, you should now have a working Yarn install! Some things might still require some adjustments in your CI scripts (for example the deprecation of arbitrary pre/post-scripts, or the renaming of --frozen-lockfile into --immutable), but at least we have a working project.

重大变化

¥Breaking changes

将你的配置更新为新设置

¥Update your configuration to the new settings

Modern 使用与 Classic 不同的配置文件样式。虽然对于锁文件来说几乎是不可见的（因为我们会动态转换它们），但如果你依赖 .npmrc 或 .yarnrc 文件，它可能会导致问题。

¥Modern uses a different style of configuration files than Classic. While mostly invisible for the lockfile (because we convert them on the fly), it might cause issues if you rely on .npmrc or .yarnrc files.

• Yarn Modern 现在使用 .yarnrc.yml。现在忽略任何其他文件 - 这包括 .npmrc。

  ¥Yarn Modern now uses .yarnrc.yml. Any other file is now ignored - this includes .npmrc.

• 从新的文件扩展名可以看出，Yarnrc 文件现在要用 YAML 编写。

  ¥As evidenced by the new file extension, the Yarnrc files are now to be written in YAML.

大多数配置键也已重命名以更加一致。可以在 .yarnrc.yml 专用文档 上找到可用设置的完整列表，但以下是一些重要的设置：

¥Most configuration keys have also been renamed to be more consistent. The comprehensive list of available settings can be found on the .yarnrc.yml dedicated documentation, but here are some important ones:

• 现在通过 npmRegistryServer 配置自定义注册表。

  ¥Custom registries are now configured via npmRegistryServer.

• 注册表身份验证令牌现在通过 npmAuthToken 配置。

  ¥Registry authentication tokens are now configured via npmAuthToken.

明确调用 pre 和 post 脚本

¥Explicitly call the pre and post scripts

为了明确其目的并消除令人困惑的行为，对 生命周期脚本 的工作方式进行了一些更改。其中一个变化是自定义 pre 和 post 脚本不再受支持。因此，重写：

¥Some changes were made to how lifecycle scripts work in order to clarify their purpose and remove confusing behaviors. One such change is that custom pre and post scripts are no longer supported. As a result, rewrite:

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

进入：

¥Into:

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

注意

这仅适用于用户脚本，例如 start 及相关脚本。使用 preinstall、install 和 postinstall 中的任何一个都可以。有关更多信息，请参阅 脚本文档。

¥This only applies to user scripts, such as start & friends. It's still fine to use any of preinstall, install, and postinstall. Consult the script documentation for more information.

使用 yarn dlx 而不是 yarn global

¥Use yarn dlx instead of yarn global

Yarn 专注于项目管理，管理系统范围的软件包被认为超出了我们的范围。因此，yarn global 已删除 需要由 yarn dlx 替换才能运行一次性脚本。

¥Yarn focuses on project management, and managing system-wide packages was deemed to be outside of our scope. As a result, yarn global got removed and needs to be replaced by yarn dlx to run one off scripts.

不要使用 bundleDependencies

¥Don't use bundleDependencies

bundleDependencies 字段（或 bundledDependencies）是过去的产物，用于让你定义一组将按原样存储在包存档中的包，node_modules 和所有内容。此功能存在许多问题：

¥The bundleDependencies field (or bundledDependencies) is an artifact of the past that used to let you define a set of packages that would be stored as-is within the package archive, node_modules and all. This feature has many problems:

• 它使用 node_modules，而 Plug'n'Play 安装下不存在 node_modules。

  ¥It uses node_modules, which doesn't exist under Plug'n'Play installs.

• 它对包内的提升进行编码，与其他包的提升混淆。

  ¥It encodes the hoisting inside the package, messing with the hoisting from other packages.

那么如何替换它们？有不同的方法：

¥So how to replace them? There are different ways:

• 如果你需要修补包，只需分叉它或通过 file: 协议 引用它（即使对于传递依赖，使用此协议也是完全没问题的）。portal: 和 patch: 协议也是选项，尽管它们仅适用于 Yarn 消费者。

  ¥If you need to patch a package, just fork it or reference it through the file: protocol (it's perfectly fine even for transitive dependencies to use this protocol). The portal: and patch: protocols are also options, although they'll only work for Yarn consumers.

• 如果你需要将包作为独立包（无依赖）发送给客户，请使用 Esbuild、Webpack、Rollup 或类似工具自行打包。

  ¥If you need to ship a package to your customers as a standalone (no dependencies), bundle it yourself using Esbuild, Webpack, Rollup, or similar tools.

用 nmHoistingLimits 替换 nohoist

¥Replace nohoist by nmHoistingLimits

Yarn Classic 中的 nohoist 设置是为 React Native 构建的，以支持工作区，但它的工作方式（通过 glob 模式）导致了很多错误和混乱，没有人真正确定需要设置哪些模式。因此，我们简化了此功能，以便仅支持三种已识别的模式。

¥The nohoist setting from Yarn Classic was built for React Native in order to support workspaces, but the way it worked (through glob patterns) was causing a lot of bugs and confusion, no one being really sure which patterns needed to be set. As a result, we've simplified this feature in order to only support three identified patterns.

如果你使用的是 nohoist，我们建议你将其从清单配置中删除，而是在 .yarnrc.yml 文件中设置 nmHoistingLimits：

¥If you were using nohoist, we recommend you remove it from your manifest configuration and instead set nmHoistingLimits in your .yarnrc.yml file:

nmHoistingLimits: workspaces

CLI 更改

¥CLI changes

已重命名的命令

¥Renamed commands

Yarn Classic (1.x)	Yarn Modern
yarn audit	yarn npm audit
yarn create	yarn dlx create-NAME
yarn global	yarn dlx(阅读更多)
yarn info	yarn npm info
yarn list	yarn info -AR(--json?)
yarn login	yarn npm login
yarn logout	yarn npm logout
yarn outdated	yarn upgrade-interactive(阅读更多)
yarn publish	yarn npm publish
yarn upgrade	yarn up（注意：更新所有工作区）
yarn install --production	yarn workspaces focus --all --production

已删除的命令

¥Removed commands

Yarn Classic (1.x)	注意事项
yarn check	现在在常规安装中检查缓存完整性 - 阅读更多
yarn import	首先导入到 Classic，然后迁移到 Yarn Modern
yarn licenses	插件的完美用例 - 阅读更多
yarn versions	使用 yarn --version 和 node -p process.versions

尚未实现

¥Not implemented yet

这些功能尚未实现。欢迎帮助！

¥Those features simply haven't been implemented yet. Help welcome!

Yarn Classic (1.x)	注意事项
yarn owner	最终将作为 yarn npm owner 提供
yarn team	最终将作为 yarn npm team 提供