Vitepress首页front matter引用自定义Vue组件无法渲染

1. 明确Hero文本的渲染限制 #

Vitepress默认的home布局中，hero.text字段仅支持纯文本或静态HTML，不会触发Vue组件的编译解析。这就是<TextRotator/>被当作普通HTML标签渲染成空节点，而…这类HTML实体能正常解析的核心原因。

2. 自定义Home布局替换默认布局 #

这是最直接的解决方案，步骤如下：

• 从Vitepress默认主题中复制Home.vue组件源码（路径通常为node_modules/vitepress/dist/client/theme-default/components/Home.vue）
• 在你的.vitepress/theme/components/目录下创建自定义Home.vue，修改hero.text的渲染逻辑：
  直接在模板中引入TextRotator并拼接目标文本，示例：

  <template>
    <!-- 保留原Home组件的其他结构 -->
    <div v-if="hero" class="VPHomeHero">
      <div class="container">
        <div class="hero-content">
          <h1 class="name">{{ hero.name }}</h1>
          <p class="text">
            A publishing platform marrying d3 and… <TextRotator/>
          </p>
          <!-- 保留原tagline、actions等部分 -->
        </div>
      </div>
    </div>
  </template>
  
  <script setup>
  import TextRotator from './TextRotator.vue'
  const props = defineProps({
    hero: Object,
    features: Array,
    footer: Object
  })
  </script>
  

• 在.vitepress/theme/index.ts中注册自定义布局，替换默认home布局：

  import { defineTheme } from 'vitepress'
  import Home from './components/Home.vue'
  
  export default defineTheme({
    layouts: {
      home: Home
    }
  })
  

3. 利用插槽注入自定义内容 #

如果不想完全重写Home组件，可通过插槽向hero区域注入带组件的内容：

• 自定义Home.vue，为hero文本区域添加插槽：

  <p class="text">
    <slot name="hero-text">{{ hero.text }}</slot>
  </p>
  

• 在index.md中使用插槽：

  <template #hero-text>
    A publishing platform marrying d3 and… <TextRotator/>
  </template>
  
  ---
  layout: home
  hero:
    name: MyProject
    tagline: Self-congratulatory tag line
  ...
  ---
  

4. 排查组件本身的问题 #

• 在TextRotator组件的mounted钩子中添加日志，确认组件是否被实例化：

  <script setup>
  import { onMounted } from 'vue'
  onMounted(() => {
    console.log('TextRotator mounted')
  })
  </script>
  

  若控制台无输出，说明组件未被Vue解析；若有输出但页面为空，检查组件内部的数据、模板逻辑是否正常。

5. 全局注册组件（可选） #

将TextRotator全局注册到主题中，避免局部引入的潜在问题：
在.vitepress/theme/index.ts中添加：

import { defineTheme } from 'vitepress'
import TextRotator from './components/TextRotator.vue'

export default defineTheme({
  enhanceApp({ app }) {
    app.component('TextRotator', TextRotator)
  }
})

内容的提问来源于stack exchange，提问作者Scott Deerwester