1. 项目概述在 Next.js App Router 中实现 AI 流式响应如果你正在用 Next.js 14 及以上的 App Router 架构开发一个集成了大语言模型LLM的应用比如智能客服、写作助手或者代码生成工具那么“流式输出”这个功能大概率是你绕不开的一个技术点。传统的请求-响应模式是用户问一个问题前端等着后端把完整的答案生成好一次性吐回来用户盯着一个空白的输入框或者加载动画干等好几秒体验非常割裂。而流式输出就像打开了一个水龙头答案是一个字一个字、一段一段地“流”到前端的用户可以几乎实时地看到思考过程和生成内容体验的流畅度和科技感直接拉满。这个项目的核心就是在 Next.js 的 App Router 框架下打通从后端 AI 服务比如 OpenAI GPT、Anthropic Claude或者本地部署的开源模型到前端页面的流式数据管道。它不仅仅是调用一个 API 那么简单涉及到 App Router 中 Server Actions、Route Handlers 的合理运用React Server Components (RSC) 与 Client Components 的边界划分以及前端如何用最新的 React 特性如usehook来消费这个流。我最近在重构一个内部知识库问答系统时完整地实践了这套方案踩过一些坑也总结出不少能让项目更稳定、代码更优雅的经验。接下来我就把这套方案的思路、具体实现和避坑指南毫无保留地分享给你。2. 技术架构设计与核心思路拆解在动手写代码之前我们必须把技术选型和架构思路理清楚。在 Next.js App Router 的范式下实现流式输出主要有两条主流路径它们各有优劣适用的场景也不同。2.1 方案对比Server Action vs. Route Handler第一种方案是使用Server Action。这是 Next.js 14 大力推崇的模式它允许你在服务端组件中定义异步函数并直接在客户端组件中调用。对于流式输出你可以在 Server Action 中返回一个ReadableStream。它的优点是开发体验非常“一体化”感觉像是在写全栈函数无需显式创建 API 端点。但缺点也很明显Server Action 的流式响应目前对错误处理和中间件的支持不如传统的 API Route 灵活并且在复杂的身份验证或需要精细控制 HTTP 头如 CORS的场景下会有些力不从心。第二种方案是使用Route Handler。也就是在app/api/目录下创建一个标准的 API 端点。这是更经典、更可控的方式。你可以完全掌控 HTTP 请求和响应的每一个细节方便集成各种中间件错误处理机制也更为成熟。对于需要与第三方 AI 服务其 SDK 可能更适配 Node.js 的Response对象深度集成或者项目已有成熟的 API 层架构的情况Route Handler 是更稳妥的选择。我的选择与理由在经历了初期使用 Server Action 后我最终在正式项目中转向了 Route Handler。主要原因有三点一是可控性API Route 让我能更方便地添加请求速率限制、详细的日志记录和统一的错误响应格式二是兼容性像openai或ai-sdk这样的官方 SDK它们提供的流式接口通常期望一个 Node.js 的Response对象在 API Route 中直接返回这个对象是最自然的三是分离性将 AI 交互逻辑放在独立的 API 端点有助于保持服务端组件的纯粹性逻辑边界更清晰。因此下文将主要围绕Route Handler 方案展开。2.2 数据流与组件职责划分无论选择哪种后端方案前端的数据消费逻辑是相通的。整个数据流的脉络可以这样理解用户交互用户在客户端组件例如一个ChatInput组件中输入问题并提交。请求发起客户端使用fetchAPI 向我们的 Next.js Route Handler (/api/chat) 发起请求。服务端代理与流式获取Route Handler 接收到请求后会以“流”的形式向真正的 AI 服务提供商如 OpenAI发起请求。这里的关键是我们不是等待 AI 服务返回完整响应后再转发而是将 AI 服务返回的流“管道式”地连接到返回给客户端的流中。流式响应Route Handler 会立即返回一个Response对象其 body 设置为一个ReadableStream。客户端流式消费客户端接收到这个流式响应使用现代 React 的特性如usehook 或第三方库来逐步读取这个流并更新 UI 状态从而实现文字的逐个出现效果。在这个链条中组件边界的划分至关重要。我的经验是将显示流式内容的区域封装在一个独立的客户端组件中例如StreamingResponseDisplay。这个组件的唯一职责就是消费流并渲染内容。而触发请求的按钮或表单可以放在另一个客户端组件或服务端组件中。这样做符合 React 的单一职责原则也使得组件更容易测试和复用。3. 核心实现构建流式 API 端点理论清晰后我们进入实战环节。首先我们在app/api/chat/route.ts中创建我们的流式聊天端点。3.1 基础实现连接 OpenAI 流假设我们使用 OpenAI 的官方 Node.js SDK。以下是一个最基础的实现它展示了如何创建一个返回ReadableStream的 Route Handler。// app/api/chat/route.ts import { NextRequest } from next/server; import OpenAI from openai; // 初始化 OpenAI 客户端建议从环境变量读取密钥 const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY, }); export const runtime nodejs; // 确保在 Node.js 运行时执行这是流式响应所必需的 export async function POST(request: NextRequest) { try { const { messages } await request.json(); // 假设前端传来 { messages: [...] } // 向 OpenAI 发起流式请求 const openaiStream await openai.chat.completions.create({ model: gpt-4o-mini, messages: messages, stream: true, // 核心参数开启流式输出 }); // 创建一个 TransformStream 来将 OpenAI 的数据流转换为标准的文本流 const encoder new TextEncoder(); const transformStream new TransformStream({ async transform(chunk, controller) { // OpenAI SDK 返回的流是异步迭代器chunk 是一个 ChatCompletionChunk 对象 const text chunk.choices[0]?.delta?.content || ; controller.enqueue(encoder.encode(text)); }, }); // 将 OpenAI 的流通过转换流管道连接并返回给前端 const readableStream ReadableStream.from(openaiStream).pipeThrough(transformStream); return new Response(readableStream, { headers: { Content-Type: text/plain; charsetutf-8, Cache-Control: no-cache, Connection: keep-alive, // 重要确保浏览器知道这是流式响应 X-Accel-Buffering: no, // 针对 Nginx 代理 }, }); } catch (error) { console.error(Chat API error:, error); return new Response(JSON.stringify({ error: Internal Server Error }), { status: 500, headers: { Content-Type: application/json }, }); } }关键点解析stream: true这是调用 AI 服务 API 时开启流式的关键开关。TransformStream这是一个 Web Streams API 中的强大工具。OpenAI SDK 返回的流对象格式是特定的我们需要将其“转换”为前端容易处理的纯文本流或 JSON 流。transform方法中的chunk.choices[0]?.delta?.content就是提取每个流片段中新生成的文本内容。响应头‘Cache-Control’: ‘no-cache’和‘Connection’: ‘keep-alive’对于流式传输至关重要它们告诉浏览器和中间代理不要缓存响应并保持连接开放。‘X-Accel-Buffering’: ‘no’在如果你使用 Nginx 作为反向代理时特别有用它禁止 Nginx 缓冲这个响应让数据能直接流到客户端。3.2 进阶处理支持 Server-Sent Events (SSE) 格式上面的例子返回的是纯文本流。但在更复杂的场景中我们可能希望传递结构化数据比如同时返回文本和推理状态。这时Server-Sent Events (SSE)格式是一个非常好的选择。SSE 是一种简单的、基于文本的协议专门为服务器向客户端单向推送事件流而设计浏览器有原生支持EventSource但在 Next.js 中我们通常用fetch来消费。我们可以修改转换流将数据包装成 SSE 格式// ... 前面的初始化代码相同 ... const transformStream new TransformStream({ async transform(chunk, controller) { const text chunk.choices[0]?.delta?.content || ; if (text) { // 将数据格式化为 SSE 的 data: 行 const payload JSON.stringify({ content: text, done: false }); controller.enqueue(encoder.encode(data: ${payload}\n\n)); } }, flush(controller) { // 流结束时发送一个结束事件 const finalPayload JSON.stringify({ done: true }); controller.enqueue(encoder.encode(data: ${finalPayload}\n\n)); } }); // 返回时 Content-Type 改为 text/event-stream return new Response(readableStream, { headers: { Content-Type: text/event-stream; charsetutf-8, Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no, }, });这样前端接收到的就是标准的事件流可以更灵活地处理不同类型的数据块和结束信号。4. 前端消费React 中的流式数据渲染后端管道搭建好了接下来就是前端如何优雅地消费这个流。在 React 的演进中处理异步流数据的方式也在变化。4.1 传统方式手动处理 ReadableStream在 React 18 之前我们需要手动使用fetch并解析响应体流。这种方式比较底层但能让你理解整个过程// app/components/StreamingChat.tsx use client; import { useState, useCallback } from react; export function StreamingChat() { const [input, setInput] useState(); const [messages, setMessages] useStateArray{role: string, content: string}([]); const [isLoading, setIsLoading] useState(false); const [currentStream, setCurrentStream] useState(); const handleSubmit useCallback(async (e: React.FormEvent) { e.preventDefault(); if (!input.trim()) return; setIsLoading(true); setCurrentStream(); // 开始新的流清空当前缓存 const userMessage { role: user, content: input }; setMessages(prev [...prev, userMessage]); setInput(); try { const response await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ messages: [...messages, userMessage] }), }); if (!response.ok || !response.body) { throw new Error(Network response was not ok); } const reader response.body.getReader(); const decoder new TextDecoder(utf-8); let accumulatedText ; while (true) { const { done, value } await reader.read(); if (done) { // 流结束将累积的完整消息存入历史 setMessages(prev [...prev, { role: assistant, content: accumulatedText }]); setCurrentStream(); break; } const chunk decoder.decode(value, { stream: true }); accumulatedText chunk; // 实时更新当前流式显示的内容 setCurrentStream(accumulatedText); } } catch (error) { console.error(Fetch error:, error); // 处理错误例如显示错误信息 } finally { setIsLoading(false); } }, [input, messages]); return ( div div {messages.map((msg, idx) ( div key{idx}strong{msg.role}:/strong {msg.content}/div ))} {/* 实时显示流式内容 */} {currentStream ( divstrongassistant:/strong {currentStream}/div )} /div form onSubmit{handleSubmit} input value{input} onChange{(e) setInput(e.target.value)} disabled{isLoading} / button typesubmit disabled{isLoading}发送/button /form /div ); }这种方式代码量较多需要手动管理reader、解码和循环并且状态更新setCurrentStream可能会比较频繁对性能有一定影响。4.2 现代方式使用 React 的useHook 与第三方库React 18.3 引入了实验性的useHook它可以“消费”一个 Promise 或 Context。结合流式处理我们可以有更声明式的写法但需要将流转换为异步迭代器。目前更主流、更成熟的做法是使用社区库。使用ai-sdk/react(Vercel AI SDK)这是目前与 Next.js App Router 集成度最高的方案之一。它抽象了底层流的细节提供了非常易用的 Hook。首先安装npm install ai// app/components/AISdkChat.tsx use client; import { useChat } from ai/react; // 从 ai/react 导入 import { useState } from react; export function AISdkChat() { const { messages, input, handleInputChange, handleSubmit, isLoading } useChat({ api: /api/chat, // 指向你的流式 API 端点 // 可选初始消息、流模式配置等 onFinish(message) { // 流式响应完成后的回调 console.log(Finished streaming:, message); }, }); // useChat 已经帮你管理了所有状态和流式更新 return ( div div {messages.map((msg) ( div key{msg.id}strong{msg.role}:/strong {msg.content}/div ))} /div form onSubmit{handleSubmit} input value{input} onChange{handleInputChange} disabled{isLoading} / button typesubmit disabled{isLoading}发送/button /form /div ); }使用useSWR或react-query的流式扩展如果你项目已经使用了这些状态管理库也有相应的流式支持插件如swr/subscription。但 Vercel AI SDK 因其与 Next.js 的深度绑定和开箱即用的体验成为了很多开发者的首选。我的实操心得对于新项目尤其是重度依赖 AI 功能的我强烈推荐直接从ai-sdk开始。它不仅仅处理 UI 状态还提供了统一的generateText、streamText等函数可以在 Server Component 或 Server Action 中直接调用后端代码也会变得更简洁。它能帮你处理很多边界情况比如请求中断、错误重试等节省大量自己造轮子的时间。5. 性能优化与稳定性保障流式输出引入了长连接对应用的稳定性和性能提出了新要求。以下是我在实践中总结的几个关键优化点。5.1 超时与中断处理流式请求可能持续很长时间。必须设置合理的超时并允许用户主动中断。服务端超时在 Vercel 或类似 Serverless 平台上需要关注函数执行超时时间默认可能只有10秒。对于长对话你可能需要调整这个配置。在 Route Handler 中虽然 Node.js 环境限制较少但也应设置一个最大时长逻辑。客户端超时与中断使用AbortController是标准做法。// 在客户端组件中 const handleSubmit async () { const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), 60000); // 60秒超时 try { const response await fetch(/api/chat, { method: POST, signal: controller.signal, // 传入 abort signal // ... 其他配置 }); // ... 处理流 } catch (error) { if (error.name AbortError) { console.log(请求被用户或超时中断); } } finally { clearTimeout(timeoutId); } };同时在“停止生成”按钮的点击事件里调用controller.abort()即可实现用户手动中断。5.2 错误处理与重试机制流式传输中网络抖动或服务不稳定可能导致流意外中断。前端的错误处理需要更细致。区分错误类型是网络错误、服务器5xx错误还是 AI 服务商返回的业务错误如内容过滤需要在 API 响应中通过不同的状态码或错误信息体来区分。优雅降级如果流式请求失败是否可以回退到非流式的普通请求在catch块中实现一个备用的fetch请求不带stream: true是不错的用户体验兜底策略。重试策略对于非用户取消的、可重试的错误如网络超时可以实现简单的指数退避重试。但注意对于已消费了一部分的流重试逻辑会非常复杂通常更好的做法是提示用户重新发送。5.3 内存与资源管理长时间运行的流连接会占用服务器资源。务必确保在连接关闭时无论是正常结束还是异常中断清理所有相关资源。监听请求中断在 Route Handler 中可以通过request.signal来监听客户端的AbortSignal。当客户端断开连接用户关闭页面或主动取消时你应该立即停止向 AI 服务请求数据并释放本地资源。export async function POST(request: NextRequest) { const { signal } request; // 获取客户端的 abort signal // 在向 OpenAI 发起请求时也传入这个 signal const openaiStream await openai.chat.completions.create({ model: gpt-4, messages: messages, stream: true, }, { signal }); // 将 signal 传递给 OpenAI SDK 的选项 // ... 后续流处理 }这样当客户端取消请求时不仅会断开与客户端的连接也会中断对 OpenAI 的后端请求避免不必要的计费和资源浪费。清理转换流确保TransformStream的controller在流结束时正确关闭。6. 常见问题排查与调试技巧在实际开发中你肯定会遇到流不工作、内容不更新或者连接意外断开的问题。这里是我整理的一份问题排查清单。6.1 流式响应不生效一直等待然后一次性返回这是最常见的问题通常原因和解决方法如下问题现象可能原因排查步骤与解决方案请求一直处于 pending 状态最后一次性收到所有内容。1.中间件或代理缓冲Nginx、Cloudflare 或 Vercel 等代理默认可能会缓冲响应。检查并确认响应头已正确设置‘Cache-Control’: ‘no-cache’,‘X-Accel-Buffering’: ‘no’(针对 Nginx)。在 Vercel 上确保使用的是Edge Runtime或正确配置了Node.js Runtime。2.未正确返回 ReadableStream后端返回的可能不是真正的流对象。在 Route Handler 中使用return new Response(readableStream, ...)确保返回的是ReadableStream实例而不是PromiseReadableStream或字符串。在 Server Action 中确保函数返回的是ReadableStream。3.AI 服务商未开启流式调用 API 时忘记设置stream: true。仔细检查调用 AI SDK如openai.chat.completions.create时的参数。4.开发环境热重载干扰Next.js 开发服务器的热重载有时会打断长连接。尝试在生产模式 (npm run build npm start) 下测试或暂时禁用部分热重载功能。6.2 前端内容更新卡顿或不流畅流是通的但前端渲染感觉“一卡一卡”的或者更新很慢。状态更新过于频繁在手动处理流的while循环中每收到一个字符就调用setState会导致 React 渲染压力巨大。一个优化策略是使用“防抖”或“节流”的思想累积一小段文本比如每收到50个字符或每100毫秒再更新一次状态。使用useDeferredValue或useTransitionReact 18 的这两个 Hook 可以将非紧急的渲染更新标记为可中断的从而避免阻塞高优先级的用户交互如输入。你可以将流式更新的状态用useDeferredValue包裹或者用startTransition来更新它。检查前端消费逻辑确保decoder.decode(value, { stream: true })中的stream: true被正确设置这能确保多字节字符如中文、Emoji被正确解码避免乱码导致的渲染问题。6.3 部署后流式功能失效本地开发一切正常但部署到 Vercel、Netlify 等平台后流式输出不工作了。运行时确认检查你的部署配置。在route.ts文件顶部通过export const runtime ‘edge’;或export const runtime ‘nodejs’;明确指定运行时。对于流式响应edgeruntime 通常延迟更低但可能不支持某些 Node.js 原生模块nodejsruntime 兼容性更好。根据你使用的 AI SDK 需求来选择。函数超时Serverless 函数有默认执行超时限制Vercel Pro 计划最长300秒Hobby 计划10秒。如果你的对话可能很长需要升级计划或优化逻辑考虑在流式传输过程中定期发送“心跳”数据包来保持连接活跃并确保函数不会因空闲而被终止。网络策略与防火墙确保你的部署平台允许出站请求到你使用的 AI 服务如api.openai.com。有些公司网络或平台策略可能会限制对外部 API 的长连接。6.4 使用ai-sdk时的特定问题useChat不更新消息检查传递给useChat的api路径是否正确并且你的 API 端点返回的流格式是否符合 AI SDK 的预期。AI SDK 默认期望 SSE 格式的流。确保你的后端返回的Content-Type是text/event-stream并且数据格式是data: {...}\n\n。流式响应中出现[DONE]或其他乱码这通常是因为后端没有正确清洗 AI 服务返回的原始数据流。例如OpenAI 的流在结束时可能会发送一个单独的[DONE]事件。你的TransformStream需要过滤掉这些非内容数据块只将有效的delta.content转发给前端。最后调试流式应用时浏览器开发者工具的Network面板是你的最佳伙伴。查看对/api/chat的请求在Response标签页下如果它是流式的你会看到内容在实时加载而不是等待完成后才显示。同时关注Console中的任何错误信息。在服务端使用console.log在关键节点如收到 AI 服务响应、转换数据块、流结束打印日志对于定位问题也至关重要。