---
title: 用 Next.js MDX 内容集合生成 AI 可读文档
description: 在 Next.js 中配置本地 MDX 内容集合、映射路由、补充有效 frontmatter，并生成 llms.txt、逐页 Markdown 与 JSON-LD。
canonical_url: https://nextaiready.com/zh/docs/guides/mdx-content
url: https://nextaiready.com/zh/docs/guides/mdx-content
last_updated: 2026-10-01
updated: 2026-10-01
author: next-ai-ready 团队
summary: 在 Next.js 中配置本地 MDX 内容集合、映射路由、补充有效 frontmatter，并生成 llms.txt、逐页 Markdown 与 JSON-LD。
topics: [nextjs, mdx, content-collections, frontmatter, llms.txt, ai-readable-docs]
---

# 用 Next.js MDX 内容集合生成 AI 可读文档

MDX 内容集合是一组遵循固定字段和路由规则的 Markdown 或 MDX 源文件。在 Next.js 项目中，next-ai-ready 可以在构建时读取这些文件，生成 `llms.txt`、逐页 Markdown、JSON-LD 与可搜索的语义图，同时保留现有的人类页面和组件系统。

最小流程只有四步：

1. 将 `.md` 或 `.mdx` 源文件保存在仓库中。
2. 初始化接入，并在 `ai-ready.config.*` 中用 `content` glob 匹配这些文件。
3. 为每一页补充清晰的 frontmatter 与直接答案。
4. 运行 `next-ai-ready build` 并验证生成路由。

## 创建本地 MDX 内容集合

在已有 Next.js App Router 项目中安装并初始化一次：

```bash
pnpm add next-ai-ready
pnpm exec next-ai-ready init
```

如果项目已有 AI handler 与 `withAiReady()` 接线，可以跳过 `init`。仅配置内容源可以让 CLI
构建产物，但不会安装运行时 Markdown 路由。

一个小型文档集合可以采用以下结构：

```text
content/
  docs/
    introduction.mdx
    installation.mdx
    deployment.mdx
```

为后面的端点验证创建 `content/docs/installation.mdx`，写入以下内容：

```markdown
---
title: 安装 Acme
summary: 为已有 Acme 项目安装依赖。
---

# 安装 Acme

在应用根目录运行 `pnpm install` 来安装依赖。
```

编辑生成的 `ai-ready.config.ts`（TypeScript）或 `ai-ready.config.mjs`（JavaScript），
配置 next-ai-ready 扫描源文件。使用已有文件，不要另建第二个配置：

```js
// ai-ready.config.ts or ai-ready.config.mjs
import { defineConfig } from "next-ai-ready"

export default defineConfig({
  site: {
    name: "Acme Docs",
    baseUrl: "https://docs.example.com",
  },
  content: ["content/docs/**/*.{md,mdx}"],
})
```

应扫描原始 MDX，而不是其他内容工具生成的 JavaScript。这样 URL、作者信息和 Markdown 输出始终对应维护者可以审阅的内容。

## 添加能贯穿所有产物的 frontmatter

先从同时适用于网页、搜索结果和机器产物的小型字段集合开始：

```yaml
---
title: 在 Vercel 部署 Acme
summary: 构建并部署 Acme Next.js 应用，然后验证公开健康检查端点。
updatedAt: 2026-09-26
author: Acme engineering
tags:
  - nextjs
  - vercel
  - deployment
questions:
  - q: 哪个命令会创建生产构建？
    a: 在应用根目录运行 pnpm build。
---
```

| 字段          | 用途                               |
| ----------- | -------------------------------- |
| `title`     | 页面标题、`llms.txt`、JSON-LD 与搜索结果标题。 |
| `summary`   | 搜索摘要、页面发现与简洁的 Agent 上下文。         |
| `updatedAt` | 内容新鲜度与 `dateModified` 元数据。       |
| `author`    | 生成结构化数据中的作者信息。                   |
| `tags`      | 语义图与页面搜索使用的主题。                   |
| `questions` | 直接答案与可选的 `FAQPage` JSON-LD。      |

