Yarn 4 中脚本执行时版本回退问题的分析与解决

问题现象

在使用 Yarn 4.6.0 版本时，开发者遇到了一个奇怪的现象：当直接运行 yarn install 命令时，系统正确显示使用的是 Yarn 4.6.0 版本；然而当通过脚本（如 yarn deploy）间接调用 yarn install 时，系统却回退到了 Yarn 1.22.22 版本。

问题重现

典型的 package.json 配置如下：

{
  "name": "app",
  "private": true,
  "type": "module",
  "scripts": {
    "deploy": "git pull && yarn install && yarn build-only"
  },
  "packageManager": "yarn@4.6.0"
}

直接运行 yarn install 时输出正常：

➤ · Yarn 4.6.0
➤ ┌ Resolution step
➤ └ Completed

但运行 yarn deploy 时却显示：

yarn install v1.22.22
[1/4] 🔍  Resolving packages...

问题根源

经过深入分析，发现问题的根本原因在于项目中意外地将 Yarn 作为了项目依赖项。当 Yarn 被列为项目依赖时，Yarn 4 在执行脚本时会优先使用项目本地的 Yarn 版本（如果存在），而不是全局安装的 Yarn 4.6.0 版本。

解决方案

解决此问题的方法很简单：只需从项目依赖中移除 Yarn 即可。具体步骤如下：

1. 检查项目的 package.json 文件
2. 移除 dependencies 或 devDependencies 中关于 Yarn 的条目
3. 确保 packageManager 字段正确指定了所需的 Yarn 版本（如 "yarn@4.6.0"）

技术背景

Yarn 从 2.0 版本开始采用了"零安装"理念，鼓励将包管理器本身作为项目依赖项进行版本控制。这种设计虽然有利于团队协作和版本一致性，但也可能导致一些混淆：

1. 版本优先级：当项目中存在 Yarn 依赖时，Yarn 会优先使用项目本地的版本
2. 全局与本地：全局安装的 Yarn 主要用于创建新项目和执行初始命令，项目具体操作会使用本地版本
3. 版本锁定：packageManager 字段是新引入的规范，用于声明项目所需的包管理器版本

最佳实践

为了避免类似问题，建议开发者：

1. 不要在项目中显式添加 Yarn 作为依赖项
2. 使用 packageManager 字段声明所需的 Yarn 版本
3. 通过 corepack 工具管理不同项目间的包管理器版本
4. 定期检查全局和本地 Yarn 版本是否一致

总结

Yarn 4 的版本管理机制设计旨在提高项目的可重复性和一致性，但这也要求开发者对包管理器的版本控制机制有更深入的理解。通过正确配置 packageManager 字段并避免不必要的依赖项，可以确保项目始终使用预期的 Yarn 版本，从而避免版本回退等意外情况的发生。