---
url: /guide/ssr.md
---
# 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、命令式调用）；业务代码里的第三方插件报错与本库无关，可用动态导入将其限制在客户端。