只发布页面正文能够支持的元数据。批量生成 FAQ 并不能让薄弱内容变得更有价值。

## 理解文件到路由的映射

默认文件系统数据源会从匹配路径推导路由。`app`、`src/app`、`content` 与 `src/content` 目录会被视为源文件根目录。

| 源文件                                | 生成路由                    |
| ---------------------------------- | ----------------------- |
| `content/index.mdx`                | `/`                     |
| `content/docs/installation.mdx`    | `/docs/installation`    |
| `content/zh/docs/installation.mdx` | `/zh/docs/installation` |

部署前运行构建并检查语义图：

```bash
pnpm exec next-ai-ready build
pnpm exec next-ai-ready doctor --score
```

当页面以正确 canonical URL 出现在 `public/llms.txt` 与 `.next-ai-ready/graph.json` 中时，映射配置才算完成。
在 `content/` 下创建文件不会创建浏览器页面；对应 HTML 路由仍由现有 MDX 渲染流程提供。

## 与现有 MDX 技术栈一起使用

next-ai-ready 是面向机器的构建层，不会替换负责页面渲染的组件系统。

- **Next.js + `@next/mdx`：** 使用 `app/**/*.{md,mdx}` glob 匹配路由文件。
- **本地内容集合：** 扫描原始 `content/**/*.{md,mdx}` 文件。
- **Fumadocs：** 保留其 source 配置，并参考 [Fumadocs 接入指南](./fumadocs-ai-ready)。
- **Nextra：** 保留 Nextra 主题与路由，并参考 [Nextra 接入指南](./nextra-ai-ready)。
- **生成式内容集合工具：** 指向原始 MDX 目录，不要扫描 `.content` 或生成的 JavaScript 目录。

如果浏览器 UI 与源文件采用不同路由规则，应增加显式路由的 Content Source Adapter，避免发布错误 canonical URL。

## 只在真实需要时补充语义信息

大多数页面使用 frontmatter 已经足够。由代码维护的数据源还可以向编译器传入更丰富的语义数据：

```ts
export const semantic = {
  topics: ["install", "quickstart", "pnpm"],
  questions: [
    { q: "如何安装 Acme？", a: "运行 `pnpm add acme`。" },
  ],
  entities: [
    { name: "pnpm", type: "tool", url: "https://pnpm.io" },
  ],
}
```

编译器会确定性提取标题、章节、FAQ、实体与感知 token 的内容块，不调用外部模型，也不需要数据库。

## 验证公开结果

`init` 会在应用构建脚本中加入 `next-ai-ready build`。构建应用并启动生产服务器：

```bash
pnpm build
pnpm start
```

在另一个终端检查上面创建的文件：

```bash
curl -i http://localhost:3000/llms.txt
curl -i http://localhost:3000/docs/installation.md
```

页面应返回 `200`、`Content-Type: text/markdown`、`安装 Acme` 标题与安装依赖的正文，而不是
缺页恢复文档。如果 UI 提供 `/docs/installation`，还应检查普通浏览器响应仍为 HTML。

部署后对真实域名运行审计：

```bash
pnpm exec next-ai-ready audit https://docs.example.com --version 3
```

确认普通页面仍返回 HTML、`.md` 地址返回 Markdown，并且所有 canonical URL 都使用生产域名。

## 常见内容集合问题

- **内容集合为空。** 从项目根目录检查 glob 与忽略规则。
- **路由包含 `content/` 或 `src/app/`。** 升级软件包并检查源目录规则。
- **生成产物出现本地 URL。** 构建前将 `site.baseUrl` 设置为生产域名。
- **UI 路由与语义图路由不一致。** 使用带显式 route 的 Content Source Adapter。
- **私有草稿进入 `llms.txt`。** 从匹配源中排除草稿；除非部署层保护，否则生成产物都是公开的。
- **页面出现在错误搜索词下。** 让 title、summary、H1 与第一段回答同一个具体问题，而不是继续堆标签。

接下来可以完成 [10 分钟安装流程](../installation)，并在部署前使用 `doctor` 验证结果。