VitePress 中如何正确引入自定义 Vue 组件？

a'ゞ浚博提问于 2026-03-10 12:05:20 阅读 59

框架

我在 VitePress 项目里想用自己写的 Vue 组件，但总是报错说组件未注册。明明已经按文档在 .vitepress/components 里放了组件，也重启了 dev server，还是不行。

比如我写了个简单的按钮组件，代码是这样的：

<template>
  <button class="my-btn">{{ text }}</button>
</template>

<script setup>
defineProps({ text: String })
</script>

<style scoped>
.my-btn { padding: 8px 16px; background: #409eff; color: white; border: none; }
</style>

然后在 Markdown 里直接写 <MyButton text="测试" /> 就报错，说 Unknown custom element。是不是还要手动注册？文档里没说清楚啊……

我来解答赞 7 收藏

反馈

2 条解答

顺红 Dev Lv1

你这问题太常见了，路径写错了。

VitePress 的自定义组件需要放在 .vitepress/theme/components/ 目录下，不是 .vitepress/components/。就差一个 theme 文件夹，很多人不看文档根本注意不到。

正确做法：

首先把组件移到正确位置：

你的项目/

└─ .vitepress/

   └─ theme/

      └─ components/

         └─ MyButton.vue  # 组件放这里

      └─ index.js         # 主题入口文件

然后在 .vitepress/theme/index.js 里注册：

import Theme from 'vitepress/theme'

import MyButton from './components/MyButton.vue'



export default {

  extends: Theme,

  enhanceApp({ app }) {

    app.component('MyButton', MyButton)

  }

}

这样就能在 Markdown 里正常用了：

<MyButton text="测试" />

另外提醒一下，组件名最好用短横线命名 like my-button，这样在 Markdown 里写的时候不会出错。如果你非要 MyButton 这种大驼峰，HTML 里也得保持一致。

重启 dev server 试试，应该就OK了。

2026-03-12 16:07

Mr.晨羲 Lv1

这个问题我也踩过坑，VitePress自动注册组件有时候确实不太灵。通用的做法是这样的：

首先确认你的组件文件名必须是大驼峰命名，比如MyButton.vue，放在.vitepress/components目录下。这是VitePress自动注册的默认位置。

如果还不行，手动注册最保险。在.vitepress/theme/index.js里这样写：

import DefaultTheme from 'vitepress/theme'

import MyButton from './components/MyButton.vue'



export default {

  extends: DefaultTheme,

  enhanceApp({ app }) {

    app.component('MyButton', MyButton)

  }

}

另外检查下组件引用时的标签名是否匹配，必须和注册时的名称完全一致，包括大小写。

最后记得清理下node_modules/.vite缓存，有时候热更新会抽风。我上次折腾半天发现是缓存问题，删了就好了。

2026-03-10 12:13