从 v2 迁移

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

升级步骤

  1. 将 @movk/nuxt-docs 升级到 ^3.0.0
  2. 按下文 依赖与功能开关 安装你用到的可选依赖
  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。

依赖与功能开关

v3 把默认关闭的功能改为 optional peer 依赖,Layer 的直接依赖由 47 个降到 35 个。启用某项功能而未安装依赖时,构建期报错并给出安装命令。完整说明见 功能开关。

组件文档默认关闭

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

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

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

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

# 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 改为构建报错:

pnpm add mermaid dompurify

启用 AI Chat 时不能关闭 MCP

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

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 已移除。

# 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

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

不再默认过滤提交日期

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

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不加载见下文 字体

页头导航与侧栏分类

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

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

字段说明见 导航与分类。

视觉默认值

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

主色与中性色

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

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

字体

Layer 默认加载 Inter、Fraunces 与 JetBrains Mono(仅拉丁字符),标题使用衬线体。改回全站无衬线:

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

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

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

中文衬线标题的引入方法见 主题与字体。

代码高亮主题

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

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

组件覆盖

以覆盖契约为准

v3 起,可覆盖的组件、挂载位置与 props 以 自定义 页的覆盖契约表为准,在 v3.x 内保持稳定。未列出的组件(如 ThemePickerButton)属于内部实现,可能随版本调整。

页面结构重做

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

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

Layer 覆盖了 ProsePre

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

移除 HeroBackground

HeroBackground 组件与页面 meta heroBackground 已删除,删除对它们的引用即可:

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 包:

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>) {
Copyright © 2024 - 2026