按指引操作未生成yarnrc.yml致Heroku Node.js应用构建失败

问题根因 #

执行yarn set version berry或yarn set version 2仅会下载对应版本的Yarn二进制文件到.yarn/releases目录，不会自动生成.yarnrc.yml配置文件，只有执行过Yarn配置修改、或首次通过yarn init -2初始化Berry版本项目时才会自动创建该文件，单纯执行yarn install不会触发文件写入，这是Yarn版本切换逻辑里的常见误区。

解决步骤 #

• 第一步：确认本地项目Yarn版本切换生效
  在项目根目录执行yarn -v，如果返回版本号为1.x，说明全局Yarn 1的路径优先级高于项目本地版本，先执行corepack enable（Node.js 16+版本自带corepack工具）绑定项目级Yarn版本，再重新执行yarn set version berry，直到yarn -v返回2.x/3.x版本号。
• 第二步：生成缺失的配置文件
  不需要等待自动生成，直接在项目根目录执行yarn config set enableGlobalCache false，命令执行后会自动在根目录创建.yarnrc.yml文件并写入对应配置。如果不想修改缓存配置，也可以直接手动在根目录新建名为.yarnrc.yml的空白文件，Yarn和Heroku识别到该文件就会判定当前项目使用Yarn 2+版本。

  注意：文件名必须是带开头点的隐藏文件格式.yarnrc.yml，不要创建不带点的yarnrc.yml，Windows系统无法直接右键新建点开头文件时，可以命名为.yarnrc.yml.，系统会自动截断末尾的点生成正确文件。

• 第三步：补全构建必要配置
  打开生成的.yarnrc.yml，补充以下基础配置，避免Heroku构建时出现依赖解析错误：

  nodeLinker: node-modules
  yarnPath: .yarn/releases/yarn-3.2.1.cjs
  

  其中yarnPath的值替换为你本地.yarn/releases目录下实际存在的cjs文件名，和你之前执行set version下载的版本对应；nodeLinker: node-modules是为了兼容Heroku默认的依赖解析逻辑，避免默认PnP模式导致的构建找不到依赖问题。
• 第四步：确认文件被Git跟踪
  检查项目根目录的.gitignore文件，确认没有把.yarnrc.yml、.yarn/releases/目录加入忽略规则，执行git status能看到这两个待提交项即可，不需要提交.yarn/cache目录（零安装模式除外）。
• 第五步：本地验证后重新部署
  本地删除node_modules目录后重新执行yarn install，确认依赖安装无报错，将变更提交到Git后重新推送到Heroku即可正常构建。

常见踩坑提醒 #

• 本地执行Yarn命令时如果始终是1.x版本，大概率是全局Yarn路径优先级问题，优先用corepack绑定项目版本，不要反复执行set version做无效操作。
• 不要把Yarn 1时代的.yarnrc（无yml后缀）文件和Yarn 2+的.yarnrc.yml混淆，两个文件格式完全不通用，Heroku构建Yarn 2+项目只识别.yarnrc.yml。

内容的提问来源于stack exchange，提问作者Mr.C