---
title: 安装
description: 安装 next-ai-ready 并生成首个配置。
canonical_url: https://next-ai-ready.vercel.app/zh/docs/installation
url: https://next-ai-ready.vercel.app/zh/docs/installation
last_updated: 2026-08-02
updated: 2026-08-02
author: next-ai-ready 团队
summary: 安装 next-ai-ready 并生成首个配置。
topics: [installation, next.js, zod]
---

# 安装

## 前置要求

- **Node.js** 20 或更高版本
- **Next.js** 14.2+ 且使用 App Router（推荐 Next.js 15+；兼容矩阵覆盖 14.2、15 和 16）
- **pnpm**、npm 或 yarn
- **Zod v4**（`zod@^4`）— actions 必需（使用 `z.toJSONSchema()`）

## 安装

```bash
pnpm add next-ai-ready zod@^4
```

这会安装 meta 包，重新导出全部 API 并提供 CLI。

## 完成基础接入

```bash
pnpm exec next-ai-ready init
# 添加或更新 content/**/*.mdx，然后执行：
pnpm exec next-ai-ready build
pnpm exec next-ai-ready doctor --score
```

当 `doctor` 显示 **0 个错误**，且 `public/llms.txt` 已列出你的内容时，基础接入即完成。下方包结构和命令参考均为可选阅读。

> **发布渠道：** 本站跟随 `main`，npm 的 `latest` 与 `alpha` 当前均为 `0.1.0-alpha.17`。本版新增根目录与 `src/` 内容发现、正确的 Nextra/Fumadocs 路由以及 MCP 页面搜索的 locale 过滤。2026-08-02 已通过完整发布门禁、npm manifest 核验及公共 registry 的 pnpm + Next.js 16 生产构建；生产 MCP 也已通过带认证 initialize 与三个页面发现工具调用。

## 包导出说明

| 导入                                                     | 需要 Next.js？      | 用途                                                              |
| ------------------------------------------------------ | ---------------- | --------------------------------------------------------------- |
| `next-ai-ready`                                        | 编写期、配置与 CLI      | `defineConfig`、`defineAction`、`withAiReady`、`aiRobots` 与 CLI 命令 |
| `next-ai-ready/hooks`                                  | 是                | 运行时观测                                                           |
| `next-ai-ready/handlers/*`                             | 是（`server-only`） | `app/%5Fai-ready/` 路由 stub                                      |
| `next-ai-ready/actions`、`/config`、`/json-ld`、`/robots` | 否或运行时专用          | 避免加载无关构建代码的专用 API                                               |
| `next-ai-ready/audit`                                  | 否                | 不加载 CLI 调度器的程序化 Audit                                           |

典型应用只需：`pnpm add next-ai-ready`。`@next-ai-ready/*` 为内部包，无需单独安装。

`jiti` 已是 `@next-ai-ready/next` 的运行时依赖，并会随 meta 包安装。因此使用 TypeScript `ai-ready.config.ts` 时无需自行添加 `jiti`。

**可选 peer 与应用依赖：**

| 包                                         | 场景                        |
| ----------------------------------------- | ------------------------- |
| `zod@^4`                                  | Actions（实际项目必需）           |
| `mcp-handler`、`@modelcontextprotocol/sdk` | MCP                       |
| `next`                                    | 仅 route handler — CLI 不需要 |

消费者应用请只使用 **`next-ai-ready`** 的 CLI；`@next-ai-ready/next` 的 bin 供 monorepo 开发（C-01）。

## 脚手架（推荐）

```bash
npm create next-ai-ready my-site
cd my-site
npm install
npx next-ai-ready init
```

脚手架会生成可直接运行的最小 Next.js App Router TypeScript 应用，其中包含 `app/layout.tsx`、`app/page.tsx`、TypeScript/Next.js 配置和初始 `content/index.mdx`。模板不会预置 AI-ready 配置或 handler stub；安装依赖后，最后一条 `next-ai-ready init` 命令会生成并接好这些文件。

## 初始化

在尚未初始化的脚手架项目或已有 Next.js 项目中：

```bash
npx next-ai-ready init
```

将创建：

- TypeScript 项目中的 `ai-ready.config.ts`，或 JavaScript 项目中的 `.mjs` — 站点配置（含 robots 策略说明）
- `instrumentation.ts` + `instrumentation-node.ts` — 可选观测 hook（`next-ai-ready/hooks`，Edge 安全拆分）
- `app/%5Fai-ready/` — `llms.txt`、`openapi.json` 等路由 handler
- `app/api/actions/` — action 执行端点
- `app/api/mcp/` — MCP 服务端点
- TypeScript 项目中的 `actions/index.ts`，或 JavaScript 项目中的 `.mjs` — 含 `ping` 健康检查的 starter action

`init` 还会从公共 meta 包为 `next.config` 注入 `withAiReady()`，并在缺失时将 `next-ai-ready build` 加入 build 脚本。

`%5F` 是 `_` 的 URL 编码。Next.js 会把字面量目录 `app/_ai-ready/` 当作私有目录并排除在路由系统之外；`app/%5Fai-ready/` 才会正确提供 `/_ai-ready/*` URL。请勿重命名生成的目录。从 alpha.10 或更早版本升级时，请重新运行 `npx next-ai-ready init`，确认没有本地定制后再删除旧的 `app/_ai-ready/` 目录。

## 配置

编辑 `ai-ready.config.mjs`：

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

export default defineConfig({
  site: {
    name: "My Site",
    baseUrl: "https://example.com",
    description: "供 AI 使用的简短站点描述。",
  },
  content: ["app/**/*.mdx", "content/**/*.mdx"],
  actions: "./actions/index.mjs",
});
```

### Robots 策略

`next-ai-ready build` 默认生成 `public/robots.txt`；若设置 `emit: { robots: false }` 则跳过。动态策略请在 `app/robots.ts` 中使用来自 `next-ai-ready` 的 `aiRobots()`。Doctor 认可该组合，不会误报缺少静态 `public/robots.txt`。

## 构建

```bash
npx next-ai-ready build
```

扫描内容、编译语义图，并将 AI 产物写入 `public/` 与 `.next-ai-ready/`。

## 验证

```bash
npx next-ai-ready doctor --score
```

Doctor 检查配置、action 暴露、`noai`、robots 策略与路由接线。`--score` 提供 0–100 分数与 **Top fixes**。CI 中 exit 0 表示无 error（warning 可接受）。

完整步骤见仓库 [quickstart-10min（中文）](https://github.com/mustcanbedo/next-ai-ready/blob/main/docs/quickstart-10min.zh-CN.md)。