#Next.js 集成

AI SDK 的聊天主路径建立在 Next.js App Router 上：服务端 app/api/chat/route.ts 调 streamText，客户端 'use client' 页用 useChat。Pages Router 有单独官方 Quickstart；新项目请用 App Router。

React 组件规则见 React 教程；类型见 TypeScript。

#推荐文件布局

app/
├── api/chat/route.ts    # POST，密钥只出现在这里
├── page.tsx             # 'use client' + useChat
├── layout.tsx
└── actions.tsx          # 仅当使用实验性 streamUI
.env.local               # AI_GATEWAY_API_KEY，已 gitignore

不要在 page.tsx 里 import { streamText } 并指望浏览器去调模型——那会把逻辑和密钥暴露到客户端。

#Route Handler 要点

import {
  convertToModelMessages,
  createUIMessageStreamResponse,
  streamText,
  toUIMessageStream,
  type UIMessage,
} from 'ai';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: 'openai/gpt-4.1-mini',
    messages: await convertToModelMessages(messages),
    onError({ error }) {
      console.error(error);
    },
  });

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream }),
  });
}

需要鉴权时在 Handler 里读 cookie / session，再决定是否调用模型。不要把用户密钥放进 useChat 的 headers 明文常量。

#环境变量

Next.js 只把 NEXT_PUBLIC_ 变量打进浏览器包。AI 密钥 禁止 这个前缀。

本地用 .env.local；Vercel 在项目 Settings → Environment Variables 配置。改密钥后要重新部署或重启 pnpm dev。

#UI 还是 RSC？

官方模板（Chatbot Starter、Multi-Modal Chat）都是 UI 路径，优先抄那些，而不是 RSC 示例。

#部署清单

1. 生产环境变量与本地一致（Gateway 或 OpenAI Key）。
2. 确认 maxDuration 覆盖最坏延迟。
3. 对 /api/chat 做鉴权与限流（官方有 Rate Limiting 模板）。
4. 日志里不要打印完整 messages（可能含用户隐私）。
5. 模型字符串做成环境变量，避免发版才能改模型。

Pages Router 使用 pipeUIMessageStreamToResponse 写入 Node response；细节以官方 Pages Router Quickstart 为准。

#HarnessAgent 在 Next 里（简介）

若路由背后是 HarnessAgent 而不是 streamText：会话在 harness 内，要按 chat id 恢复 session，不要把整段 UI 历史重放进 generate。返回值仍可 toUIMessageStream 给 useChat。完整模式见官方 Harnesses UI 文档。

#下一步

• 实战案例
• 流式输出
• Provider 与模型