使用 Content Collections 高效管理和渲染文档、博客文章等结构化内容

Content Collections 是一个用于管理内容的模块化工具，常用于从 content/ 目录中提取和处理 .mdx 和 .json 文件，并将其转换为结构化的数据集合。

它非常适合用于文档、博客文章、静态页面等内容驱动型模块的数据建模。

一、安装依赖

确保你已经安装了必要的依赖包，如：

pnpm add @content-collections/core @fumadocs/content-collections

二、配置路径别名（tsconfig.json）

在项目根目录下的 tsconfig.json 中添加路径映射，以便在代码中直接引用 content-collections：

{
  "compilerOptions": {
    "paths": {
      "content-collections": ["./content-collections"]
    }
  }
}

这样你就可以通过以下方式导入内容集合：

import { allPosts } from 'content-collections';

三、创建 content-collections.ts 配置文件

在项目根目录创建或修改 content-collections.ts，定义内容集合。例如：

// content-collections.ts
import { defineCollection, defineConfig } from '@content-collections/core';
import { DEFAULT_LOCALE, LOCALES } from '@/i18n/routing';
import {
  createDocSchema,
  createMetaSchema,
  transformMDX,
} from '@fumadocs/content-collections/configuration';

const docs = defineCollection({
  name: 'docs',
  directory: 'content/docs',
  include: '**/*.mdx',
  schema: (z) => ({
    ...createDocSchema(z),
    preview: z.string().optional(),
    index: z.boolean().default(false),
  }),
  transform: transformMDX,
});

export default defineConfig({
  collections: [docs],
});

1、配置的作用

这个配置文件做了以下几件事：

• 定义集合：使用 defineCollection 定义了一个名为 docs 的集合。
• 指定目录：告诉程序去 content/docs 目录下查找 .mdx 文件。
• 国际化支持：导入国际化相关的语言配置（默认语言和所有支持的语言列表）。
• 设置 schema：定义 frontmatter 元信息的字段类型和默认值。
• 数据转换：使用 transformMDX 将 .mdx 文件正文解析为 HTML 并生成目录（TOC）。

在 content-collections.ts 文件中，schema 和 transform 是两个非常关键的配置项，它们分别用于定义内容集合的数据结构和数据转换逻辑。

2、schema 的作用

用途: 定义每个集合中内容的字段类型、默认值和验证规则。 处理的数据: 每个 .mdx 或 .json 文件中的 frontmatter（文件头部的元信息）。

实现方式: 使用 Zod 库来创建类型安全的 schema。 确保读取的内容具有预期的字段，并对字段进行类型校验。 可以设置默认值或可选字段，以提高灵活性。

3、transform 的作用

用途: 对集合中的每一条内容进行自定义转换，生成更复杂或更适用于前端展示的数据结构。

处理的数据: 包括文件路径、frontmatter 元信息以及文件正文内容。

实现方式: 接收原始内容对象 (data) 和上下文 (context) 返回一个经过处理的新对象 可以访问其他集合的内容（如作者、分类），进行关联处理

四、创建内容文件

在 content/docs 目录下创建一些 .mdx 文件，例如：

示例：content/docs/introduction.mdx

---
title: Introduction
description: Welcome to the documentation.
date: 2025-07-10T10:00:00Z
published: true
---

# Introduction

Welcome to the documentation of this project.

五、在组件中使用内容集合

现在你可以直接在页面组件中导入并使用这些内容：

示例：src/app/docs/page.tsx

import { allDocs } from 'content-collections';

export default function DocsPage() {
  return (
    <div>
      <h1>Documentation</h1>
      <ul>
        {allDocs.map((doc) => (
          <li key={doc.slug}>
            <h2>{doc.title}</h2>
            <p>{doc.description}</p>
          </li>
        ))}
      </ul>
    </div>
  );
}

六、构建与运行

确保你的开发服务器正在运行：

pnpm dev

访问 /docs 路由，你应该能看到所有 .mdx 文件的内容被正确渲染出来。

在 package.json 中配置以下命令：

"dev": "concurrently \"content-collections watch\" \"next dev\"",
"build": "content-collections build && next build"

• dev: 同时启动内容监听与 Next.js 开发服务器，实现热更新。
• build: 先构建内容集合数据，再构建整个 Next.js 应用，确保部署前数据同步完成。

七、编译输出命名规范

在使用 Content Collections 管理内容的项目中，所有集合的完整数据输出文件采用统一命名格式：all<CollectionName>.js（如 allPosts.js, allDocs.js）。该命名方式表示“包含某类内容的全部数据”，具有以下特点：

• 语义清晰：便于开发者快速理解文件用途。
• 约定优于配置：提升项目一致性，避免歧义。
• 易于检索：在大型项目中更方便查找特定集合的全部数据。
• 构建流程集成：由 content-collections.ts 中定义的集合自动构建生成，结合 schema 校验和 transform 处理后输出结构化数据。

建议保持默认命名风格以确保一致性与兼容性，除非构建工具明确支持自定义输出格式。

八、总结

总之，content-collections 提供了一种高效的方式来管理和渲染文档、博客文章等结构化内容。通过合理配置，可以大幅提升开发效率和内容维护能力。

• 所有内容文件放在 content/ 目录下按类别组织
• schema 中使用 Zod 进行类型校验，确保数据一致性
• transform 函数用于生成路由、关联其他集合数据、计算阅读时间等
• 每个集合需定义 name, directory, include, schema, transform
• 集合名称建议使用复数形式（如 posts, docs）；输出文件自动命名为 all<CollectionName>.js（如 allPosts.js）
• 可通过封装中间层统一导出所有集合数据：@/lib/content/index.ts
• 确保 .mdx 文件 frontmatter 符合 schema 定义的字段类型
• 多语言支持可通过文件名后缀识别（如 file.en.mdx, file.zh.mdx）