prerender_html 是私有封装函数，非标准api；落地预渲染需确保构建生成含真实数据的html且服务端直接返回它；next.js用generatestaticparams，vue cli用prerender-spa-plugin，puppeteer需禁js再启用并拦截xhr。
prerender_html 不是标准函数，别在代码里直接调用
看到 prerender_html 就去 npm install 或查 MDN？停手。它根本不是浏览器 API，也不是 Next.js/Nuxt 的导出函数，99% 是某团队私有构建脚本里封装的 puppeteer.launch() + page.goto() + page.content() 组合调用。搜不到文档很正常——因为没人公开它。
真正要落地预渲染，得盯住两件事：构建时是否生成了含真实数据的 HTML 字符串；服务端或 CDN 是否直接返回该 HTML（而非空壳 index.html）。其他全是包装。
- 如果项目用 Next.js 13+ App Router，删掉所有手写的
prerender_html调用，改用generateStaticParams+dynamic = "error" - 如果是 Vue CLI 或原生 Webpack 项目，
prerender-spa-plugin是更可靠的选择，它明确暴露PuppeteerRenderer配置项，而不是黑盒函数名 - 在 Express 中写中间件时，别挂
prerender_html到全局，直接复用puppeteer-core连接已运行的 Chrome 实例，避免每次请求都launch()导致内存爆炸
用 Puppeteer 做预渲染，必须关掉 JS 执行再开
很多人跑完 puppeteer 渲染发现 HTML 里还是空容器，或者数据没加载出来——问题往往出在 JS 执行时机。默认 page.goto() 会等 load 事件，但现代框架（Vue/React）的 hydration 和数据获取常依赖 DOMContentLoaded 后的异步逻辑，甚至靠 IntersectionObserver 触发懒加载。
解决办法不是等更久，而是控制 JS 行为：
- 用
page.emulateMediaType('print')之前先await page.setJavaScriptEnabled(false)，等 DOM 结构稳定后再setJavaScriptEnabled(true)并手动触发关键事件 - 对 Vue 应用，在
mounted()里发自定义事件（如document.dispatchEvent(new Event('render-ready'))），Puppeteer 用renderAfterEvent: 'render-ready'捕获 - 拦截并 abort 所有非必要 XHR（特别是打点、埋点、用户行为上报），否则 Puppeteer 会卡在 pending 状态，超时后吐出不完整 HTML
预渲染输出的 HTML 必须能被客户端正确 hydration
生成的静态 HTML 和后续客户端 JS 接管时的 DOM 结构不一致，React 会直接丢弃整个根节点重 render，Vue 会报 Hydration failed 警告——这比不预渲染还糟，因为白屏时间没减少，反而多了一次 DOM 重建。
关键检查点：
- 服务端生成的 HTML 中，所有动态内容（比如商品列表、用户昵称）必须真实存在，不能留占位符或 loading 态；否则客户端 JS 渲染时结构对不上
- 确保 CSS-in-JS（如 Emotion、Styled Components）在构建时提取了 SSR 样式，否则预渲染 HTML 缺少对应 class，样式丢失
- 避免在组件顶层用
window.location或localStorage，这些在 Puppeteer 环境里虽能运行，但和服务端 Node.js 环境行为不一致，容易导致 hydration 差异
别把 link rel="preload" 当成预渲染
<link rel="preload"> 只下载资源，不执行 JS，也不生成 DOM。它解决的是“JS 文件来得太晚”，而预渲染解决的是“HTML 里压根没内容”。两者目标不同，不能互相替代。
常见混淆操作：
- 在
里写<link rel="preload" href="/data.json">，以为这样就算预渲染——实际页面仍要等 JS fetch 完才开始 render - 用已废弃的
<link rel="prerender">（Chrome 自 2017 年起就不再支持），它既不触发渲染，也不影响首屏内容 - 给路由 JS 文件加一堆 preload，幻想“预加载下一页”——这只会挤占当前页带宽，Lighthouse 评分反而下降
真正的预渲染输出物，打开 DevTools → Network → 刷新页面，Response 中应直接看到带商品标题、描述、价格的真实 HTML 文本，而不是一个空 <div id="app"></div>。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
