功能开关
组件文档、Mermaid、AI Chat、无障碍检查等可选功能都由 nuxt.config 中的开关控制,默认关闭的功能不会打包任何相关依赖。本页列出每个开关的默认值、启用后需要安装的依赖,以及关闭时的降级行为。
开关一览
nuxt.config.ts
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
movkNuxtDocs: {
componentDocs: false,
mcp: true,
ogImage: true,
mermaid: false,
a11y: false
},
aiChat: {
enabled: undefined
}
})
| 开关 | 默认值 | 作用 | 需要额外安装 |
|---|---|---|---|
movkNuxtDocs.componentDocs | false | ComponentProps、ComponentSlots、ComponentEmits、ComponentCode、ComponentExample 与 Prettier 格式化 | 是 |
movkNuxtDocs.mcp | true | 内置 MCP Server(@nuxtjs/mcp-toolkit) | 否 |
movkNuxtDocs.ogImage | true | 构建期为每页生成 OG 图片(nuxt-og-image) | 否 |
movkNuxtDocs.mermaid | false | Markdown 中的 Mermaid 图表 | 是 |
movkNuxtDocs.a11y | false | @nuxt/a11y 开发期无障碍检查 | 是 |
aiChat.enabled | 构建期存在 AI_API_KEY 时为 true | AI 聊天助手、浮动输入框与「用 AI 解释」 | 是 |
默认开启的功能(MCP、OG 图片)依赖已随 Layer 安装;默认关闭的功能依赖声明为可选的 peer dependency,启用时由你的项目安装。
AI Chat 通过 MCP Server 读取文档,启用
aiChat 时不能设置 movkNuxtDocs.mcp: false,否则构建会直接报错。安装依赖
启用的功能缺少依赖时,构建会中止并列出缺失的包与安装命令,例如:
[@movk/nuxt-docs] 已启用的功能缺少依赖:
- mermaid: mermaid, dompurify
请安装后重试:pnpm add mermaid dompurify
组件文档
pnpm add nuxt-component-meta vue-component-meta prettier
npm install nuxt-component-meta vue-component-meta prettier
yarn add nuxt-component-meta vue-component-meta prettier
bun add nuxt-component-meta vue-component-meta prettier
启用后,只有通过 componentMeta.include 声明的组件才会生成元数据,见 nuxt.config 选项。
Mermaid
pnpm add mermaid dompurify
npm install mermaid dompurify
yarn add mermaid dompurify
bun add mermaid dompurify
无障碍检查
pnpm add @nuxt/a11y
npm install @nuxt/a11y
yarn add @nuxt/a11y
bun add @nuxt/a11y
AI Chat
pnpm add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
npm install ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
yarn add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
bun add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
再在构建与运行环境中配置 AI_API_KEY(可选 AI_BASE_URL),模型等选项见 AI Chat。
关闭时的行为
关闭的功能不会参与打包与类型检查,调用方无需判断开关:
| 功能 | 关闭后 |
|---|---|
| 组件文档 | 组件文档相关的 MDC 组件不再注册;raw markdown 与 MCP 组件工具读取到的元数据、示例为空 |
| MCP | 不注册 /mcp 端点,/.well-known/mcp/server-card.json 不再生成 |
| OG 图片 | 页面中的 defineOgImage 调用替换为空实现,仍保留 og:title、og:description 等元信息 |
| Mermaid | 语言标识为 mermaid 的代码块按普通代码块显示 |
| a11y | 不加载 @nuxt/a11y |
| AI Chat | AiChat、AiChatPanel 等组件替换为禁用版本,useAIChat() 返回禁用态实现,页头不显示 AI 入口 |
aiChat.enabled 未设置时以构建期是否存在 AI_API_KEY 决定。显式设置 aiChat.enabled: true 但构建期没有该变量时,构建会给出警告,请确认运行环境已配置。
关闭全部可选功能可以获得最小的构建体积与最短的构建时间:
nuxt.config.ts
export default defineNuxtConfig({
movkNuxtDocs: {
mcp: false,
ogImage: false
},
aiChat: {
enabled: false
}
})