构建Electron-React应用时提示fs.copySync is not a function报错

报错关联逻辑 #

三个报错是明确的因果连锁关系，不存在独立故障：

• 根触发点：react-scripts build 执行时抛出 fs.copySync is not a function 错误，编译进程以状态码1退出，直接触发npm的ELIFECYCLE脚本生命周期错误
• 第一重连锁反应：React构建流程中途中断，build目录下不会生成打包所需的前端静态资源、electron.js入口等文件
• 第二重连锁反应：后续执行的electron-builder找不到有效构建输入，无法完成asar归档流程，最终抛出app.asar不存在的错误

根因说明 #

fs.copySync 从来不是Node.js原生fs模块提供的方法，这个API是第三方文件操作库fs-extra的扩展方法。报错意味着构建脚本执行时拿到的是原生fs对象，没有正确加载到fs-extra，结合当前Node v14.17.0环境，基本是两类问题导致：

• 依赖损坏：node_modules存在软链冲突、缓存损坏，或者fs-extra依赖版本不兼容/缺失，导致模块引入时fallback到了原生fs
• 版本兼容问题：react-scripts版本低于4.0.3时，和Node 14存在已知的模块引入逻辑bug，会触发该错误

修复步骤 #

按顺序执行，每步完成后单独跑npx react-scripts build验证，直到构建正常出产物：

1. 彻底清理损坏的依赖与缓存
   执行以下命令清空旧的安装产物：

   rm -rf node_modules package-lock.json
   npm cache clean --force
   

2. 固定兼容版本后重装依赖
   先修改package.json里的依赖配置：
   • 将react-scripts版本固定到4.0.3及以上的4.x稳定版，不要用5.x以上版本，和多数Electron-React旧模板存在兼容冲突
   • 在devDependencies中手动添加"fs-extra": "^10.1.0"，该版本完全适配Node 14环境，不会出现API兼容问题
     修改完成后执行npm install重新安装全量依赖
3. 验证全流程打包
   确认react-scripts build执行成功、build目录生成完整产物后，再执行Mac打包命令即可。

   注：如果React构建正常后electron-builder仍提示找不到入口文件，可把打包脚本里的npm build改成npm run build，避免npm内置build命令和自定义脚本的执行歧义。

4. 兜底方案
   如果以上步骤执行后仍报错，可将Node版本切换到14.x的最终稳定版14.21.3，切换后重新走一遍依赖清理、重装流程即可，Node 14.17.0存在几个已知的模块解析bug，确实会在部分依赖场景下触发异常。

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