如何排查React组件项目中的YARN编译错误

错误根因 #

这个报错的核心是版本不兼容：api.assumption是Babel v7.13.0才新增的API，你项目里react-scripts@4.0.1内置的Babel版本低于这个要求，而它内置引入的@pmmmwh/react-refresh-webpack-plugin新版调用了这个不存在的API，就触发了编译失败。这个插件是react-scripts自带的开发依赖，所以不会出现在你显式声明的dependencies清单里，属于正常情况。

针对性排查解决方向 #

• 方案1：锁定兼容版本的react-refresh-webpack-plugin
  在项目根目录的package.json中新增对应配置强制指定版本：
  • 如果你使用npm v8.3+，添加overrides字段：

  "overrides": {
    "@pmmmwh/react-refresh-webpack-plugin": "0.4.3"
  }
  

  • 如果你使用yarn，添加resolutions字段：

  "resolutions": {
    "@pmmmwh/react-refresh-webpack-plugin": "0.4.3"
  }
  

  配置完成后删除node_modules文件夹和锁文件（package-lock.json或yarn.lock），重新执行依赖安装命令即可。
• 方案2：升级react-scripts到兼容版本
  你当前使用的react-scripts@4.0.1版本较旧，直接升级到4.0.3以上的4.x稳定版，或是5.x版本即可解决内置依赖的版本不兼容问题，升级后同样需要重新安装依赖。
• 方案3：临时关闭热重载绕开报错
  仅做临时调试用的话，可以在项目根目录新建.env文件，添加一行配置FAST_REFRESH=false，关闭React Refresh热重载功能即可绕开该报错，不建议长期使用该方案。

这类Babel/Webpack编译错误通用排查步骤 #

• 第一步：定位错误归属
  先看报错路径是属于自己编写的业务代码，还是node_modules下的第三方依赖，如果是第三方依赖报错，优先排查版本兼容问题。
• 第二步：追溯依赖来源
  没有在package.json显式声明的依赖都是其他包的间接依赖，执行npm ls [报错依赖名]或yarn why [报错依赖名]即可查到引入该依赖的父级包，比如本次报错可以执行npm ls @pmmmwh/react-refresh-webpack-plugin确认是react-scripts引入的依赖。
• 第三步：匹配兼容版本
  查报错依赖的官方更新日志，确认触发报错的API/特性是哪个版本新增的，或是哪个版本开始不再兼容你当前使用的父级包版本，锁定匹配的兼容版本即可。
• 第四步：兜底验证
  不确定版本问题时，可以直接删除node_modules文件夹和锁文件，重新安装依赖，排除锁文件锁定了错误版本的问题。

内容的提问来源于stack exchange，提问作者HVG1928