---
title: "从 v2 迁移"
description: "逐条列出从 @movk/nuxt-docs v2 升级到 v3 的破坏性变更，每项给出 v2 与 v3 写法对比。按顺序检查依赖与功能开关、内容目录、配置字段、视觉默认值和组件覆盖，即可完成升级。"
canonical_url: "https://docs.mhaibaraai.cn/docs/getting-started/migration"
---
# 从 v2 迁移

> 逐条列出从 @movk/nuxt-docs v2 升级到 v3 的破坏性变更，每项给出 v2 与 v3 写法对比。按顺序检查依赖与功能开关、内容目录、配置字段、视觉默认值和组件覆盖，即可完成升级。

## 升级步骤

1. 将 `@movk/nuxt-docs` 升级到 `^3.0.0`
2. 按下文 [依赖与功能开关](#%E4%BE%9D%E8%B5%96%E4%B8%8E%E5%8A%9F%E8%83%BD%E5%BC%80%E5%85%B3) 安装你用到的可选依赖
3. 确认文档位于 `content/docs/`
4. 检查 `app.config.ts` 与覆盖的组件
5. 运行 `nuxt build`。缺少依赖或配置冲突时构建会直接报错并说明原因

## 用 AI 迁移

把下面的提示词交给 Claude Code、Cursor、Codex 等编码代理，它会按本页的变更清单检查并修改你的项目。代理也可以直接读取本页的 Markdown 版本：`https://docs.mhaibaraai.cn/raw/docs/getting-started/migration.md`。

````md
你正在把**当前项目**（@movk/nuxt-docs 的使用方）升级到 **@movk/nuxt-docs 3.0**。

v3 把默认关闭的功能改为 optional peer 依赖，固定了内容目录，重命名了部分配置字段，并以编辑式排版作为新的视觉默认值。大多数变更在构建期直接报错，少数（视觉默认值、组件覆盖）只会改变外观。

你的任务：

1. 只在**当前仓库**中查找受下列变更影响的代码、配置与内容。
2. 按清单改为 v3 写法，不要为旧写法添加兼容层。
3. 保持站点现有行为与外观；第 6 节的视觉默认值先询问我是否保留 v2 外观，再决定是否改回。
4. 完成后运行项目的 `nuxt build`、类型检查与测试，修复由迁移引起的失败。
5. 最后列出：修改的文件、新安装的依赖、需要我人工确认的项。

## 不要改动

- `extends: ['@movk/nuxt-docs']` 写法不变
- 覆盖 `useHeader` / `useCategory` 的旧写法仍然可用；只在我同意时才改为 `app.config` 的 `header.nav` / `docs.categories`
- MDC 语法、frontmatter 字段、文件名数字前缀不变
- `AI_API_KEY`、`AI_BASE_URL`、`NUXT_GITHUB_TOKEN` 环境变量名不变

## 前置

先将 `@movk/nuxt-docs` 升级到 `^3.0.0`，用项目实际使用的包管理器：

```bash
pnpm add @movk/nuxt-docs@^3.0.0
```

## 变更清单

### 1. 可选功能的依赖

以下功能的依赖不再随 Layer 安装。只为项目实际启用的功能安装：

| 功能 | 启用条件 | 需安装 |
|---|---|---|
| 组件文档 | 页面中使用 `ComponentProps` / `ComponentSlots` / `ComponentEmits` / `ComponentCode` / `ComponentExample` | `nuxt-component-meta vue-component-meta prettier`，并设置 `movkNuxtDocs.componentDocs: true` |
| AI Chat | 构建期存在 `AI_API_KEY` 或 `aiChat.enabled: true` | `ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes` |
| Mermaid | `movkNuxtDocs.mermaid` 开启 | `mermaid dompurify`（v2 缺依赖时静默跳过，v3 构建报错） |
| 无障碍检查 | v2 默认开启，v3 默认关闭 | 需要时设置 `movkNuxtDocs.a11y: true` 并安装 `@nuxt/a11y` |
| 国际化 | `modules` 中含 `@nuxtjs/i18n` | `@nuxtjs/i18n` |

判断组件文档是否启用：在 `content/` 与 `app/` 中搜索上表的组件名。

### 2. AI Chat 与 MCP

启用 AI Chat 时不能设置 `movkNuxtDocs.mcp: false`，否则构建报错。如两者同时出现，删除 `mcp: false`。

### 3. 内容目录

文档必须位于 `content/docs/`，其他语言位于 `content/{locale}/docs/`，路由前缀固定为 `/docs`。如果文档直接放在 `content/` 下（如 `content/1.getting-started/`），整体移入 `content/docs/`，并更新站内链接、`header.nav`、`docs.categories` 等处的路径。`content/index.md`、`content/releases.*`、`content/templates.*` 保持在 `content/` 根目录。

### 4. 配置字段

- `app.config.ts` 中 `github.per_page` 重命名为 `github.perPage`
- v2 默认只显示 `2025-01-31` 之后、构建时刻之前的提交，v3 不再过滤。原来依赖该行为时显式设置 `github.since` / `github.until`

### 5. 移除的作者私有默认值

v3 不再携带以下默认值。如果站点依赖它们，在项目配置中显式设置：

- `header.avatar`（v2 指向作者头像）
- `github.dateFormat.options.timeZone: 'Asia/Shanghai'`
- Alibaba PuHuiTi 字体 CDN：字体栈仍优先使用该字体，需要时通过 `app.head.link` 自行引入样式表

### 6. 视觉默认值（先询问我）

| 项 | v2 | v3 | 改回 v2 |
|---|---|---|---|
| 主色 / 中性色 | `green` / `slate` | `vermilion` / `paper` | `app.config.ts` 设置 `ui.colors.primary: 'green'`、`ui.colors.neutral: 'slate'` |
| 标题字体 | 无衬线 | 衬线（Fraunces） | `theme.font: 'sans'` |
| 代码高亮 | Nuxt Content 默认 | `github-light` / `github-dark` | `nuxt.config.ts` 设置 `content.build.markdown.highlight.theme` |

项目已显式配置的颜色、字体、高亮主题保持不变。

### 7. 组件覆盖

在 `app/components/` 中查找与 Layer 同名的覆盖组件：

- 可覆盖的组件、挂载位置与 props 以文档「自定义」页的覆盖契约表为准，未列出的（如 `ThemePickerButton`）属于内部实现，提示我需要人工确认
- 页头、侧栏、目录、上下篇、页脚结构已重做；覆盖过这些组件或在 CSS 中依赖其 DOM 结构的，标记出来交给我确认
- `PageHeaderLinks` 的挂载位置改到文档页导语下方的元信息行
- Layer 覆盖了 Nuxt UI 的 `ProsePre`；项目自己的 `ProsePre` 覆盖仍然优先，无需改动

### 8. 删除的 API

- 删除 `HeroBackground` 组件的所有引用，以及 `definePageMeta({ heroBackground: ... })` 中的 `heroBackground`
- 在项目中覆盖 `useToolCall` 时，`state` 参数类型由 `ToolState` 改为 `string`，并删除不再使用的 `ToolState` 导入

## 验证

1. 运行 `nuxt build`。出现「已启用的功能缺少依赖」时按提示安装；出现 `[request error]` 日志说明有死链，修正对应链接
2. 运行项目的类型检查与测试
3. 启动开发服务器，抽查首页、一篇文档页与使用组件文档的页面
````

## 依赖与功能开关

v3 把默认关闭的功能改为 optional peer 依赖，Layer 的直接依赖由 47 个降到 35 个。启用某项功能而未安装依赖时，构建期报错并给出安装命令。完整说明见 [功能开关](https://docs.mhaibaraai.cn/docs/guide/features)。

### 组件文档默认关闭

`ComponentProps`、`ComponentSlots`、`ComponentEmits`、`ComponentCode`、`ComponentExample` 需要显式开启：

```ts [v3 nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  movkNuxtDocs: {
    componentDocs: true
  }
})
```

```bash [安装依赖]
pnpm add nuxt-component-meta vue-component-meta prettier
```

### AI Chat、无障碍检查与国际化需自行安装依赖

AI Chat 的开启条件不变：构建期存在 `AI_API_KEY` 或设置 `aiChat.enabled: true`。区别是依赖不再随 Layer 安装：

```bash
# AI Chat
pnpm add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
# movkNuxtDocs.a11y: true
pnpm add @nuxt/a11y
# 在 modules 中启用 @nuxtjs/i18n
pnpm add @nuxtjs/i18n
```

`@nuxt/a11y` 在 v3 中默认关闭，需要设置 `movkNuxtDocs.a11y: true`。

### Mermaid 缺少依赖时构建失败

v2 中开启 Mermaid 但未安装 `mermaid` / `dompurify` 时会静默跳过，v3 改为构建报错：

```bash
pnpm add mermaid dompurify
```

### 启用 AI Chat 时不能关闭 MCP

AI Chat 通过 MCP Server 检索文档。同时设置以下两项会在构建期抛错：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  aiChat: { enabled: true },
  movkNuxtDocs: {
    mcp: false // 报错：aiChat 依赖 MCP Server
  }
})
```

## 内容目录

文档必须放在 `content/docs/`，其他语言放在 `content/{locale}/docs/`，路由前缀固定为 `/docs`。v2 在缺少 `content/docs/` 时会把文档挂到根路径，但该分支下文档页实际无法访问，v3 已移除。

```bash
# v2：直接放在 content/ 下
content/
├── 1.getting-started/
└── 2.guide/

