顶级await仅适用于es模块，需满足type="module"、环境支持es2022+、无循环依赖；否则报syntaxerror；浏览器仅对明确标记为module的script启用该特性。

可以直接在 ES 模块顶层用 await 加载配置，但必须满足三个硬性条件：脚本是模块（type="module"）、运行环境支持 ES2022+、加载链无循环依赖。否则会报 SyntaxError: await is only valid in async functions and the top level bodies of modules。

确保 HTML 正确启用模块上下文

浏览器只对明确标记为模块的 <script></script> 启用顶层 await。不能写成普通脚本，也不能靠构建工具“自动转换”：

• ✅ 正确写法：<script type="module" src="main.js"></script> —— main.js 中可直接写 await fetch(...)
• ❌ 错误写法：<script src="main.js"></script> —— 即使 main.js 内容含 await，也会语法报错
• ⚠️ 内联模块可行但慎用：<script type="module">const conf = await (await fetch('/conf.json')).json();</script> —— 合法，但无法访问全局变量，且多数模板引擎会过滤或转义，不建议生产环境使用

在模块文件中安全加载并导出配置

顶层 await 的核心价值是让导入者能“等结果再继续”，所以配置应尽早加载、明确导出。注意两点关键细节：

Pandas 配置文件报告生成器

使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。

下载

• fetch 返回的 response 需手动检查状态，.json() 在非 2xx 时会 reject，不能只依赖 await fetch().then(...)
• 导出语句必须在 await 之后，且不能被条件包裹（ES 模块要求导出静态可分析）

示例（config.js）：

const res = await fetch('/conf.json');
if (!res.ok) throw new Error(`Config load failed: ${res.status}`);
const config = await res.json();

export const API_BASE = config.apiBase;
export const FEATURE_FLAGS = config.features;
export default config;

避免常见阻塞和错误陷阱

顶层 await 会让整个模块变成异步依赖，所有 import 它的模块都会被挂起，因此要控制粒度和健壮性：

• 不要在顶层 await 耗时过长的操作（如未加 timeout 的 fetch），否则拖慢整个应用启动
• 若需带认证凭据（如 Cookie），必须显式传 { credentials: 'include' }，否则可能静默返回 401
• 严禁循环依赖：比如 A.js 顶层 await 加载配置并 import B.js，而 B.js 又 import A.js —— 会导致模块图死锁
• 不推荐用 IIFE 模拟顶层 await（如 (async () => { ... })()），因为导出值会变成 undefined，破坏模块求值时机