顶层 await 不能直接控制页面渲染时机，因为它仅阻塞模块执行，不阻塞 HTML 解析、DOM 构建及非模块脚本的渲染；浏览器仍会照常绘制已就绪的 DOM 片段，导致内容提前暴露或闪烁。
顶层 await 在 module script 中为什么不能直接控制页面渲染时机
顶层 await 确实能让模块执行暂停，直到 Promise 解析完成，但它**不阻塞 HTML 解析和 DOM 构建**，也不影响 <script type="module"></script> 之外的元素（比如普通 HTML 标签、CSS、非模块脚本）的加载与渲染。浏览器仍会照常解析并绘制已就绪的 DOM 片段——这意味着你可能看到“空白页闪一下”或“未填充内容先出现”，即使模块里 await fetch() 还没结束。
如何让页面真正等数据就绪再显示（实用三步）
核心思路：不让关键 DOM 提前暴露，用 CSS 隐藏 + JS 控制显隐，配合模块加载完成信号。不是靠顶层 await “拦住浏览器”，而是主动管理可见性。
- 在
或上加一个初始 class，比如loading，并用 CSS 隐藏所有主内容区域：body.loading main, body.loading .app { opacity: 0; pointer-events: none; } - 模块脚本中用顶层
await加载数据（如await fetch('/api/user').then(r => r.json())），处理完后移除 loading 状态：document.body.classList.remove('loading'); - 确保该模块是页面中**唯一且最先执行的模块脚本**，且没有其他非模块脚本提前操作 DOM；否则竞态会导致状态混乱。
常见翻车点：CSS 与 JS 的协作陷阱
很多人以为加个 display: none 就够了，但实际容易出问题：
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
-
display: none会让元素脱离文档流，可能影响布局计算或导致 FOUC（Flash of Unstyled Content）更明显；推荐用opacity: 0; visibility: hidden;或pointer-events: none配合过渡动画 - 如果模块脚本被标记为
defer或放在底部，它可能晚于某些内联脚本执行，造成classList.remove被跳过或报错Cannot read property 'classList' of null - 服务端渲染（SSR）或静态生成场景下，顶层 await 模块不会在服务端运行，所以这个方案只适用于纯客户端渲染（CSR）或 hydration 前的等待，不能替代 SSR 数据预取
替代方案对比：什么时候不该用顶层 await
如果你需要 SEO 友好、首屏可交互时间敏感，或者数据依赖复杂（如嵌套 fetch、需 fallback UI），顶层 await + CSS 隐藏就显得单薄：
立即学习“前端免费学习笔记（深入）”；
- 想支持服务端注入数据？改用
<script id="__INIT_DATA" type="application/json"></script>预置 JSON，JS 直接读取，无需 await - 需要错误降级（比如 API 失败时显示默认内容）？顶层 await 会直接 reject 模块，导致整个脚本失败，应改用
try/catch包裹 fetch，并显式处理 error 状态 - 多个模块都 await 不同资源？模块加载顺序不可控，容易出现部分数据到了、部分还没到的情况；建议统一收口到一个入口模块做协调
顶层 await 是个干净的语法糖，但它不改变浏览器渲染流水线的本质节奏——真要控渲染，得靠你亲手管好 DOM 的 visibility 和 JS 的执行时序。
