---
title: "配置总览"
description: "Movk Nuxt Docs 的配置分为 nuxt.config.ts 与 app.config.ts 两处：前者在构建期决定启用哪些模块与功能，后者在运行时控制界面、文案与导航。本页说明两者的分工、生效时机，以及常见需求应该改哪一处。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/configuration"
---
# 配置总览

> Movk Nuxt Docs 的配置分为 nuxt.config.ts 与 app.config.ts 两处：前者在构建期决定启用哪些模块与功能，后者在运行时控制界面、文案与导航。本页说明两者的分工、生效时机，以及常见需求应该改哪一处。

## 两个配置文件

| 文件 | 生效时机 | 负责内容 | 完整参考 |
| --- | --- | --- | --- |
| `nuxt.config.ts` | 构建期 | 继承 Layer、功能开关、AI 模型、MCP、llms.txt、国际化、站点地址 | [nuxt.config 选项](https://docs.mhaibaraai.cn/docs/reference/nuxt-config) |
| `app/app.config.ts` | 运行时 | 页头、页脚、导航、侧栏分类、目录、主题、GitHub 集成、AI Chat 界面文案 | [app.config 参考](https://docs.mhaibaraai.cn/docs/reference/app-config) |

判断改哪一处的规则很简单：会影响**打包了哪些代码、生成哪些路由与文件**的，放 `nuxt.config.ts`；只影响**页面上显示什么**的，放 `app.config.ts`。

> [!NOTE]
> See: https://nuxt.com/docs/4.x/directory-structure/app/app-config
> 
> app.config.ts
> 
>  需要位于 
> 
> app/
> 
>  目录下，并且项目根目录必须存在 
> 
> nuxt.config.ts
> 
> 。

## 最小配置

继承 Layer 后，大多数站点只需要补充站点名称与导航：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  site: {
    name: 'My Docs',
    url: 'https://docs.example.com'
  }
})
```

```ts [app/app.config.ts]
export default defineAppConfig({
  header: {
    nav: [
      { label: '文档', to: '/docs/getting-started', activeMatch: '/docs' },
      { label: '版本发布', to: '/releases' }
    ]
  },
  footer: {
    credits: 'Copyright © 2026 My Team'
  }
})
```

未配置的字段使用 Layer 的默认值。以下几项会在构建期自动推断：

| 字段 | 来源 |
| --- | --- |
| `site.name` | `package.json` 的 `name`，其次是 Git 仓库名 |
| `site.url` | `NUXT_PUBLIC_SITE_URL`、`NUXT_SITE_URL`，或 Vercel、Netlify、Cloudflare Pages、GitLab Pages 注入的部署地址 |
| `header.title` | `site.name` 转为首字母大写 |
| `seo.title` / `seo.titleTemplate` | `site.name`，标题模板为 `%s - {site.name}` |
| `seo.description` | `package.json` 的 `description` |
| `github.owner` / `name` / `url` / `branch` | 本地 Git 信息或 CI 环境变量 |

## 常见任务

| 想做的事 | 改哪里 | 详见 |
| --- | --- | --- |
| 修改页头导航、移动端菜单、侧栏分组 | `app.config` 的 `header.nav`、`header.mobileNav`、`docs.categories` | [导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation) |
| 更换主色、中性色、标题字体 | `app.config` 的 `ui.colors`、`theme.*` | [主题与字体](https://docs.mhaibaraai.cn/docs/guide/theme) |
| 启用组件文档、Mermaid、AI Chat | `nuxt.config` 的 `movkNuxtDocs.*`、`aiChat.*` | [功能开关](https://docs.mhaibaraai.cn/docs/guide/features) |
| 替换页头 Logo、页脚等界面区域 | 在 `app/components/` 中创建同名组件 | [自定义](https://docs.mhaibaraai.cn/docs/guide/customization) |
| 添加版本发布页、案例页、自定义页面 | `content/releases.yml`、`content/templates.yml`、`app/pages/` | [页面与布局](https://docs.mhaibaraai.cn/docs/guide/pages) |
| 支持多语言 | `nuxt.config` 的 `i18n` | [国际化](https://docs.mhaibaraai.cn/docs/guide/i18n) |

## SEO

全站默认值写在 `app.config.ts`，单页覆盖写在 Markdown 的 frontmatter：

```ts [app/app.config.ts]
export default defineAppConfig({
  seo: {
    titleTemplate: '%s - My Docs',
    title: 'My Docs',
    description: '一句话介绍你的项目'
  }
})
```

```md [content/docs/1.getting-started/1.index.md]
---
title: 简介
description: 页面导语，同时作为默认的 meta description。
seo:
  title: Introduction
  description: 搜索引擎与社交卡片使用的描述。
---
```

文档页的 `<title>` 与 OG 图片优先使用 `seo.title`，未设置时回退到 `title`；描述同理。

## GitHub 集成

Layer 从本地 Git 信息推断仓库地址，用于页头 GitHub 图标、「查看源码 / 编辑此页」链接、`PageLastCommit` 与 `CommitChangelog`。文档不在仓库根目录时需要指定 `rootDir`：

```ts [app/app.config.ts]
export default defineAppConfig({
  github: {
    rootDir: 'docs',
    branch: 'main'
  }
})
```

设置 `github: false` 可完全关闭集成。生产环境请配置 `NUXT_GITHUB_TOKEN`，避免 GitHub API 匿名请求的频率限制。

> [!TIP]
> See: /docs/reference/app-config
> 
> github.since
> 
> 、
> 
> github.perPage
> 
> 、
> 
> github.dateFormat
> 
>  等全部字段见 app.config 参考。

## 目录与页脚

```ts [app/app.config.ts]
export default defineAppConfig({
  toc: {
    title: '本页内容',
    bottom: {
      title: '社区',
      links: [
        { icon: 'i-lucide-book-open', label: 'Nuxt UI', to: 'https://ui.nuxt.com', target: '_blank' }
      ]
    }
  },
  footer: {
    credits: 'Copyright © 2026 My Team · <span class="text-highlighted">MIT License</span>',
    socials: [
      { 'icon': 'i-simple-icons-github', 'to': 'https://github.com/my/repo', 'target': '_blank', 'aria-label': 'GitHub' }
    ]
  }
})
```

`footer.credits` 按 MDC 渲染，可以包含链接与行内 HTML。目录底部会自动追加 GitHub 的「编辑此页」链接。


## Sitemap

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