---
title: 为 Next.js App Router 添加 llms.txt 与 Markdown 端点
description: 判断应该手写还是自动生成 llms.txt，运行一个干净的 Next.js 演示，并验证生产结果。
canonical_url: https://nextaiready.com/zh/docs/guides/nextjs-llms-txt
url: https://nextaiready.com/zh/docs/guides/nextjs-llms-txt
last_updated: 2026-10-01
updated: 2026-10-01
author: next-ai-ready 团队
summary: 判断应该手写还是自动生成 llms.txt，运行一个干净的 Next.js 演示，并验证生产结果。
topics: [nextjs, app-router, ai-search, llms.txt, markdown, tutorial]
---

# 为 Next.js App Router 添加 llms.txt 与 Markdown 端点

最小实现是在 `public/llms.txt` 中手写内容。对于页面少、更新不频繁的网站，这已经足够。
当文件需要与大量页面、摘要、Markdown、结构化数据或 Agent 工具保持同步时，再使用构建集成。

本指南为现有 Next.js App Router 项目添加这些机器接口，不改动现有 UI。

如果项目使用文档框架，请查看专门的 [Nextra 4 指南](./nextra-ai-ready) 或
[Fumadocs 指南](./fumadocs-ai-ready)，其中包含内容目录、插件组合与部署限制。

## 选择满足需求的最小方案

| 使用场景         | 推荐方案                                              |
| ------------ | ------------------------------------------------- |
| 只有少量稳定页面的小网站 | 手写 `public/llms.txt`，内容变化时人工检查。                   |
| 文档站或内容型网站    | 从内容源自动生成 `llms.txt`、`llms-full.txt` 与逐页 Markdown。 |
| 多语言网站        | 自动生成带 locale 的路由，并验证每种语言返回正确内容。                   |
| Agent 需要执行操作 | 先让内容层可读，再按真实需求增加经过鉴权的 Action。                     |

不要为了宣称网站“AI-ready”就立即加入 MCP、数据库或可调用 Action。先完成内容发现与读取，
在生产环境验证，再根据真实使用场景添加能力。

## 先运行一个干净的演示

在改动现有项目之前，先创建最小 App Router 项目：

```bash
npm create next-ai-ready@alpha next-ai-ready-demo
cd next-ai-ready-demo
npm install
npx next-ai-ready init
```

创建 `content/docs/example.mdx`，写入以下内容：

```markdown
---
title: 示例文档
summary: 用于检查 Markdown 端点的非根页面。
---

# 示例文档

此页面用于验证内容源是否以 Markdown 形式提供。
```

然后构建、验证本地接线并启动应用：

```bash
npm run build
npx next-ai-ready doctor --score
npm run dev
```

然后打开：

- `http://localhost:3000/llms.txt`
- `http://localhost:3000/llms-full.txt`
- `http://localhost:3000/docs/example.md`

在另一个终端直接检查非根页面：

```bash
curl -i http://localhost:3000/docs/example.md
```

应返回 `200`、`Content-Type: text/markdown` 和示例页面的标题与正文，而不是缺页恢复文档。
`content/index.mdx` 在语义图中映射为 `/`；当前适配器不会把 `/index.md` 作为根页面的别名，
因此本演示验证明确的非根路由。

alpha.21 的默认 `init` 仅启用知识平面，不会创建 `/openapi.json` 或 `/tools.json`；
需要这些端点时，再使用下方可选的能力平面接入流程。

生成目录就是一个普通的 Next.js TypeScript 项目，可以直接提交、部署，或与现有项目比较小范围
接入差异。生成器本身也会经过仓库的干净安装与生产构建发布门禁。

## 查看生产案例

当前文档站正在运行下方同一套集成：

