同构渲染需确保服务端与客户端DOM完全一致，否则将触发重挂载；须规避非确定性操作、统一数据预取时机、实施部分水合，并隔离不可水合区域以避免白屏闪动与性能倒退。

同构渲染不是加个 renderToString 就能跑通的架构选择，它本质是让同一套组件逻辑在服务端和浏览器两端都能执行并产出一致 DOM。不解决数据流同步、水合错位、资源加载时序这三类问题，SSR 反而会让首屏更慢、更不可靠。

如何保证服务端与客户端渲染结果完全一致

这是同构最基础也最容易翻车的一环。只要服务端生成的 HTML 和客户端首次水合时生成的 DOM 存在差异，React/Vue 就会丢弃服务端 HTML、重新挂载，等于白做 SSR。

• 避免在组件 render 或 setup 中读取 window、document、localStorage 等仅客户端存在的 API；服务端没有这些对象，会报错或返回 undefined，导致 DOM 不匹配
• 时间/随机数等非确定性操作必须收口：比如用 Date.now() 生成唯一 ID，服务端和客户端值不同，DOM key 就对不上；应统一用服务端传入的 context.timestamp 或请求时生成的稳定 seed
• 样式注入顺序要一致：CSS-in-JS 库（如 Emotion、Styled Components）必须启用 SSR 支持，并在服务端调用 extractCritical 或 collectStyles，把关键 CSS 提前注入 HTML 模板，否则客户端样式补丁会触发重排

数据预取必须与组件生命周期对齐

不能只在路由层 fetch 数据，否则组件内部的异步逻辑（比如 asyncData、serverPrefetch、getServerSideProps）可能被跳过，导致服务端渲染出空内容，客户端水合后才补数据——又回到“白屏→闪动”老路。

PigX UI 前端开发

PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。

下载

• Vue 场景下，确保 serverPrefetch 钩子被框架实际调用（检查是否在 export default 对象中定义，且组件被 createBundleRenderer 正确识别）
• React 场景下，若用 getServerSideProps，注意它只对页面组件生效；嵌套子组件的数据需通过 props 逐层透传，或改用支持组件级数据获取的方案（如 React Query 的 dehydrate/hyde）
• 避免在服务端重复请求：比如用户已带 token，服务端直接用该上下文调用 API；不要在客户端再发一遍相同请求，除非明确需要强刷新

水合过程必须可控，不能全量强制

默认水合是“全量接管”，但首屏里很多区域根本不需要交互（比如静态 banner、版权信息），强行水合只会拖慢 TTI。

立即学习“前端免费学习笔记（深入）”；

• 用 suppressHydrationWarning={true}（React）或 v-cloak + 服务端注释标记（Vue）隔离不可水合区域，让这部分 DOM 完全静态化
• 对可交互模块做“部分水合”：比如只对 <ProductList> 组件启用 hydration，其余用 v-html 或 dangerouslySetInnerHTML 渲染纯 HTML 字符串
• 警惕第三方脚本干扰：广告、埋点 SDK 如果在水合前就执行，可能修改 DOM 结构，导致水合失败；应统一用 useEffect/onMounted 延迟到客户端执行

真正难的不是让同构跑起来，而是让服务端渲染的 HTML 在浏览器里“活”得自然——不闪、不抖、不重绘、不重复请求。每个组件都得清楚自己在哪一端执行、依赖什么上下文、输出什么副作用。漏掉任意一个环节，性能优化就从提速变成添堵。