): string;\n```\n\n**示例：**\n\n```ts\nimport { serializeAttributes } from '@vitarx/runtime-ssr'\n\nconst attrs = serializeAttributes({\n id: 'test',\n class: 'foo bar',\n disabled: true\n})\nconsole.log(attrs) // ' id=\"test\" class=\"foo bar\" disabled'\n```\n\n## 高级用法\n\n### 异步组件 SSR\n\n#### 异步懒加载支持\n\nVitarx SSR 自动支持异步组件，在服务端渲染时会等待异步组件加载完成。\n\n```tsx\nimport { lazy } from 'vitarx'\n\nconst AsyncComponent = lazy(() => import('./HeavyComponent'))\n\nfunction App() {\n return (\n \n )\n}\n\n// 服务端渲染会等待 AsyncComponent 加载完成\nconst html = await renderToString(createSSRApp(App))\n```\n\n#### 异步数据获取\n\n在 `onInit` 生命周期中获取异步数据：\n\n```tsx\nimport { ref, onInit } from 'vitarx'\nfunction UserProfile() {\n const user = ref(null)\n onInit(async ()=>{\n // 服务端渲染时会等待这个 Promise\n const response = await fetch('/api/user')\n user.value = await response.json()\n })\n return {user.value ? user.value.name : 'Loading...'}
\n}\n```\n\n#### 错误处理\n\n在渲染过程中捕获错误：\n\n```tsx\ntry {\n const html = await renderToString(app, context)\n res.send(html)\n} catch (error) {\n console.error('SSR 渲染失败:', error)\n // 降级为客户端渲染\n res.send(`\n \n \n \n \n \n \n \n `)\n}\n```\n\n### 指令支持\n\n#### v-show 指令\n\n`v-show` 指令会在 SSR 时转换为 inline style：\n\n```tsx\nimport { withDirectives } from '@vitarx/runtime-core'\n\nfunction App() {\n return Content
\n}\n\n// 渲染结果：Content
\n```\n\n#### v-html 指令\n\n`v-html` 指令允许插入原始 HTML：\n\n```tsx\nfunction App() {\n const rawHTML = 'Important'\n return \n}\n\n// 渲染结果：Important
\n```\n\n> **警告：** 使用 `v-html` 时必须确保内容来源可信，否则可能导致 XSS 攻击。\n\n### 状态管理\n\n#### 服务端状态注入\n\n在服务端渲染时写入状态：\n\n```tsx\nimport { useSSRContext } from '@vitarx/runtime-ssr'\n\nfunction App() {\n const ctx = useSSRContext()\n \n if (ctx) {\n ctx.initialData = {\n user: { id: 1, name: 'John' },\n theme: 'dark'\n }\n }\n \n return App Content
\n}\n\n// 服务端\nconst context = {}\nconst html = await renderToString(app, context)\n\n// 将 context 注入到 HTML\nconst fullHTML = `\n \n \n \n ${html}
\n \n \n \n \n`\n```\n\n#### 客户端状态恢复\n\n客户端水合时自动恢复状态：\n\n```tsx\nimport { useSSRContext } from '@vitarx/runtime-ssr'\n\nfunction App() {\n const ctx = useSSRContext()\n \n // 客户端可以访问服务端注入的状态\n const initialData = ctx?.initialData || {}\n \n return User: {initialData.user?.name}
\n}\n```\n\n### 性能优化\n\n#### 流式渲染优化\n\n对于大型页面，使用流式渲染减少 TTFB：\n\n```tsx\nimport { renderToNodeStream } from '@vitarx/runtime-ssr'\n\napp.get('*', async (req, res) => {\n res.writeHead(200, { 'Content-Type': 'text/html' })\n \n // 立即发送 HTML 头部\n res.write('')\n \n const stream = await renderToNodeStream(createSSRApp(App))\n stream.pipe(res, { end: false })\n \n stream.on('end', () => {\n res.end('
')\n })\n})\n```\n\n#### 水合性能优化\n\n分批水合大型应用：\n\n```tsx\n// 先水合关键内容\nconst app = createSSRApp(App)\nawait hydrate(app, '#app')\n\n// 然后延迟加载非关键内容\nsetTimeout(() => {\n // 加载其他组件\n}, 0)\n```\n\n#### 缓存策略\n\n缓存 SSR 渲染结果：\n\n```tsx\nconst cache = new Map()\n\napp.get('*', async (req, res) => {\n const url = req.url\n \n // 检查缓存\n if (cache.has(url)) {\n return res.send(cache.get(url))\n }\n \n const html = await renderToString(createSSRApp(App))\n cache.set(url, html)\n \n res.send(html)\n})\n```\n\n## 最佳实践\n\n### 服务端渲染最佳实践\n\n#### 避免使用浏览器 API\n\n在服务端渲染时，避免使用浏览器特有的 API：\n\n```jsx\nfunction MyComponent() {\n // ✗ 错误：服务端没有 window 对象\n // const width = window.innerWidth\n \n // ✓ 正确：检查环境\n const width = typeof window !== 'undefined' ? window.innerWidth : 0\n \n return Width: {width}
\n}\n```\n\n#### 生命周期限制\n\n服务端渲柕仅执行部分生命周期钩子：\n\n| 钩子 | 服务端 | 客户端 |\n|-----------------|-----|-----|\n| `onInit` | ✓ | ✓ |\n| `onBeforeMount` | ✗ | ✓ |\n| `onMounted` | ✗ | ✓ |\n| `onShow` | ✗ | ✓ |\n| `onHide` | ✗ | ✓ |\n| `onDispose` | ✓ | ✓ |\n\n```tsx\nimport { onInit, onMounted, ref } from 'vitarx'\n\nfunction MyComponent() {\n const data = ref()\n onInit(async ()=> {\n // 服务端和客户端都会执行\n console.log('Component init')\n data.value = await fetchData()\n })\n \n onMounted(()=>{\n // 仅客户端执行\n console.log('Component mounted')\n this.startTimer()\n })\n\n return {data}
\n}\n```\n\n### 水合一致性保证\n\n#### 确保渲染结果一致\n\n服务端和客户端必须渲染相同的结果：\n\n```tsx\n// ✗ 错误：不一致\nfunction App() {\n const isServer = typeof window === 'undefined'\n return {isServer ? 'Server' : 'Client'}
\n}\n\n// ✓ 正确：一致性\nfunction App() {\n return Content
\n}\n```\n\n#### 处理随机数和时间戳\n\n避免在渲染过程中使用随机数或当前时间：\n\n```tsx\n// ✗ 错误：每次渲染结果不同\nfunction App() {\n return Random: {Math.random()}
\n}\n\n// ✓ 正确：使用上下文传递\nfunction App() {\n const ctx = useSSRContext()\n const randomValue = ctx?.randomValue || 0\n return Random: {randomValue}
\n}\n```\n\n### SEO 优化\n\n#### Meta 标签处理\n\n动态设置 meta 标签：\n\n```tsx\nimport { useSSRContext } from '@vitarx/runtime-ssr'\n\nfunction App() {\n const ctx = useSSRContext()\n \n if (ctx) {\n ctx.title = 'My Page Title'\n ctx.meta = [\n { name: 'description', content: 'Page description' },\n { property: 'og:title', content: 'My Page Title' }\n ]\n }\n \n return Content
\n}\n\n// 服务端\nconst context = {}\nconst html = await renderToString(app, context)\n\nconst fullHTML = `\n \n \n \n ${context.title}\n ${context.meta?.map(m => \n ` `${k}=\"${v}\"`).join(' ')} />`\n ).join('\\n')}\n \n \n ${html}
\n \n \n`\n```\n\n### 错误处理策略\n\n#### 水合失败降级\n\n`hydrate()` 会自动处理水合失败，如果水合失败后，会清空容器内容，并回退到正常渲染挂载模式。\n\n## 注意事项\n\n### 生命周期钩子在 SSR 中的行为\n\n- `onInit` 和 `onDispose` 在服务端和客户端都会执行\n- `onBeforeMounte`、`onMounted`、`onShow`、`onHide` 仅在客户端执行\n\n### 浏览器 API 限制\n\n服务端环境不支持以下 API：\n\n- `window`、`document`、`navigator`\n- `localStorage`、`sessionStorage`\n- `setTimeout`、`setInterval`（在 `onMounted` 中使用）\n- DOM 操作 API\n\n### 内存泄漏预防\n\n- 在 `onMounted` 中编写仅运行在客户端的逻辑\n- 避免全局状态污染\n\n## API 索引\n\n| API | 类型 | 描述 |\n|--------------------------|----|----------------------------------|\n| `createSSRApp` | 函数 | 创建 SSR 应用实例 |\n| `SSRApp` | 类 | SSR 应用类 |\n| `renderToString` | 函数 | 渲染为 HTML 字符串（同步） |\n| `renderToStream` | 函数 | 渲染为流（异步） |\n| `renderToReadableStream` | 函数 | 创建 Web ReadableStream |\n| `renderToNodeStream` | 函数 | 创建 Node.js Readable 流 |\n| `hydrate` | 函数 | 客户端水合 |\n| `useSSRContext` | 函数 | 获取 SSR 上下文 useRenderContext 效果一致 |\n| `isSSR` | 函数 | 判断是否在 SSR 环境 |\n| `isHydrating` | 函数 | 判断是否在水合阶段 |\n| `escapeHTML` | 函数 | 转义 HTML 特殊字符 |\n| `serializeAttributes` | 函数 | 序列化属性对象 |\n| `SSRContext` | 类型 | SSR 上下文类型定义 |\n\n## 许可证\n\n[MIT](LICENSE)\n","readmeFilename":""}