在Next.js项目里怎么启用Webpack的topLevelAwait功能

在Next.js项目开发中，顶层await（topLevelAwait）可以让开发者在ES模块的顶层作用域直接使用await语法，不需要把代码包裹在async函数里，能简化很多异步初始化的逻辑，比如直接加载远程配置、初始化第三方服务等。不过Next.js默认的Webpack配置没有开启这个特性，直接使用的话会触发构建错误。

配置前的前置说明

Next.js允许开发者通过next.config.js文件自定义Webpack配置，我们只需要在该文件中修改Webpack的experiments配置项，就能开启topLevelAwait支持。需要注意的是，开启该特性后，使用了顶层await的模块会被标记为异步模块，引入该模块的时候也需要配合动态导入或者顶层await语法，否则会出现执行顺序问题。

具体操作步骤

1. 找到或创建next.config.js文件

在项目根目录下，一般已经存在next.config.js文件，如果没有的话可以手动创建一个，这个是Next.js的默认配置文件。

2. 修改Webpack配置

在配置文件中添加webpack自定义函数，修改config.experiments属性，添加topLevelAwait: true。完整的配置代码如下：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 其他现有配置可以保留，不需要删除
  webpack: (config, { isServer }) => {
    // 开启Webpack的顶层await实验特性
    config.experiments = {
      ...config.experiments,
      topLevelAwait: true,
    };
    // 返回修改后的配置
    return config;
  },
};

module.exports = nextConfig;

3. 验证配置是否生效

可以在项目里新建一个测试模块，写入顶层await代码，然后启动项目看是否正常构建运行。测试代码示例如下：

// 测试顶层await的模块 test.mjs 或者 test.ts（需要确认项目模块配置支持ES模块）
const data = await fetch('https://ipipp.com/api/test').then(res => res.json());
console.log('顶层await加载的数据:', data);

export default data;

然后在页面组件中引入这个模块，如果项目正常启动没有报错，说明配置已经生效。

注意事项

• 使用了顶层await的模块会被Webpack处理为异步模块，如果你用静态导入的方式引入该模块，需要确保运行环境支持异步模块，或者改用动态导入import('./test.mjs').then(module => {})的方式。
• 如果项目同时使用了TypeScript，需要在tsconfig.json中把module设置为esnext，同时target设置为支持顶层await的版本，比如es2017及以上，否则TypeScript会报语法错误。
• 该特性属于Webpack的实验性功能，虽然目前稳定性已经比较高，但后续Next.js或者Webpack版本更新可能会有配置变动，建议更新依赖后重新验证配置是否生效。

常见问题排查

如果配置之后还是报错，可以先检查next.config.js的语法是否正确，有没有把其他现有配置误删。如果报错提示模块类型问题，可以确认项目里的相关文件是不是ES模块，或者把文件后缀改成.mjs再测试。如果是在服务端组件里使用，还需要确认Node.js版本是否支持顶层await，Node.js 14.8.0及以上版本已经支持该特性，一般Next.js项目的Node.js版本都满足要求。

Next.jsWebpacktopLevelAwaitnext.config.js修改时间：2026-06-03 01:50:05