---
title: withAiReady
description: Next.js 配置包装器的 API 参考。
canonical_url: https://next-ai-ready.vercel.app/zh/docs/api-reference/with-ai-ready
url: https://next-ai-ready.vercel.app/zh/docs/api-reference/with-ai-ready
last_updated: 2026-08-01
updated: 2026-08-01
author: next-ai-ready 团队
summary: Next.js 配置包装器的 API 参考。
topics: [api, reference]
---

# withAiReady

`withAiReady()` 是一个 Next.js 配置包装器，为 AI 就绪路由添加 URL rewrite 和 file tracing。

## 导入

```ts
import { withAiReady } from "next-ai-ready"
```

消费者应用只需安装 `next-ai-ready`。使用专用 `/config` 子路径，可避免 Next.js 读取配置时加载构建期扫描器与 CLI 模块。

## 用法

```ts
// next.config.mjs
import { withAiReady } from "next-ai-ready"

export default withAiReady()({
  // 你正常的 Next.js 配置
  reactStrictMode: true,
})
```

函数是柯里化的：第一次调用接受选项，第二次调用接受你的 Next.js 配置。

## 选项

```ts
interface WithAiReadyOptions {
  rewrites?: boolean
  fileTracing?: boolean
  agentReadable?: boolean | {
    accept?: boolean
    userAgents?: boolean | string[]
  }
}
```

| 选项              | 类型                  | 默认值     | 说明                                                                                                   |
| --------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `rewrites`      | `boolean`           | `true`  | 为 AI 路由添加 URL rewrite。如果你想自行挂载路由，可禁用。                                                                |
| `fileTracing`   | `boolean`           | `true`  | 添加 `outputFileTracingIncludes` 使 `.next-ai-ready/*.json` 随 serverless bundle 部署。如果你的部署适配器打包整个项目，可禁用。 |
| `agentReadable` | `boolean \| object` | `false` | 显式启用 `Accept: text/markdown` 内容协商，以及面向已知或自定义 Agent User-Agent 的 Markdown 响应；同时添加匹配的 `Vary` 响应头。      |

设置 `agentReadable: true` 会同时开启 Accept 和内置 Agent User-Agent 协商。使用 `agentReadable: { accept: true }` 可只开启 Accept，也可以传入自定义 `userAgents` 列表。API 路径、Next.js 内部路径和带扩展名的路径不会被改写。

## 做了什么

当 `rewrite` 为 `true` 时，添加以下 rewrite：

| 源                 | 目标                          | 用途          |
| ----------------- | --------------------------- | ----------- |
| `/llms.txt`       | `/_ai-ready/llms-txt`       | 全站 LLM 索引   |
| `/llms-full.txt`  | `/_ai-ready/llms-full`      | 完整内容        |
| `/:path*.md`      | `/_ai-ready/md/:path*`      | 每页 Markdown |
| `/:path*.ai.json` | `/_ai-ready/ai-json/:path*` | 每页结构化 JSON  |
| `/openapi.json`   | `/_ai-ready/openapi`        | OpenAPI 规范  |
| `/tools.json`     | `/_ai-ready/tools`          | 工具定义        |

当 `fileTracing` 为 `true` 时，添加：

```json
{
  "outputFileTracingIncludes": {
    "/_ai-ready/**/*": [".next-ai-ready/**/*"]
  }
}
```

这确保构建产物包含在 serverless 函数 bundle 中（Vercel、AWS Lambda 等必需）。

## 与现有配置合并

`withAiReady()` 与你的现有配置合并：

- 如果你的配置有 `rewrites()` 函数，AI rewrite 会被追加。
- 如果你的配置有 `outputFileTracingIncludes`，AI 条目会被合并。
- 所有其他配置属性保持不变。

## 禁用 rewrite

如果你想自行控制 URL 路由：

```ts
export default withAiReady({ rewrites: false })({
  // 不添加 rewrite；你必须自行挂载 /llms.txt 等
})
```

你仍然需要 `app/%5Fai-ready/` 中的 route handler 文件——rewrite 只是将干净 URL 映射到它们。