在Next.js项目中使用顶层Await可以简化异步逻辑编写，但默认Webpack配置不支持该特性，需要手动调整配置才能生效。顶层Await允许在模块顶层直接使用await，无需嵌套在async函数内，适合处理模块加载时的异步初始化场景。
顶层Await的基础说明
顶层Await是ES2022正式纳入标准的JavaScript特性，它解决了以往只能在async函数内部使用await的限制。在支持该特性的环境下，开发者可以在模块的顶层直接编写await语句，比如直接等待异步配置加载、远程模块获取等操作，代码结构会更清晰简洁。
不过该特性属于较新的语法，需要构建工具正确转译或支持才能运行，Next.js内置的Webpack配置默认没有开启对应的处理规则，直接使用时会出现编译错误，提示语法不支持。
Next.js的Webpack配置修改方法
Next.js允许通过项目根目录下的next.config.js文件自定义Webpack配置，我们只需要在该文件中添加对顶层Await的支持规则即可。具体步骤如下：
1. 基础配置修改
打开项目根目录的next.config.js文件，如果没有该文件可以手动创建，添加以下配置代码：
/** @type {import('next').NextConfig} */
const nextConfig = {
webpack: (config, { isServer }) => {
// 修改babel配置支持顶层Await
config.module.rules.forEach(rule => {
if (rule.test && rule.test.toString().includes('jsx|tsx')) {
if (rule.use && Array.isArray(rule.use)) {
rule.use.forEach(useItem => {
if (useItem.loader && useItem.loader.includes('babel-loader')) {
// 添加顶层Await对应的babel插件支持
if (!useItem.options) {
useItem.options = {};
}
if (!useItem.options.plugins) {
useItem.options.plugins = [];
}
// 引入支持顶层Await的babel插件
useItem.options.plugins.push('@babel/plugin-syntax-top-level-await');
}
});
}
}
});
return config;
},
}
module.exports = nextConfig2. 安装依赖插件
上述配置用到了@babel/plugin-syntax-top-level-await插件，需要先通过包管理工具安装该依赖：
- 使用npm的项目执行：
npm install @babel/plugin-syntax-top-level-await --save-dev - 使用yarn的项目执行：
yarn add @babel/plugin-syntax-top-level-await --dev
配置验证与使用示例
完成配置和依赖安装后，重启Next.js开发服务，就可以在项目中使用顶层Await了。以下是一个简单的使用示例：
// 模块顶层直接使用await
const config = await fetch('https://ipipp.com/api/config')
.then(res => res.json())
.catch(err => {
console.error('配置加载失败', err);
return {};
});
console.log('加载到的配置', config);
export default function HomePage() {
return (
<div>
<h1>顶层Await测试页面</h1>
<p>配置已加载完成</p>
</div>
);
}常见问题排查
如果配置后仍然出现语法错误，可以按照以下思路排查：
- 检查
@babel/plugin-syntax-top-level-await是否正确安装，依赖版本是否兼容当前Next.js版本 - 确认
next.config.js中的Webpack规则修改是否正确命中了babel-loader，部分自定义配置可能会修改默认的规则匹配逻辑 - 如果是服务端组件使用顶层Await，还需要确认Node.js版本是否支持该特性，Node.js 16.12及以上版本原生支持顶层Await，低版本需要额外转译
注意：顶层Await只能在ES模块中使用，如果项目中使用的是CommonJS模块规范，需要先调整模块类型，或者在支持的模块文件中使用。
Next.jsWebpack顶层AwaitJavaScript前端配置修改时间：2026-06-03 01:50:51