功能开关

组件文档、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.componentDocsfalseComponentProps、ComponentSlots、ComponentEmits、ComponentCode、ComponentExample 与 Prettier 格式化是
movkNuxtDocs.mcptrue内置 MCP Server(@nuxtjs/mcp-toolkit)否
movkNuxtDocs.ogImagetrue构建期为每页生成 OG 图片(nuxt-og-image)否
movkNuxtDocs.mermaidfalseMarkdown 中的 Mermaid 图表是
movkNuxtDocs.a11yfalse@nuxt/a11y 开发期无障碍检查是
aiChat.enabled构建期存在 AI_API_KEY 时为 trueAI 聊天助手、浮动输入框与「用 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

启用后,只有通过 componentMeta.include 声明的组件才会生成元数据,见 nuxt.config 选项。

Mermaid

pnpm add mermaid dompurify

无障碍检查

pnpm add @nuxt/a11y

AI Chat

pnpm 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 ChatAiChat、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
  }
})
Copyright © 2024 - 2026