---
title: 为 Nextra 4 添加 llms.txt 与 Markdown 端点
description: 在不替换 Nextra 导航、搜索、主题和 MDX 渲染的前提下，将 next-ai-ready 接入 Nextra 4 App Router 文档站。
canonical_url: https://nextaiready.com/zh/docs/guides/nextra-ai-ready
url: https://nextaiready.com/zh/docs/guides/nextra-ai-ready
last_updated: 2026-09-28
updated: 2026-09-28
author: next-ai-ready team
summary: 在不替换 Nextra 导航、搜索、主题和 MDX 渲染的前提下，将 next-ai-ready 接入 Nextra 4 App Router 文档站。
topics: [nextra, nextjs, llms.txt, mdx]
---

# 为 Nextra 4 添加 llms.txt 与 Markdown 端点

[Nextra 4](https://nextra.site/docs) 是基于 Next.js App Router 的内容型站点框架。Nextra 继续
负责面向用户的文档体验；当你需要同步生成 `/llms.txt`、页面 Markdown、语义发现和可选 MCP
资源时，再把 `next-ai-ready` 放在它旁边。

如果没有使用 Nextra，请从框架无关的
[Next.js App Router llms.txt 实战教程](./nextjs-llms-txt)开始。

本指南支持 Nextra 的根目录 `content/`、`app/` 以及对应的 `src/` 目录，不支持仍使用 Pages
Router 的 Nextra 1-3。

## 可执行参考实现

仓库提供了[可执行 Nextra 4 夹具](https://github.com/mustcanbedo/next-ai-ready/tree/main/examples/nextra-docs)，
已使用 Nextra `4.6.1`、Next.js `16.2.6` 与 React `19.2.4` 验证。同一份 `content/` MDX 同时
驱动 Nextra 界面与 next-ai-ready 语义图；生产 smoke 覆盖 HTML、`/llms.txt`、
`/llms-full.txt`、显式 Markdown 与 AI JSON URL、内容协商，以及相互独立的浏览器和 Agent
缺页契约。

在仓库根目录可复现同一套契约：

```bash
pnpm --filter @next-ai-ready/example-nextra-docs build
pnpm --filter @next-ai-ready/example-nextra-docs test
```

## 1. 安装并初始化

在 Nextra 应用目录执行：

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

`init` 会增加 AI 路由和 `ai-ready.config.mjs`，不会替换 Nextra 的主题、catch-all 页面、搜索
配置或 MDX 组件。

## 2. 让两个系统读取同一份内容

Nextra 支持 `content/`、`src/content/`、`app/` 或 `src/app/` 下的 Markdown 与 MDX。默认
next-ai-ready scanner 已覆盖这些位置。若希望显式限制 Nextra 内容目录，可以这样配置：

```js
import { defineConfig } from "next-ai-ready"

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

项目使用 `src/` 时改为 `src/content/**/*.{md,mdx}`。next-ai-ready 会把 frontmatter 中的
`description` 作为页面摘要，因此无需为了接入再复制一套 Nextra 元数据。

## 3. 组合 Next.js 插件

保留 Nextra 原有插件，再用 `withAiReady()` 包装最终 Next.js 配置：

```js
import nextra from "nextra"
import { withAiReady } from "next-ai-ready/config"

const withNextra = nextra({
  // 原有 Nextra 配置保留在这里。
})

const nextConfig = withNextra({})

export default withAiReady({ agentReadable: true })(nextConfig)
```

该组合保留 Nextra 的 MDX 处理，并增加 AI 页面内容协商。不要启用 Next.js
`output: "export"`，生成的运行时 handler 需要服务器。

### Nextra 4.6.1 与 Zod 4.4 兼容说明

Nextra `4.6.1` 当前声明的 Zod 依赖范围可能把内部依赖解析到 `4.4.x`，导致页面渲染前的
`nextra-theme-docs` layout 校验失败。在上游修复发布前，可只在 workspace 根目录固定 Nextra
自己的副本：

```json
{
  "pnpm": {
    "overrides": {
      "nextra>zod": "4.3.6",
      "nextra-theme-docs>zod": "4.3.6"
    }
  }
}
```

保持 next-ai-ready 使用的 Zod 4 不变；该 override 只作用于 Nextra 的私有副本。上游进度见
[Nextra #4989](https://github.com/shuding/nextra/issues/4989) 与
[#5036](https://github.com/shuding/nextra/issues/5036)；修复版本通过该夹具后即可移除 override。

## 4. 构建并验证

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

部署后验证真实页面与发现文件：

```bash
curl -I https://docs.example.com/llms.txt
curl -I https://docs.example.com/docs/getting-started.md
pnpm exec next-ai-ready audit https://docs.example.com/docs/getting-started --version 3
```

浏览器访问的 Nextra HTML 页面应保持不变，对应 `.md` URL 应返回干净 Markdown；不存在的普通
浏览器页面仍必须返回真实 `404`。

## 先从 Knowledge plane 开始

首次接入 Nextra 时，只发布内容发现与页面读取能力。等项目出现明确 Agent 工作流和认证策略后，
再增加 MCP 或可调用 actions。