🤖 qwen-3-coder-480b | 0304357c-30a5-4067-b405-a9f9f7a4157e

VitePress 使用 defineClientComponent 防坑指南

在开发基于 VitePress 的项目时，如果你需要使用那些依赖浏览器 API（如 window, localStorage）的组件，那么你必须通过 defineClientComponent 来包装它，以便保证服务端渲染（SSR）能够正常运行。

然而，不少开发者在使用 defineClientComponent 时会遇到插槽（slot）不生效的问题，比如传递的默认插槽或具名插槽内容为空。本文将详述该问题的原因及正确的解决方式。

---

一、defineClientComponent 是什么？

defineClientComponent 是 VitePress 提供的辅助函数，用于处理不能在 SSR 阶段运行的组件。

import { defineClientComponent } from 'vitepress'
const ClientComponent = defineClientComponent(() => import('./YourComponent.vue'))

它能够确保组件在客户端挂载（mounted）之后才被导入和渲染，避免了 Node.js 环境中的报错。

---

二、为什么插槽无效？

2.1 SSR 渲染阶段不加载组件

VitePress 在生成静态页面时，会先执行服务端渲染（SSR），随后客户端挂载组件。而使用 defineClientComponent 的组件在 SSR 阶段不会被真正渲染。

因此，如果你按如下方式使用组件：

<ClientComponent>
  插槽内容
</ClientComponent>

服务端只会生成空标签，插槽内容在初始 HTML 中不会出现，浏览器视图初始加载时看起来就是“空的”，这就会形成误导。

2.2 Hydration 不匹配问题

在某些情况下，如果 SSR 和客户端渲染结果不匹配（DOM 结构差异），Vue 会抛出 Hydration Mismatch 错误。为了防止这类错误，VitePress 官方暂时禁用了插槽的常规使用方式。

---

三、如何正确传递插槽？

插槽必须通过 defineClientComponent 的第二个参数来传递！

3.1 基本用法（传递插槽内容）

<script setup>
import { h } from 'vue'
import { defineClientComponent } from 'vitepress'

const ClientCard = defineClientComponent(
  () => import('./Card.vue'),
  [
    {}, // props
    {
      // slots
      default: () => h('p', '这是默认插槽内容'),
      title: () => h('h3', '这是具名插槽 title')
    }
  ]
)
</script>

<template>
  <ClientCard />
</template>

在这个例子中：

• 使用了 Vue 的 h() 函数创建虚拟 DOM 结构。

• 插槽内容必须是一个返回 VNode 的函数，而不是直接写的标签内容。

3.2 高级用法（传递复杂内容）

如果插槽内容涉及更复杂的结构（比如包含子组件、动态内容），可以通过嵌套 h() 函数实现：

const ClientCard = defineClientComponent(
  () => import('./Card.vue'),
  [
    {}, // props
    {
      default: () => h('div', [
        h('p', '第一段文字'),
        h('span', { style: 'color:red' }, '红色文字')
      ])
    }
  ]
)

3.3 带有 Props 的用法

const ClientCard = defineClientComponent(
  () => import('./Card.vue'),
  [
    { title: '卡片标题' }, // props
    {
      default: () => h('p', '这是插槽内容')
    }
  ]
)

---

四、常见错误示例

❌ 错误示例，插槽内容不会被渲染：

<ClientCard>这是默认插槽的内容</ClientCard>

✅ 正确示例，使用参数方式传入插槽内容：

const ClientCard = defineClientComponent(
  () => import('./Card.vue'),
  [
    {},
    {
      default: () => h('div', '这是默认插槽的内容')
    }
  ]
)

---

五、总结

使用方式	是否生效	说明
<ClientComp>插槽内容</ClientComp>	❌ 不生效	SSR 阶段未渲染，导致内容丢失
defineClientComponent(() => import(...), [props, { default: () => h(...) }])	✅ 生效	正确传递插槽内容，保证客户端渲染正常
直接 import 组件	❌ SSR 报错	如果组件依赖浏览器 API，会出错