迁移指南

Nuxt Content v3 从底层重新设计了内容集合、查询方式和类型系统。它仍然服务于 Markdown 内容管理，但在 API、集合定义和渲染方式上与 v2 有明显差异。

主要变化

查询 API

queryContent() 已被基于集合的 queryCollection() 取代。新的查询方式要求先在 content.config.ts 中定义集合，再基于集合名称进行查询。

const page = await queryCollection('docs')
  .path('/docs/introduction/start')
  .first()

内容集合

v3 推荐使用 defineCollection 显式声明内容来源、类型和 schema。这样可以让内容结构更清晰，也能获得更好的类型推断。

import { defineCollection, defineContentConfig } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: 'docs/**/*.md'
    })
  }
})

组件渲染

旧版本中的部分 Content 组件已经调整或移除。迁移时应优先使用当前版本推荐的渲染方式，例如在页面中查询内容后交给内容渲染组件处理。

路由生成

如果站点使用静态生成，需要确保文档路由被显式纳入预渲染列表，避免部署后出现内容页面缺失。

迁移建议

1. 先梳理现有 content 目录结构，明确哪些内容属于文档、博客或更新日志。
2. 在 content.config.ts 中为每类内容定义集合。
3. 将旧的 queryContent() 调用替换为 queryCollection()。
4. 检查 Markdown 内的本地链接，确保迁移后仍能解析到正确路由。
5. 执行 npm run typecheck、npm run test:sitemap 和 npm run generate 验证迁移结果。

注意事项

• v3 的集合名称会影响查询代码，建议保持命名稳定。
• 静态站点需要显式处理动态内容路由。
• 如果使用自定义 Markdown 组件，应检查组件注册方式是否仍符合 Nuxt 当前版本约定。
• 迁移后应重点检查文档导航、面包屑、SEO 信息和 sitemap。