# v3：移入 content/docs/
content/
└── docs/
    ├── 1.getting-started/
    └── 2.guide/
```

缺少 `content/docs/` 时，构建日志会输出警告。

## 配置字段

### `github.per_page` 重命名为 `github.perPage`

```diff [app/app.config.ts]
export default defineAppConfig({
  github: {
-   per_page: 50
+   perPage: 50
  }
})
```

### 不再默认过滤提交日期

v2 默认 `since` 为 `2025-01-31`、`until` 为构建时刻，早于该日期与构建之后的提交都看不到。v3 的 `github.since` / `github.until` 默认留空，不做限制。需要限定范围时显式设置：

```ts [app/app.config.ts]
export default defineAppConfig({
  github: {
    since: '2025-01-01T00:00:00Z'
  }
})
```

### 移除作者私有的默认值

v3 发布包不再携带以下默认值，需要时在自己的配置中设置：

| v2 默认 | v3 默认 | 恢复方式 |
| --- | --- | --- |
| `header.avatar` 指向作者头像 | `''` | 设置 `header.avatar` |
| `github.dateFormat.options.timeZone: 'Asia/Shanghai'` | 不指定时区 | 在 `github.dateFormat.options` 中设置 `timeZone` |
| 加载 Alibaba PuHuiTi 字体 CDN | 不加载 | 见下文 [字体](#%E5%AD%97%E4%BD%93) |

## 页头导航与侧栏分类

v2 通过在 `app/composables/` 中覆盖 `useHeader` / `useCategory` 定义导航。v3 推荐在 `app.config.ts` 中声明，文案可按语言区分，站内链接自动加语言前缀并计算激活状态。旧写法仍然可用。

```ts [v2 app/composables/useHeader.ts]
export function useHeader() {
  const desktopLinks = computed(() => [
    { label: '文档', to: '/docs/getting-started', active: useRoute().path.startsWith('/docs') }
  ])
  return { desktopLinks, mobileLinks: desktopLinks }
}
```

```ts [v3 app/app.config.ts]
export default defineAppConfig({
  header: {
    nav: [
      { label: { 'zh-CN': '文档', 'en': 'Docs' }, to: '/docs/getting-started', activeMatch: '/docs' }
    ]
  },
  docs: {
    categories: {
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
      ]
    }
  }
})
```

字段说明见 [导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation)。

## 视觉默认值

v3 以编辑式排版作为默认外观。想保留 v2 的样子，可以逐项改回。

### 主色与中性色

默认主色由 `green` 改为 `vermilion`，中性色由 `slate` 改为 `paper`，背景不再是纯白：

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'green',
      neutral: 'slate'
    }
  }
})
```

