---
title: "nuxt.config 选项"
description: "Layer 在构建期读取的全部 nuxt.config 选项与环境变量，包括功能开关、AI Chat、组件元数据、MCP、llms.txt、代理发现与站点信息。修改这些选项后需要重新构建或重启开发服务器。"
canonical_url: "https://docs.mhaibaraai.cn/docs/reference/nuxt-config"
---
# nuxt.config 选项

> Layer 在构建期读取的全部 nuxt.config 选项与环境变量，包括功能开关、AI Chat、组件元数据、MCP、llms.txt、代理发现与站点信息。修改这些选项后需要重新构建或重启开发服务器。

本页列出 Movk Nuxt Docs 在 `nuxt.config.ts` 中读取或预设的选项。运行时的界面配置见 [app.config 参考](https://docs.mhaibaraai.cn/docs/reference/app-config)。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  site: { name: 'My Docs', url: 'https://docs.example.com' },
  movkNuxtDocs: { componentDocs: true },
  aiChat: { model: 'openai/gpt-5-mini' }
})
```

## `movkNuxtDocs`

功能开关，详见[功能开关](https://docs.mhaibaraai.cn/docs/guide/features)。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `movkNuxtDocs.componentDocs` | `boolean` | `false` | 组件文档：`ComponentProps` / `Slots` / `Emits` / `Code` / `Example`，需安装 `nuxt-component-meta`、`vue-component-meta`、`prettier` |
| `movkNuxtDocs.mcp` | `boolean` | `true` | 内置 MCP Server；启用 AI Chat 时不能关闭 |
| `movkNuxtDocs.ogImage` | `boolean` | `true` | 构建期生成 OG 图片 |
| `movkNuxtDocs.mermaid` | `boolean` | `false` | Mermaid 图表，需安装 `mermaid`、`dompurify` |
| `movkNuxtDocs.a11y` | `boolean` | `false` | `@nuxt/a11y` 开发期无障碍检查，需安装 `@nuxt/a11y` |

## `aiChat`

AI 聊天助手的模块选项，界面文案与图标在 `app.config` 的 `aiChat` 中配置，详见 [AI Chat](https://docs.mhaibaraai.cn/docs/ai/ai-chat)。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `aiChat.enabled` | `boolean` | 构建期存在 `AI_API_KEY` 时为 `true` | 是否启用 AI Chat |
| `aiChat.model` | `string` | `''` | 默认模型，格式为 `provider/model` 或 `model` |
| `aiChat.models` | `string[]` | `[]` | 模型选择器中可切换的模型列表 |
| `aiChat.apiPath` | `string` | `'/api/ai-chat'` | 聊天 API 端点；项目 `server/` 下存在同路径的处理函数时使用你的实现 |
| `aiChat.mcpPath` | `string` | `'/mcp'` | AI Chat 连接的 MCP Server 路径，同时写入 MCP 服务卡片 |

## `componentMeta`

开启 `movkNuxtDocs.componentDocs` 后传给 [nuxt-component-meta](https://github.com/nuxt-content/nuxt-component-meta) 的选项。Layer 默认排除项目 `app/components/` 与 `components/` 下的全部组件，只有 `include` 匹配的组件才会生成元数据。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `componentMeta.include` | `Array<string \| RegExp \| (component) => boolean>` | `[]` | 需要生成元数据的项目组件。字符串按文件路径匹配，支持 `*`（不跨目录）与 `**`；正则同时匹配文件路径与 PascalCase 组件名；函数接收 `{ filePath, pascalName }` |
| `componentMeta.exclude` | 同上 | Nuxt 官方包与以包名注册组件的模块 | 额外排除的组件，追加在 Layer 的默认排除之后 |

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  componentMeta: {
    include: [
      'app/components/ui/**',
      /^Base/,
      ({ pascalName }) => pascalName.endsWith('Input')
    ]
  }
})
```

## `site`

由 `nuxt-site-config` 读取，影响 canonical 地址、站点地图、OG 图片、`llms.txt` 与 MCP 服务卡片。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `site.url` | `string` | 从部署环境推断 | 站点地址，依次读取 `NUXT_PUBLIC_SITE_URL`、`NUXT_SITE_URL` 与 Vercel、Netlify、Cloudflare Pages、GitLab Pages 的部署地址 |
| `site.name` | `string` | `package.json` 的 `name`，其次是 Git 仓库名 | 站点名称，也是 `header.title`、`seo.title`、`llms.title` 的默认值 |