- [生产 llms.txt](https://nextaiready.com/llms.txt)
- [安装页面的 Markdown](https://nextaiready.com/zh/docs/installation.md)
- [生产 OpenAPI 文档](https://nextaiready.com/openapi.json)
- [生产工具清单](https://nextaiready.com/tools.json)
- [文档站生产源码](https://github.com/mustcanbedo/next-ai-ready/tree/main/examples/docs-site)

生产站还通过了固定版本 Vercel Agent Readability CLI 的全部 25 项检查。该分数只衡量技术
可读性，不代表搜索位置或引用效果。

### 检查实现证据

这是项目自身的生产 dogfood，不是外部客户评价。与其依赖营销截图，不如直接检查实现和断言：

- [生产配置](https://github.com/mustcanbedo/next-ai-ready/blob/main/examples/docs-site/ai-ready.config.mjs)
- [生成本指南的内容源](https://github.com/mustcanbedo/next-ai-ready/blob/main/examples/docs-site/content/zh/docs/guides/nextjs-llms-txt.mdx)
- [生产路由 smoke 检查](https://github.com/mustcanbedo/next-ai-ready/blob/main/examples/docs-site/scripts/docs-site-route-smoke.mjs)
- [可执行 Nextra 4 夹具](https://github.com/mustcanbedo/next-ai-ready/tree/main/examples/nextra-docs)

路由 smoke 会验证 HTML 页面、`llms.txt`、显式 Markdown URL、内容协商、canonical 响应头、
搜索、MCP 读取，以及相互独立的浏览器和 Agent 缺页行为。外部采用单独记录；只有其他项目完成
部署并验证后，才会把它作为客户案例展示。

## 1. 安装

在已有 Next.js App Router 项目中运行：

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

`init` 会创建显式的知识平面 route handler、AI-ready 配置，以及启用 Agent Markdown
协商的 Next.js rewrite 配置，不会修改现有页面组件。

## 2. 添加 AI 可读内容

创建 `content/about.mdx`：

```markdown
---
title: 关于 Acme
summary: Acme 帮助客服团队查找经过核验的产品答案。
author: Acme 团队
updatedAt: 2026-08-02
questions:
  - q: Acme 提供什么服务？
    a: Acme 帮助客服团队搜索经过核验的产品文档。
---

# 关于 Acme

Acme 为客服团队提供一个可搜索的可信产品答案来源。
```

清晰的标题、摘要、作者、更新时间和直接回答同时服务人类与 AI。不要添加可见页面无法支持
的营销主张或 FAQ 答案。

## 3. 生成机器接口

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

构建会生成 discovery 文件和运行时 handler 使用的语义图谱。基础部署会提供：

- `/llms.txt`：简洁的站点发现入口。
- `/llms-full.txt`：合并后的全站上下文。
- `/<page>.md`：读取匹配到的非根内容页面。
- `/sitemap.md`：供 Agent 使用的页面导航。

`/openapi.json`、`/tools.json` 和 `/api/mcp` 属于可选的能力平面，不是默认 `init` 的接入结果。

当 `doctor` 没有错误，并且 `llms.txt` 列出预期页面时，基础接入完成。警告表示仍需处理的
可选质量项或生产配置。

## 检查真实 HTTP 响应

使用 HTTP 检查，避免看似成功的页面其实是重定向或 HTML fallback：

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

两个请求都应返回 `200`。`llms.txt` 应返回纯文本，页面端点应返回来自预期内容源的 Markdown，
而不是缺页恢复文档。如果应用已有 `/about` 页面，普通浏览器访问时仍应返回原有 HTML。
仅添加 `content/about.mdx` 不会创建该浏览器页面。

## 4. 验证生产站

部署后应检查真实公开响应，而不只检查构建产物：

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

同时打开 `https://example.com/llms.txt` 和类似 `https://example.com/about.md` 的真实页面，
确认 canonical URL 指向生产域名，普通浏览器页面仍返回 HTML。

## 常见问题

- **端点返回应用的 HTML 外壳。** 检查导出的 Next.js config 是否由 `withAiReady()` 包装，并确认
  生成的 route handler 已存在。
- **`llms.txt` 为空或缺少页面。** 检查 `ai-ready.config.*` 的 `content` glob，再重新构建。
- **生产产物中出现本地 URL。** 设置生产环境的 `site.baseUrl`，然后重新构建与部署。
- **私有内容出现在生成产物中。** 将它从内容源移除或显式排除；除非部署层另有保护，生成文件
  默认公开。
- **审计分数很高但引用没有增加。** 可读性只是输入条件，不是排名或引用保证；应另行衡量真实
  爬虫访问与引荐流量。

## 后续再添加可调用 Action

`llms.txt` 和 Markdown 首先解决 AI 系统发现、读取内容的问题。可调用 Action 是另一项生产
决策。只有当 Agent 确实需要执行具体操作时再添加，并同时配置鉴权、输入校验和审计日志。

在已经初始化的项目中显式启用：

```bash
pnpm add zod@^4 @modelcontextprotocol/sdk mcp-handler
pnpm exec next-ai-ready init --with-capabilities
```

构建前检查 `ai-ready.config.*`。初始化器会为自己生成的配置补上接线，但无法安全定位插入点时，
会保留已经自定义的配置。如果缺少 `actions` 选项，请手动加入现有 `defineConfig` 对象：

```ts
actions: "./actions/index.ts", // JavaScript 项目使用 index.mjs。
```

然后构建能力产物并检查接线：

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

重启 dev 服务器，然后在另一个终端检查：

```bash
curl -i http://localhost:3000/openapi.json
curl -i http://localhost:3000/tools.json
```

两个端点都应返回 `200` 和包含生成的公开 `ping` action 的 JSON。MCP 读取与调用验证请继续查看
[MCP 接入指南](./mcp-integration)。

## 它不能保证什么

技术层面的 AI-readiness 不能保证某个 AI 产品一定抓取、收录、排名、引用或推荐页面。这些
端点的价值是为优质源内容提供稳定的机器访问方式，实际访问、检索、引用和业务结果仍需单独衡量。

## 相关 Next.js AI 发现指南

- [在 Next.js 中配置面向 AI 爬虫的 robots.txt](./robots-txt)
- [如何为 Next.js App Router 添加 MCP Server](./mcp-integration)
- [为 Fumadocs 添加 llms.txt 与 Markdown 端点](./fumadocs-ai-ready)
- [Nextra llms.txt 与 Markdown 端点配置](./nextra-ai-ready)