VitePress 默认不支持 Vue 2 组件，因为：
- ✅ VitePress 是基于 Vue 3 + Vite 构建的静态站点生成器；
- ❌ 它的运行时环境是 Vue 3，无法直接渲染 Vue 2 组件（Vue 2 和 Vue 3 的 API、响应式系统、虚拟 DOM 结构都不兼容）。
🚫 直接使用 Vue 2 组件会失败
如果你在 VitePress 的 Markdown 或 .vue 页面中直接引入一个 Vue 2 组件（比如用 Options API 写的、依赖 this.$emit、beforeCreate 等），会出现以下问题：
- 报错：
$attrs is readonly、$listeners is not defined等； - 生命周期钩子不触发；
- 响应式数据失效；
- 模板语法部分兼容，但行为异常。
✅ 可行的解决方案（按推荐度排序）
✅ 方案一：将 Vue 2 组件升级为 Vue 3 兼容写法（最推荐）
💡 如果你控制组件源码，这是唯一长期可靠的方式。
Vue 2.7 已经提供了大部分 Vue 3 Composition API，你可以逐步迁移：
// 原 Vue 2 写法（Options API）
export default {props: ['title'],data() {return { count: 0 }},methods: {increment() {this.count++}}
}
👇 升级为 Vue 3 兼容写法（仍可用 Options API，但避免 Vue 2 特有特性）：
<script>
// 使用 Vue 3 的 defineComponent（类型更好）
import { defineComponent } from 'vue'export default defineComponent({props: {title: String},data() {return { count: 0 }},methods: {increment() {this.count++}}
})
</script>
✅ 这样的组件可以在 Vue 3 环境（包括 VitePress）中正常运行。
🔔 注意：避免使用 Vue 2 特有功能：
$listeners（Vue 3 合并到$attrs）functional组件beforeDestroy→ 改用beforeUnmountdestroyed→ 改用unmounted
⚠️ 方案二：仅展示组件代码（不运行）
如果你只是想文档化 Vue 2 组件（比如写教程、API 说明），不需要实际渲染，可以用代码块：
## BaseButton (Vue 2)```vue
<template><button @click="$emit('click')">{{ label }}</button>
</template><script>
export default {props: ['label']
}
</script>
→ 这样安全，且不会报错。---#### ❌ 方案三：尝试混用 Vue 2 运行时（不推荐，几乎不可行）有人尝试通过 `@vue/compat`（Vue 3 的兼容模式）来运行 Vue 2 代码，但在 **VitePress 中极难集成**，原因：- VitePress 封装了构建流程，难以注入自定义 Vue 运行时；
- `@vue/compat` 需要全局替换 `vue` 模块，而 VitePress 自身依赖 Vue 3；
- 即使成功，也会导致 bundle 体积暴增、HMR 失效、SSR 出错。> 🚫 **结论：不要尝试在 VitePress 中运行真正的 Vue 2 组件。**---### 🔧 补充：如何判断组件是否兼容 Vue 3？你的 Vue 2 组件如果满足以下条件，大概率可在 VitePress 中运行：| 条件 | 是否兼容 |
|------|--------|
| 使用 `defineComponent` | ✅ |
| 用 `props: { x: String }` 而非 `props: ['x']` | ✅（推荐）|
| 不使用 `$listeners` | ✅ |
| 生命周期用 `mounted` / `beforeUnmount` | ✅ |
| 不依赖 `Vue.extend()`、`new Vue()` | ✅ |
| 使用 `<script setup>`（Vue 3 语法） | ✅ |否则就需要改造。---### ✅ 最佳实践建议1. **将文档站点和组件库解耦** - 组件库仍支持 Vue 2；- 文档站（VitePress）使用 **Vue 3 兼容版本** 的组件做 demo。2. **提供两个版本的 demo 组件**
docs/
components/
BaseButton.vue ← Vue 3 兼容版（用于 VitePress）
src/
BaseButton.vue ← 原始 Vue 2 版本
3. **在文档中注明兼容性**
> “以下示例在 Vue 3 环境中运行，Vue 2 用户请参考 [链接]。”---### 总结| 问题 | 答案 |
|------|------|
| VitePress 能直接用 Vue 2 组件吗？ | ❌ 不能 |
| 有没有 hack 方法？ | ⚠️ 理论上可用 `@vue/compat`，但 VitePress 中几乎不可行 |
| 正确做法是什么？ | ✅ 将组件改写为 **Vue 3 兼容的 Options API 或 Composition API** |
| 只想展示代码？ | ✅ 用 Markdown 代码块即可 |> 💡 **记住：VitePress = Vue 3 生态，不是 Vue 2 的运行环境。**如果你提供具体的 Vue 2 组件代码，我可以帮你改写成 Vue 3 兼容版本。