React配置craco开启topLevelAwait仍报错如何解决

安全阿岳

2026-9-2

排查解决步骤

按以下顺序逐一校验修复：

校验package.json脚本配置
必须将原有react-scripts相关命令全部替换为craco指令，否则craco.config.js的配置完全不会生效，正确配置如下：
```
{
  "scripts": {
    "start": "craco start",
    "build": "craco build",
    "test": "craco test"
  }
}
```
修改后必须终止本地开发进程，重新执行启动命令，热更新不会加载新的构建配置。
调整babel配置
babel默认会将ES模块转为CommonJS规范，导致webpack无法识别顶层await语法。在项目根目录新增或修改babel.config.json，关闭模块转译逻辑：
```
{
  "presets": [
    [
      "react-app",
      {
        "modules": false
      }
    ]
  ]
}
```
校验版本匹配关系
仅@craco/craco@7.x版本适配react-scripts@5.x（内置webpack5，原生支持顶层await实验特性），低版本craco对接webpack4无该能力。执行命令查看当前依赖版本：
```
yarn list @craco/craco react-scripts
```
版本不匹配时执行以下命令重装适配版本：
```
yarn remove @craco/craco && yarn add -D @craco/craco@7
```
兜底配置方案
对象形式的webpack配置合并可能存在失效问题，将craco.config.js改为函数形式直接修改最终构建配置：
```
module.exports = {
  webpack: {
    configure: (webpackConfig) => {
      webpackConfig.experiments = {
        ...webpackConfig.experiments,
        topLevelAwait: true
      }
      return webpackConfig
    }
  }
}
```
修改后删除node_modules/.cache目录清理构建缓存，重启服务即可生效。