React-Intl项目构建报top-level-await未启用错误咨询解决方案

报错核心原因 #

React-Intl 及其底层依赖 @formatjs 系列包的ESM产物默认使用顶层await语法做语言包懒加载，当前构建链路存在两个触发点：

• Babel 转译阶段未识别顶层await语法，输出的产物仍保留该语法
• Webpack 未开启对应语法解析支持，且默认配置下babel-loader会跳过node_modules内依赖的转译，导致带顶层await的文件直接进入Webpack解析环节触发报错

可行解决方案（按优先级排序） #

方案1：调整Babel转译范围+语法支持（兼容所有Webpack版本，优先选择） #

1. 安装顶层await语法支持插件

npm i -D @babel/plugin-syntax-top-level-await

2. 修改Babel配置文件（babel.config.js/.babelrc），在plugins数组中加入插件：

module.exports = {
  presets: [
    ["@babel/preset-env", { targets: "> 0.25%, not dead" }],
    "@babel/preset-react"
  ],
  plugins: ["@babel/plugin-syntax-top-level-await"]
}

3. 修改babel-loader规则，将react-intl、@formatjs相关依赖纳入转译白名单，不要被exclude规则跳过：

// webpack.config.js 中module.rules配置
{
  test: /\.(js|mjs|jsx)$/,
  // 原exclude: /node_modules/ 修改为下面的规则，放行两个相关依赖
  exclude: /node_modules\/(?!(react-intl|@formatjs)\/).*/,
  loader: require.resolve('babel-loader')
}

方案2：Webpack 5 环境开启顶层await实验特性（方案1无效时使用） #

如果项目使用Webpack 5版本，可直接在配置中开启对应特性支持，修改webpack.config.js：

module.exports = {
  // 其余原有配置保持不变
  experiments: {
    topLevelAwait: true
  }
}

注意：Webpack 4及更低版本不支持该实验特性，不要在低版本Webpack中强行添加该配置。

方案3：调整语言包加载逻辑（兜底方案） #

如果上述配置修改后仍有报错，可移除代码中顶层await加载语言包、初始化intl实例的写法，改为组件内异步加载：

import { useState, useEffect } from 'react';
import { IntlProvider } from 'react-intl';

function AppWrapper({ children }) {
  const [localeConfig, setLocaleConfig] = useState(null);

  useEffect(() => {
    const initIntl = async () => {
      const lang = navigator.language.startsWith('zh') ? 'zh-CN' : 'en-US';
      const messages = await import(`./locales/${lang}.json`);
      setLocaleConfig({ locale: lang, messages: messages.default });
    };
    initIntl();
  }, []);

  if (!localeConfig) return <div>国际化资源加载中</div>;
  return (
    <IntlProvider {...localeConfig}>
      {children}
    </IntlProvider>
  );
}

排错提示：如果是使用Create React App创建且未eject的项目，不要直接修改node_modules内的webpack配置，通过craco/react-app-rewired注入上述规则即可。

内容的提问来源于stack exchange，提问作者Raunak Deep Srivastava