SSR 兼容性 ​

本库组件可在服务端渲染（Nuxt / VitePress / 自研 SSR）环境下安全输出首屏 HTML。本页说明兼容边界与使用注意。

验证方式 ​

本库文档站的所有组件演示页都在 CI 中以 SSR 模式构建（VitePress 生产构建对每个页面做服务端渲染）——即每个组件至少一个真实实例在每次发版前都经过 SSR 渲染验证，这是随版本持续回归的常设检查，而非一次性声明。

组件层约定 ​

• 浏览器 API 时机：window / document 触达只发生在 onMounted 之后、事件回调或命令式调用中；模板与 setup 的同步路径不依赖浏览器对象，服务端可完整渲染。
• 持久化降级：主题 / 密度等持久化能力（saveThemeConfig / loadThemeConfig 等）对无 localStorage 环境静默跳过，不抛错、不阻塞渲染。
• 弹层即客户端：Dialog / Select 下拉 / DatePicker 面板 / Tooltip 等 19 类弹层均走 Teleport，服务端只输出触发器部分，弹层内容在客户端挂载后出现——属 Vue 官方语义，非兼容性缺陷。
• 测量类组件：VirtualList / Splitter / Affix 等依赖视口或容器测量的组件，首帧在客户端完成测量校准；建议为其指定确定性的高度 / 容器尺寸，避免水合前后的布局跳动。
• 命令式 API：EbMessage / EbNotify / EbMsgbox / EbLoading 只能在客户端交互中调用（服务端无挂载点），SSR 路由加载器等纯服务端上下文里不要调用。

图表（EbChart） ​

Canvas 绘制在客户端完成，服务端输出图表容器。建议在容器上固定宽度 / 高度（或宽高比），首屏视觉稳定且图表挂载后无需重排。

排查建议 ​

若自建 SSR 环境遇到 window is not defined 类报错，先确认调用点是否位于上述「客户端侧」约定内（事件回调、onMounted、命令式调用）；业务代码里的第三方插件报错与本库无关，可用动态导入将其限制在客户端。