## `mcp`

开启 `movkNuxtDocs.mcp` 时传给 `@nuxtjs/mcp-toolkit` 的选项，未列出的项见该模块文档，详见 [MCP Server](https://docs.mhaibaraai.cn/docs/ai/mcp)。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `mcp.name` | `string` | 由 `@nuxtjs/mcp-toolkit` 决定 | MCP Server 的名称 |
| `mcp.browserRedirect` | `string` | 由 `@nuxtjs/mcp-toolkit` 决定 | 在浏览器中直接访问 MCP 端点时跳转的页面；同时作为 MCP 服务卡片的文档地址，未设置时卡片使用 `/docs` |

## `llms`

传给 [nuxt-llms](https://github.com/nuxt-content/nuxt-llms) 的选项，用于生成 `/llms.txt` 与 `/llms-full.txt`，详见 [LLMs.txt](https://docs.mhaibaraai.cn/docs/ai/llms-txt)。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `llms.domain` | `string` | 推断的站点地址，无法推断时为 `https://example.com` | 文件中链接使用的域名 |
| `llms.title` | `string` | 站点名称 | `/llms.txt` 的标题 |
| `llms.description` | `string` | `package.json` 的 `description` | `/llms.txt` 的描述 |
| `llms.full.title` | `string` | 站点名称 | `/llms-full.txt` 的标题 |
| `llms.full.description` | `string` | `package.json` 的 `description` | `/llms-full.txt` 的描述 |
| `llms.notes` | `string[]` | — | 附加在 `/llms.txt` 末尾的说明 |

## `agentDiscovery`

传给 [nuxt-agent-discovery](https://github.com/benjamincanac/nuxt-agent-discovery) 的选项，Layer 预设了以下值，详见[代理发现](https://docs.mhaibaraai.cn/docs/ai/agent-discovery)。

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `agentDiscovery.skills.dir` | `string` | `'skills'` | Agent Skills 所在目录，相对项目根目录，见 [Agent Skills](https://docs.mhaibaraai.cn/docs/ai/skills) |
| `agentDiscovery.sitemap.markdown.expand` | `string[]` | `['/docs']` | `/sitemap.md` 中展开列出全部子页面的路径 |
| `agentDiscovery.sitemap.markdown.labels` | `Record<string, string>` | `{ 'getting-started': 'Getting Started' }` | `/sitemap.md` 中分节标题的替换文案 |
| `agentDiscovery.siteUrl` / `siteName` | `string` | 取 `site.url` / `site.name` | 发现文档中使用的站点信息 |

MCP 服务卡片与发现链接由 Layer 根据功能开关、`aiChat.mcpPath` 与 `mcp.browserRedirect` 自动生成，不建议手动覆盖。

## `i18n`

在 `modules` 中加入 `@nuxtjs/i18n` 并配置 `i18n.locales` 后启用多语言，详见[国际化](https://docs.mhaibaraai.cn/docs/guide/i18n)。

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `i18n.defaultLocale` | `string` | 默认语言，URL 不带前缀；未设置时取 `locales` 的第一项 |
| `i18n.locales` | `Array<{ code: string, name: string }>` | 语言列表。缺少内置翻译文件或 `content/{code}/docs` 目录的语言会在构建期被过滤并告警；不要声明 `file` |

Layer 固定使用 `prefix_except_default` 路由策略。

## 环境变量

| 变量 | 必需 | 说明 |
| --- | --- | --- |
| `NUXT_GITHUB_TOKEN` | 生产环境建议配置 | GitHub API 令牌，用于版本发布页、提交历史与最后提交时间，避免匿名请求的频率限制 |
| `AI_API_KEY` | 启用 AI Chat 时 | AI Chat 总开关；AI Gateway 与 OpenAI 兼容端点共用 |
| `AI_BASE_URL` | 否 | OpenAI 兼容端点，如 `https://api.deepseek.com/v1`；留空时通过 AI Gateway 调用 |
| `NUXT_PUBLIC_SITE_URL` / `NUXT_SITE_URL` | 否 | 显式指定站点地址，优先于部署平台推断 |


## Sitemap

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