### 字体

Layer 默认加载 Inter、Fraunces 与 JetBrains Mono（仅拉丁字符），标题使用衬线体。改回全站无衬线：

```ts [app/app.config.ts]
export default defineAppConfig({
  theme: {
    font: 'sans'
  }
})
```

v2 自动加载的 Alibaba PuHuiTi 中文字体 CDN 已移除。字体栈仍会优先使用 `Alibaba PuHuiTi`，自行引入样式表即可生效：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  app: {
    head: {
      link: [
        { rel: 'stylesheet', href: 'https://your-cdn.example.com/fonts/alibaba-puhuiti.css' }
      ]
    }
  }
})
```

中文衬线标题的引入方法见 [主题与字体](https://docs.mhaibaraai.cn/docs/guide/theme)。

### 代码高亮主题

代码块高亮由 Nuxt Content 默认主题改为 `github-light` / `github-dark`。需要其他主题时在 `nuxt.config.ts` 中覆盖：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          theme: { default: 'material-theme-lighter', dark: 'material-theme-palenight' }
        }
      }
    }
  }
})
```

## 组件覆盖

### 以覆盖契约为准

v3 起，可覆盖的组件、挂载位置与 props 以 [自定义](https://docs.mhaibaraai.cn/docs/guide/customization) 页的覆盖契约表为准，在 v3.x 内保持稳定。未列出的组件（如 `ThemePickerButton`）属于内部实现，可能随版本调整。

### 页面结构重做

页头、侧栏、目录、上下篇与页脚的结构和样式均已重做。如果你覆盖过这些组件，或在 CSS 中依赖它们的 DOM 结构，需要对照新实现调整：

- 页头改为双行报头：字标、文字主导航与搜索框在上，编号栏目条在下
- `PageHeaderLinks` 的挂载位置由页面标题右侧改为文档页导语下方的元信息行
- 侧栏当前项改为左侧朱红指示条

### Layer 覆盖了 `ProsePre`

Layer 覆盖了 Nuxt UI 的 `ProsePre`，复制按钮会显示「复制 / 已复制」文字。你在项目中自行覆盖 `ProsePre` 时，以你的实现为准。

### 移除 `HeroBackground`

`HeroBackground` 组件与页面 meta `heroBackground` 已删除，删除对它们的引用即可：

```diff [app/pages/index.vue]
<script setup lang="ts">
- definePageMeta({ heroBackground: 'opacity-30' })
</script>

<template>
- <HeroBackground />
  <ContentRenderer :value="page" />
</template>
```

### `useToolCall` 的 `state` 类型放宽

在项目中覆盖 `useToolCall` 时，`state` 参数类型由 AI SDK 的 `ToolState` 放宽为 `string`，避免核心代码依赖可选的 `ai` 包：

```diff [app/composables/useToolCall.ts]
-export function useToolCall(state: ToolState, toolName: string, input: Record<string, string | undefined>) {
+export function useToolCall(state: string, toolName: string, input: Record<string, string | undefined>) {
```


## Sitemap

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