从 v2 迁移
- 要求
- @movk/nuxt-docs 3.0
- 难度
- 进阶
升级步骤
- 将
@movk/nuxt-docs升级到^3.0.0 - 按下文 依赖与功能开关 安装你用到的可选依赖
- 确认文档位于
content/docs/ - 检查
app.config.ts与覆盖的组件 - 运行
nuxt build。缺少依赖或配置冲突时构建会直接报错并说明原因
用 AI 迁移
把下面的提示词交给 Claude Code、Cursor、Codex 等编码代理,它会按本页的变更清单检查并修改你的项目。代理也可以直接读取本页的 Markdown 版本:https://docs.mhaibaraai.cn/raw/docs/getting-started/migration.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 个。启用某项功能而未安装依赖时,构建期报错并给出安装命令。完整说明见 功能开关。
组件文档默认关闭
ComponentProps、ComponentSlots、ComponentEmits、ComponentCode、ComponentExample 需要显式开启:
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
movkNuxtDocs: {
componentDocs: true
}
})
pnpm add nuxt-component-meta vue-component-meta prettier
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 检索文档。同时设置以下两项会在构建期抛错:
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
export default defineAppConfig({
github: {
- per_page: 50
+ perPage: 50
}
})
不再默认过滤提交日期
v2 默认 since 为 2025-01-31、until 为构建时刻,早于该日期与构建之后的提交都看不到。v3 的 github.since / github.until 默认留空,不做限制。需要限定范围时显式设置:
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 }
}
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' }
]
}
}
})
字段说明见 导航与分类。
视觉默认值
v3 以编辑式排版作为默认外观。想保留 v2 的样子,可以逐项改回。
主色与中性色
默认主色由 green 改为 vermilion,中性色由 slate 改为 paper,背景不再是纯白:
export default defineAppConfig({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
}
}
})
字体
Layer 默认加载 Inter、Fraunces 与 JetBrains Mono(仅拉丁字符),标题使用衬线体。改回全站无衬线:
export default defineAppConfig({
theme: {
font: 'sans'
}
})
v2 自动加载的 Alibaba PuHuiTi 中文字体 CDN 已移除。字体栈仍会优先使用 Alibaba PuHuiTi,自行引入样式表即可生效:
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 中覆盖:
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 已删除,删除对它们的引用即可:
<script setup lang="ts">
- definePageMeta({ heroBackground: 'opacity-30' })
</script>
<template>
- <HeroBackground />
<ContentRenderer :value="page" />
</template>
useToolCall 的 state 类型放宽
在项目中覆盖 useToolCall 时,state 参数类型由 AI SDK 的 ToolState 放宽为 string,避免核心代码依赖可选的 ai 包:
-export function useToolCall(state: ToolState, toolName: string, input: Record<string, string | undefined>) {
+export function useToolCall(state: string, toolName: string, input: Record<string, string | undefined>) {