Yarn Classic 与现代 Yarn：版本固定、安装和迁移

Yarn 有不兼容的主版本代际：Yarn 1（Classic）和 Yarn 2+（现代 Yarn）在配置、安装策略和命令选项上存在差异。进入仓库先看 package.json 的 packageManager、yarn.lock 文件头、.yarnrc/.yarnrc.yml、README 与 CI；不要看到 yarn 命令就把任意最新版全局装上去。

1. 确认项目使用的 Yarn 版本

node --version
yarn --version
git status --short

项目 manifest 可以固定 package manager，例如 "packageManager": "yarn@4.9.2"；示例版本应替换成项目已经验证过的版本。Corepack 会依据项目声明选择 Yarn，但 Node.js 自带 Corepack 的范围有限：它随 Node 14.19/16.9 至 Node 24 分发，Node 25 起不再捆绑。若提示找不到 corepack，先按 Corepack 与 Yarn 官方说明安装受信任版本，再处理 shim；不要通过随手 npm install -g yarn 覆盖项目选择。

2. 固定 Yarn 并初始化新项目

在支持 Corepack 的环境中启用 shim；Node 25+ 需要先独立安装 Corepack。按组织的软件来源策略选择经过验证的 Corepack 版本：

# Node 25+ 且当前环境没有 corepack 时才需要安装
npm install --global corepack
corepack enable

若机器已由 Volta、asdf、fnm 或其他工具管理 shim，先阅读其官方集成说明，不要让多个工具争抢同一个 yarn 命令。初始化新项目时使用当前 Yarn 文档的命令，并在提交前审阅生成的 package.json、lockfile 与 .yarnrc.yml：

yarn init -2
yarn set version stable
yarn --version

yarn set version 会影响仓库中的 package manager 约定或配置；不要在现有项目里为追新版本直接运行。升级前先阅读对应迁移指南，在独立分支处理 lockfile、插件和 CI。

3. 常见依赖和脚本操作

yarn add <package>
yarn add -D <dev-tool>
yarn remove <package>
yarn up <package>
yarn run build
yarn run test

使用仓库选定的 Yarn 主版本查看具体命令语义；Yarn 1 和 Yarn 4 的参数并非处处相同。加入依赖时检查依赖类型、版本范围、脚本和许可证。不要运行 yarn upgrade 或通配符更新后不看 lockfile diff；依赖升级必须通过测试与兼容审阅。

4. 锁文件与可复现安装

Yarn 1 的 CI 常用 yarn install --frozen-lockfile；现代 Yarn 以 yarn install --immutable 阻止改写 lockfile，后者在 CI 默认启用。若项目采用 Zero-Installs 并提交缓存，可按项目策略运行：

yarn install --immutable

只有仓库确认采用 Zero-Installs 时才使用缓存相关检查：

yarn install --immutable --immutable-cache --check-cache

--immutable-cache 会拒绝缓存目录变化，--check-cache 会重新校验包校验和；这是 Zero-Installs/接收外部 PR 时的特定校验，不是每个项目都需要提交缓存。不要同时在同一项目混用 package-lock.json、yarn.lock 和 pnpm-lock.yaml；如果仓库已有多个锁文件，先向维护者确认权威文件，不要自行删改。

5. PnP、node_modules 与编辑器

现代 Yarn 可以通过 nodeLinker 选择 Plug'n'Play、传统 node_modules 或 pnpm 风格链接器。PnP 取消常规逐包 node_modules 布局，部分旧工具、脚本或编辑器插件可能需要调整。先检查 .yarnrc.yml、项目插件兼容性和 CI，再迁移；必要时评估 nodeLinker: node-modules 作为受控过渡，而不是默认把故障归咎为 Yarn 错误。

PnP 项目可能需要生成编辑器 SDK，相关文件应遵守仓库的提交策略。也要检查依赖的安装构建脚本和 Yarn lifecycle 配置；lockfile 固定解析结果不代表第三方包脚本天然可信。

6. Registry 与凭据

现代 Yarn 的 registry 与 npm 配置格式不完全相同。先查询 yarn config get npmRegistryServer、审阅 .yarnrc.yml，再按 scope 配置组织批准的 registry。认证令牌必须 scope 到正确 registry host/path，并保存在 CI Secret 或用户级配置中；不要提交明文 token、私有 registry 密码或带凭据 URL。

失败时检查 lockfile 中的来源、证书和网络日志，不要禁用 TLS 校验或使用来历不明的镜像。安装 registry 和包发布目标也不是一回事，发布前根据 publishConfig、scope、访问权限和团队流程再次确认。

7. 从 Yarn Classic 迁移

迁移前记录当前 Yarn 1 版本、Node 版本、CI 安装命令、lockfile 状态和所有 scripts。使用独立分支升级 Yarn；按现代 Yarn Migration 指南检查 .yarnrc.yml、lockfile、插件、patches、工作区、PnP 与 node_modules 工具兼容。先让开发机和 CI 使用同一固定版本，再比较依赖树和构建输出。

迁移验收至少包含干净克隆安装、immutable lockfile 校验、开发/测试/生产构建、编辑器解析、CI 缓存和发布流程。出现解析差异时先定位依赖声明或配置，不要直接删除锁文件重新生成并接受整份无审阅差异。

官方资料：Yarn 安装与版本管理、Corepack、Yarn install、现代 Yarn 配置、Manifest 与 packageManager、Yarn Classic 安装文档。