React JS无法启动开发服务器 npm start报模块解析编译错误

算力阿峰

2026-8-30

报错根因

你使用的react-scripts（Create React App内置构建工具）版本自带的babel/webpack解析规则，默认不会转译node_modules目录下的第三方依赖代码。而你安装的htmlparser2高版本使用了export * as DomUtils from "domutils"这类较新的ESM聚合导出语法，超出了老版本构建工具的默认语法识别范围，直接触发解析失败。

修复方案（按操作成本从低到高排序）

方案1：锁定htmlparser2兼容版本（无额外配置改动，最快修复）
直接在项目根目录执行命令，将htmlparser2降级到适配旧构建工具的稳定版本：
```
# npm用户执行
npm install htmlparser2@7.2.0 --save-exact
# yarn用户执行
yarn add htmlparser2@7.2.0 --exact
```
执行完成后删除项目下的node_modules文件夹、package-lock.json（yarn用户删yarn.lock），重新执行npm install安装依赖后再运行npm start即可。
方案2：升级react-scripts到最新稳定版
新版react-scripts已经原生适配这类ESM语法解析，执行升级命令：
```
npm install react-scripts@latest --save
```
升级完成后直接重启开发服务器即可。注意如果你的项目是3年以上的老CRA项目，升级react-scripts可能带来其他依赖兼容冲突，操作前建议备份代码。
方案3：自定义构建配置转译对应依赖（适合不方便升降级版本的场景）
如果你不能改动htmlparser2和react-scripts的版本，可以通过@craco/craco修改CRA默认构建规则，让babel转译htmlparser2及关联依赖：
1. 安装craco依赖：npm install @craco/craco --save-dev
2. 项目根目录新建craco.config.js配置文件，添加规则将htmlparser2、domutils等相关包加入babel转译范围
3. 将package.json里scripts字段下的start、build、test命令中的react-scripts替换为craco，再执行启动命令。