top-level await仅在中有效，需es2022+环境支持；内联模块合法但生产慎用，非模块脚本直接报错；必须确保模块加载链完整且无循环依赖。
Top-Level Await 在 HTML 中根本不能直接使用
浏览器的 <script type="module"></script> 支持 Top-Level Await，但前提是脚本必须是模块（type="module"），且加载方式符合 ES 模块规范——不能通过内联 script 直接写 await，也不能在非模块 script 中启用。
常见错误现象：Uncaught SyntaxError: await is only valid in async functions and the top level bodies of modules，说明当前 script 不被识别为模块上下文。
- 必须显式声明
type="module"，哪怕脚本内容只有一行await Promise.resolve() - 内联模块（
<script type="module">await fetch('/api');</script>）是合法的，但多数构建工具或服务端模板会因转义/注入策略禁用，生产环境慎用 - 动态
import()是替代方案，但它返回 Promise，需配合.then()或外层包装函数，不是真正的顶层 await
如何正确启用 Top-Level Await：从 HTML 到模块加载链
关键不在 HTML 标签本身，而在于整个加载链是否构成有效的模块图。浏览器只对明确标记为模块的 script 启用 TLA。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
-
<script type="module" src="main.js"></script>✅ ——main.js内可直接写const data = await fetch('/conf.json').then(r => r.json()); -
<script type="module">console.log(await Promise.resolve('ok'));</script>✅ —— 内联模块允许，但无法访问外部作用域变量（如全局window.config需提前定义） -
<script src="main.js"></script>❌ —— 即使main.js内容含await，也会报语法错误，因为不是模块上下文 - 如果入口模块通过
import加载其他模块，TLA 仅在首个模块（即 HTML 中直接引用的那个）顶层生效；被 import 的模块内部仍可使用 TLA，但它们属于模块图一部分，不是“HTML 中启用”的源头
常见陷阱：跨域、CORS 和 JSON 解析失败导致 await 静默卡住
TLA 让代码看起来同步，但错误处理容易被忽略——没有 try/catch 包裹时，模块加载会直接失败，表现为白屏或控制台报错后脚本终止。
- fetch 默认不带
credentials，若 API 需 Cookie，必须显式加{ credentials: 'include' }，否则 401 且await拿不到响应 - JSON 接口返回非 2xx 状态码（如 404）时，
fetch()依然 resolve，但.json()会 reject；应写成const res = await fetch('/data'); if (!res.ok) throw new Error(res.status); const data = await res.json(); - 模块加载阶段无法使用
window.onload或DOMContentLoaded监听 TLA 完成，因为模块执行早于这些事件；如需 DOM 就绪后再 await，应在 TLA 后加await new Promise(r => document.addEventListener('DOMContentLoaded', r));
构建工具和打包器对 Top-Level Await 的兼容性差异
Vite 默认支持 TLA，Webpack 5+ 需配置 experiments.topLevelAwait: true，而旧版打包器（如 Webpack 4、Rollup 默认配置）会直接报错或降级为语法错误。
- ESBuild 不支持输出含 TLA 的代码（v0.19 仍报错），必须用
dynamicImport替代 - 若目标浏览器需兼容 Safari ≤15.4 或 Firefox ≤100，TLA 不可用（查 caniuse），此时必须将顶层逻辑封装进
async function init() { ... }并立即调用 - Node.js 里
type="module"的 .mjs 文件支持 TLA，但和浏览器 HTML 场景无关——别混淆服务端模块与前端 script 加载机制
TLA 看似简化了异步初始化，但它的执行时机紧贴模块解析，任何阻塞都会拖慢整个模块图加载；真正难处理的不是语法，而是错误传播路径变短、调试线索变少——比如一个 await 失败，整页 JS 可能就不再执行。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
