You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.08.27 09:54:23