GitHub Actions构建Umi报fastRefresh配置无效错误排查修复
问题根因
- 核心触发原因是Umi大版本不兼容:项目
package.json中声明依赖的是Umi 3.x版本("umi": "^3.5.0"),但CI流水线中执行yarn global add umi时未指定版本,yarn默认拉取了最新的Umi 4.0.5版本。 - Umi 3与Umi 4存在不兼容的破坏性变更,配置校验规则差异较大:报错提到的
fastRefresh配置项在Umi4中强制要求必须为布尔值,而项目内的配置是适配Umi3的写法,无法通过Umi4的配置校验,直接抛出断言错误终止构建。 - 本地Mac环境构建正常的原因:本地全局安装的Umi版本为3.x,或者本地执行命令时优先调用了项目
node_modules内的Umi3版本,未出现版本错配;而CI为全新Ubuntu环境,全局安装默认拉取最新大版本,且全局包的二进制路径优先级高于本地依赖,执行umi build时实际调用的是不兼容的Umi4版本。 - 构建日志中出现的eslint peer依赖警告为无关提示,不会导致构建失败。
修复方案
推荐直接移除全局安装Umi的步骤,使用项目本地依赖的Umi版本执行构建,彻底规避全局版本不可控导致的兼容性问题,修改CI配置中的构建步骤为如下内容即可:
- name: Build React App run: | yarn yarn build
方案说明:
- 执行
yarn时会自动按照package.json的声明,安装对应版本的Umi3到项目本地node_modules目录 - 执行
yarn build会自动调用项目scripts中定义的umi build命令,yarn会优先查找本地依赖内的umi二进制文件,版本完全匹配项目要求,不会出现配置校验错误。
如果存在特殊场景必须使用全局安装的Umi,需要在全局安装时明确指定和项目一致的大版本,将安装命令改为yarn global add umi@3,但这种方式不推荐,后续项目升级Umi版本时需要同步修改CI配置,维护成本更高。
内容的提问来源于stack exchange,提问作者Dolphin
相关产品推荐
相关产品推荐

