迁移

Nuxt Content v3 已经从底层进行了重建，形成了一个具有增强功能的新库。虽然我们以与 Content v2 类似的方式重新设计了概念和组件，但破坏性更改是不可避免的。

不用担心，你无需修改你的内容文件。我们确保 Content v3 以与 Content v2 相同的方式处理内容。

变更

Vue utils

• queryContent() API 被新的 queryCollection() 替换

• fetchContentNavigation() API 被新的 queryCollectionNavigation() 替换
• Surroundings 现在有自己独立的 API queryCollectionItemSurroundings()
• 文档驱动模式已删除：Markdown 文件不会自动转换为 Nuxt 页面，你需要创建页面，查看此部分了解如何操作。
• useContent() composable 已删除
• searchContent() 已删除，取而代之的是新的 queryCollectionSearchSections API
• 使用 queryCollectionSearchSections API 可以轻松实现全文搜索，查看此部分了解如何操作

组件

• 所有内容都应该使用 <ContentRenderer> 组件渲染。<ContentDoc>、<ContentList>、<ContentNavigation> 和 <ContentQuery> 组件在 v3 中已删除。
• v3 不支持 <ContentSlot> 和 <MDCSlot> 组件。相反，组件可以直接使用 Vue 原生的 <slot> 组件。

• 在 components/content 目录下创建的组件不再自动注册为全局组件。如果你使用 动态渲染 在 Markdown 文件之外渲染这些组件，则必须在你的 Nuxt 应用程序中手动注册它们。有关如何执行此操作的更多信息，请查看 Nuxt - 自定义组件目录 文档。

类型

• import type { NavItem } from '@nuxt/content/dist/runtime/types' 被 import type { ContentNavigationItem } from '@nuxt/content' 替换

常规

• _dir.yml 文件重命名为 .navigation.yml
• 模块选项中不再有 source 选项，你可以在 content.config.ts 中为你的集合定义 多个来源。
• 文档 ._path 现在重命名为 .path，同样地，所有带有 _ 前缀的内部字段都被移除或重命名。
• useContentHelpers() 已被移除。
• 模块默认不忽略点文件，你可以在集合源的 exclude 选项中添加 ignore: ['**/.*'] 来忽略它们。
• 由于 SQL 的限制，排序现在使用字母顺序而不是数字顺序。有关更多信息，请查看 排序文件 部分。
• 模块选项已从 v2 版本更改。有关详细信息，请查看 配置页面。

Nuxt Studio 集成

• studio 模块 已被弃用，一个新的通用 Preview API 已直接集成到 Nuxt Content 中，你可以从你的依赖项和 nuxt.config.ts 模块中移除 @nuxthq/studio 包。相反，我们只需要通过绑定 Studio API 在 Nuxt 配置文件中启用预览模式。

export default defineNuxtConfig({
  content: {
    preview: {
      api: 'https://api.nuxt.studio'
    }
  },
})

• 为了保持 app config 文件 可以从 Studio 更新，我们只需要将 nuxt.schema.ts 文件中的辅助函数导入从 @nuxthq/studio/theme 更新为 @nuxt/content/preview。

在 v3 中实现文档驱动模式

在 Content v3 中实现文档驱动模式非常简单。你只需要在 Nuxt 中创建一个 catch-all 页面，并根据路由路径获取内容。

<script lang="ts" setup>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('content').path(route.path).first()
})
</script>

<template>
  <div>
    <header><!-- ... --></header>

    <ContentRenderer v-if="page" :value="page" />

    <footer><!-- ... --></footer>
  </div>
</template>

将 queryContent 转换为 queryCollections

正如我们上面提到的，queryContent 被新的基于集合的 queryCollection 所取代。这两者之间有两个主要区别：

1. queryCollection 为 SQL 数据库构建查询。
2. queryCollection 仅在指定的集合内进行搜索。你应该知道集合的名称（配置中的键）。

// Content v2
const v2Query = await queryContent(route.path).findOne()
// Content v3 - don't forget to create `content` collection in `content.config.ts`
const v3Query = await queryCollection('content').path(route.path).first()

// Content v2
const v2Query = await queryContent()
  .where({ path: /^\/hello\/.*/ })
  .find()
// Content v3 - don't forget to create `content` collection in `content.config.ts`
const v3Query = await queryCollection('content')
  .where('path', 'LIKE', '/hello%')
  .first()

转换 queryContent().findSurround()

Surround 现在有其自己独立的 API。

const targetPath = '/docs'

// Content v2
const v2Surround = await queryContent(targetPath)
  .only(['title', 'description', 'navigation'])
  .findSurround(withoutTrailingSlash(route.path))

// Content v3 - don't forget to create `content` collection in `content.config.ts`
const v3Surround = await queryCollectionItemSurroundings(
  'content',
  targetPath,
  {
    fields: ['title', 'description', 'navigation']
  }
)

合并 ProsePre、ProseCode 和 ProseCodeInline 组件

许多 ProsePre 组件都是 ProseCode 组件的简单包装器。我们已将这三个组件合并为两个组件。现在 ProsePre 和多行代码块之间没有区别。

1. MDC 现在会将单个反引号 ` 映射和解析为 ProseCode 而不是 ProseCodeInline。
2. MDC 现在会将以三个反引号 ``` 开头的块代码映射和解析为 ProsePre 组件。

建议的更改：

1. 你当前的 ProseCode 逻辑应该移到 ProsePre
2. 将你的 ProseCodeInline 组件重命名为 ProseCode

_dir.yml 文件重命名为 .navigation.yml

在 Content v3 中，我们将 _dir.yml 重命名为 .navigation.yml。新名称更好地反映了这些文件的用途。模块使用这些文件来收集有关目录的信息以生成导航。

请注意，为了使这些文件可供模块使用，你应该以包含这些文件的方式定义你的集合源。例如，source: '**' 和 source: '**/*.{md|yml}' 将在集合中包含这些文件，但 source: '**/*.md' 不会包含它们。

忽略点文件

默认情况下，Content v3 不忽略点文件。如果你想忽略它们，可以在你的集合源的 exclude 选项中添加 ignore: ['**/.*']。

defineCollection({
  source: {
    include: '**',
    exclude: ['**/.*']
  }
})

请注意，上面的模式也会从集合中排除 .navigation.yml 文件。如果你使用 .navigation.yml 并想保留它们，你可以使用 **/.(!(navigation.yml)) 模式排除除 .navigation.yml 之外的所有点文件。

defineCollection({
  source: {
    include: '**',
    exclude: ['**/.!(navigation.yml)']
  }
})