---
title: "功能开关"
description: "组件文档、Mermaid、AI Chat、无障碍检查等可选功能都由 nuxt.config 中的开关控制，默认关闭的功能不会打包任何相关依赖。本页列出每个开关的默认值、启用后需要安装的依赖，以及关闭时的降级行为。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/features"
---
# 功能开关

> 组件文档、Mermaid、AI Chat、无障碍检查等可选功能都由 nuxt.config 中的开关控制，默认关闭的功能不会打包任何相关依赖。本页列出每个开关的默认值、启用后需要安装的依赖，以及关闭时的降级行为。

## 开关一览

```ts [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，启用时由你的项目安装。

> [!WARNING]
> 
> AI Chat 通过 MCP Server 读取文档，启用 
> 
> aiChat
> 
>  时不能设置 
> 
> movkNuxtDocs.mcp: false
> 
> ，否则构建会直接报错。

## 安装依赖

启用的功能缺少依赖时，构建会中止并列出缺失的包与安装命令，例如：

```text
[@movk/nuxt-docs] 已启用的功能缺少依赖：
  - mermaid: mermaid, dompurify
请安装后重试：pnpm add mermaid dompurify
```

### 组件文档

```bash [pnpm]
pnpm add nuxt-component-meta vue-component-meta prettier
```

```bash [npm]
npm install nuxt-component-meta vue-component-meta prettier
```

```bash [yarn]
yarn add nuxt-component-meta vue-component-meta prettier
```

```bash [bun]
bun add nuxt-component-meta vue-component-meta prettier
```

启用后，只有通过 `componentMeta.include` 声明的组件才会生成元数据，见 [nuxt.config 选项](https://docs.mhaibaraai.cn/docs/reference/nuxt-config#componentmeta)。

### Mermaid

```bash [pnpm]
pnpm add mermaid dompurify
```

```bash [npm]
npm install mermaid dompurify
```

```bash [yarn]
yarn add mermaid dompurify
```

```bash [bun]
bun add mermaid dompurify
```

### 无障碍检查

```bash [pnpm]
pnpm add @nuxt/a11y
```

```bash [npm]
npm install @nuxt/a11y
```

```bash [yarn]
yarn add @nuxt/a11y
```

```bash [bun]
bun add @nuxt/a11y
```

### AI Chat

```bash [pnpm]
pnpm add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
```

```bash [npm]
npm install ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
```

```bash [yarn]
yarn add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
```

```bash [bun]
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](https://docs.mhaibaraai.cn/docs/ai/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` 但构建期没有该变量时，构建会给出警告，请确认运行环境已配置。

> [!TIP]
> 
> 关闭全部可选功能可以获得最小的构建体积与最短的构建时间：
> 
> ```ts [nuxt.config.ts]
> export default defineNuxtConfig({
>   movkNuxtDocs: {
>     mcp: false,
>     ogImage: false
>   },
>   aiChat: {
>     enabled: false
>   }
> })
> ```


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
