分步说明
你可能听说过 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.
迁移步骤
¥Migration steps
-
确保你使用的是 Node 18+
¥Make sure you're using Node 18+
-
运行
corepack enable
以激活 Corepack¥Run
corepack enable
to activate Corepack -
进入你的项目目录
¥Go into your project directory
-
运行
yarn set version berry
¥Run
yarn set version berry
-
将你的
.npmrc
和.yarnrc
文件转换为.yarnrc.yml
(详情见 此处)¥Convert your
.npmrc
and.yarnrc
files into.yarnrc.yml
(details here) -
运行
yarn install
来迁移锁定文件¥Run
yarn install
to migrate the lockfile -
提交所有更改
¥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). Theportal:
andpatch:
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 team | 最终将作为 提供 |