React npm run build报错Must use import to load ES Module如何解决

云上老周

2026-9-2

问题触发原因

这个报错是Node.js的CommonJS/ES Module模块加载规则冲突导致的，之前的排查操作没生效有几个明确的问题：

手动修改node_modules/@eslint/eslintrc/package.json的操作从根源上无效：Docker构建过程会重新执行依赖安装命令，拉取官方原版依赖包，本地对node_modules的修改要么不会被拷贝进镜像构建上下文，要么会被依赖安装步骤覆盖，自然不会对构建结果产生任何影响。另外提到删除的是"type": "model"配置，ESM模块的声明字段实际是"type": "module"，字段名写错就算本地修改也没改到点上。
本地通过nvm切换Node 16的操作不影响Docker构建结果：Docker容器和宿主机环境完全隔离，构建时用的是Dockerfile基础镜像内预装的Node版本，和本地nvm切换的版本没有任何关系，如果基础镜像用的Node版本低于14.18，本身就不支持部分ESM包的加载逻辑。
核心冲突来源：@eslint/eslintrc@2.x及以上版本是纯ESM包，而react-scripts 5.x内置的eslint加载逻辑是CommonJS规范，二者不兼容就会抛出Must use import to load ES Module的错误。如果.dockerignore没有排除本地node_modules目录，把本地不同版本的依赖拷进镜像，还会进一步加剧版本冲突。

可行解决方案

按优先级依次尝试即可：

修正Docker构建配置

首先在项目根目录的.dockerignore文件中添加以下规则，避免本地冗余文件干扰镜像构建：
```
node_modules
build
.git
.env.local
```

修正Dockerfile，确保基础镜像Node版本和本地能正常运行项目的版本一致（推荐用Node 16/18 LTS版本），并利用Docker缓存优化构建流程，参考配置：

# 选择和本地运行一致的LTS版本Node镜像
FROM node:16-alpine
WORKDIR /app
# 先拷贝依赖声明文件，充分利用docker层缓存
COPY package*.json ./
# 用npm ci安装锁文件对应版本的依赖，保证版本一致性
RUN npm ci
# 拷贝其余业务代码
COPY . .
# 执行构建命令
RUN npm run build

锁定冲突依赖的兼容版本
如果修正Docker配置后仍然报错，直接在项目中把冲突的eslint相关依赖锁到支持CommonJS的稳定版本，执行以下命令：
```
# 删除本地旧依赖和锁文件
rm -rf node_modules package-lock.json
# 安装兼容版本的冲突包
npm install @eslint/eslintrc@1.4.1 eslint@8.22.0 --save-dev
# 重新安装全量依赖
npm install
```
本地执行npm run build验证通过后，再重新执行docker build即可。
配置依赖版本强制覆盖规则
如果用的是npm 8.3以上版本，可以直接在package.json中添加overrides字段，强制全项目所有依赖引用的@eslint/eslintrc使用兼容版本，避免子依赖偷偷升级到不兼容的ESM版本：
```
{
  "name": "your-react-app",
  "version": "0.1.0",
  // ...其余原有配置
  "overrides": {
    "@eslint/eslintrc": "1.4.1"
  }
}
```
如果用yarn作为包管理工具，把overrides换成resolutions字段即可，配置完重新安装依赖再构建。

注意：任何场景下都不要直接修改node_modules目录下的文件，所有依赖调整都要通过package.json的版本声明、版本覆盖规则实现，否则本地重装依赖、CI构建、Docker构建时都会复现问题。

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