渲染策略详解

ssr:only（默认）

服务端预渲染，无客户端 JavaScript。适用于纯静态展示内容。

特点：

• 构建时完成渲染，生成静态 HTML
• 对 FCP、LCP、SEO 最有利
• 可使用 Node.js API（如 node:fs）读取本地数据
• 默认启用 spa:sync-render

使用场景： 数据表格、文章摘要、静态图表

<DataTable :data="tableData" />

client:only

仅客户端渲染，无 SSR。组件在浏览器中从头渲染。

特点：

• 初始 HTML 为空容器
• 需要等待 JS 加载后才可见
• 不利于 SEO
• 适合依赖 window/document 的组件

使用场景： 浏览器存储交互、WebGL、Canvas 绑定

<BrowserOnlyWidget client:only />

client:load

SSR + 立即 hydration。页面加载后立即激活交互。

特点：

• 构建时预渲染 HTML
• 页面加载后立即执行 hydration
• 平衡 SEO 与交互性
• 增加首屏 JS 负载

使用场景： 首屏关键交互组件、搜索框、导航菜单

<SearchBox client:load placeholder="搜索..." />

client:visible

SSR + 懒加载 hydration。组件进入视口时才激活。

特点：

• 构建时预渲染 HTML
• 使用 IntersectionObserver 检测可见性
• 减少首屏 JS 负载
• 适合折叠线下方内容

使用场景： 评论区、页脚交互、长页面底部组件

<CommentSection client:visible postId={123} />

spa:sync-render 辅助指令

解决 SPA 路由切换时 React 组件的布局闪烁问题（CLS）。

工作原理：

• 将预渲染输出集成到 Vue 客户端脚本
• 路由切换时同步渲染，避免内容跳动

代价：

• 增加客户端脚本体积
• 组件 CSS 成为渲染阻塞资源

使用建议：

• ssr:only 默认启用，可用 spa:sr:disable 关闭
• client:load/client:visible 默认关闭，需显式添加 spa:sr
• client:only 不支持此指令

<!-- 关键布局组件 -->
<HeroSection client:load spa:sync-render />

<!-- 非关键组件，关闭同步渲染 -->
<Analytics ssr:only spa:sr:disable />

性能权衡总结

策略	首屏速度	JS 体积	SEO	交互延迟
ssr:only	最快	最小	好	N/A
client:only	慢	中等	差	最小
client:load	快	较大	好	小
client:visible	快	较小	好	中等