create-react-app运行npm start报terser-webpack-plugin模块找不到错误

问题表现 #

• 基于create-react-app搭建的项目此前运行正常，未修改过react-scripts相关配置，也未改动任何package.json文件，突然在运行npm start时触发报错
• 本地已安装terser-webpack-plugin依赖，查看其package.json文件，main字段配置正常，值为"main": "dist/index.js"
• 已尝试重新安装node_modules依赖、参考网上webpack5适配terser-webpack-plugin的方案调整，问题均未解决
• 运行时抛出的完整错误信息如下：

throw err;
      ^

Error: Cannot find module 'Z:\Documents\chat-test\my-app\node_modules\terser-webpack-plugin\dist\index.js'. Please verify that the package.json has a valid "main" entry
    at tryPackage (node:internal/modules/cjs/loader:353:19)
    at Function.Module._findPath (node:internal/modules/cjs/loader:566:18)
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:919:27)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (Z:\Documents\chat-test\my-app\node_modules\react-scripts\config\webpack.config.js:18:22)
    at Module._compile (node:internal/modules/cjs/loader:1101:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
    at Module.load (node:internal/modules/cjs/loader:981:32) {
  code: 'MODULE_NOT_FOUND',
  path: 'Z:\\Documents\\chat-test\\my-app\\node_modules\\terser-webpack-plugin\\package.json',
  requestPath: 'terser-webpack-plugin'
}

问题根因 #

这个报错和配置修改无关，核心原因是terser-webpack-plugin依赖包安装不完整，包内的dist目录实际缺失，Node按照package.json的main字段寻址时找不到对应文件。常见触发场景有两个：一是npm本地缓存损坏，单纯删除node_modules重装时会从损坏的缓存里拉取不完整的包；二是Windows系统下的安全防护软件误删了terser-webpack-plugin里的脚本文件，这类代码压缩混淆相关的脚本经常被误判为风险文件隔离。

修复步骤 #

• 第一步：彻底清理残留依赖和本地缓存，在项目根目录执行以下命令：

# Windows环境下删除node_modules文件夹和lock文件
rd /s /q node_modules
del package-lock.json
# 强制清除npm本地缓存
npm cache clean --force

• 第二步：安装和当前react-scripts版本匹配的terser-webpack-plugin，不要盲目安装最新版避免webpack版本不兼容。先执行npm list react-scripts查看本地react-scripts版本，对应安装其依赖列表中指定的terser-webpack-plugin版本即可，比如react-scripts 5.x版本对应执行：

npm install terser-webpack-plugin@5.3.6 --save-dev

• 第三步：重新安装全量项目依赖

npm install

• 第四步：执行npm start验证启动是否正常

如果以上操作完成后仍然复现报错，直接打开本地安全防护软件的隔离区，检查是否存在terser-webpack-plugin/dist/index.js相关的隔离记录，恢复文件并将项目node_modules目录加入防护白名单即可。

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