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

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

框架

我在 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。是不是还要手动注册？文档里没说清楚啊……

我来解答赞 0 收藏

反馈

1 条解答

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