0Pricing
Next.js 15 Fullstack (App Router + Server Actions) · 课时

处理程序中的流式响应与 ReadableStream

使用 ReadableStream 为人工智能令牌、日志和渐进式负载返回增量数据。

处理程序中的流式响应与 ReadableStream 是 CoddyKit 上的免费 Next.js 15 Fullstack (App Router + Server Actions) 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Next.js 15 Fullstack (App Router + Server Actions) 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Next.js 15 Fullstack (App Router + Server Actions) 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Stream a Response?

A normal Route Handler builds the entire body in memory, then sends it all at once. For AI token output, live logs, or large reports, that means the user stares at a blank screen until the very end.

Streaming flips this: you push chunks to the client as they become available. The browser starts rendering the first bytes immediately, time-to-first-byte drops, and you never hold the whole payload in RAM.

  • ReadableStream is the Web Standard primitive Next.js 15 uses for this.
  • You return it directly from a Route Handler inside a Response.
  • It works on both the Node.js and Edge runtimes.

The ReadableStream Shape

A ReadableStream is constructed with an object containing a start(controller) method. Inside it you call controller.enqueue(chunk) to push data and controller.close() when finished.

The chunk should be a Uint8Array of bytes. A TextEncoder turns a string into those bytes. This is pure Web API code, so it runs anywhere a modern JS engine exists.

const encoder = new TextEncoder();

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue(encoder.encode("Hello, "));
    controller.enqueue(encoder.encode("streamed "));
    controller.enqueue(encoder.encode("world!"));
    controller.close();
  },
});

const response = new Response(stream);
console.log("Stream and Response created:", response instanceof Response);

Returning a Stream from a Handler

In app/api/.../route.ts you export an HTTP method function (here GET) and return a Response whose body is the stream.

Always set Content-Type. For plain incremental text, text/plain is fine; for structured event streams you would use text/event-stream (covered later).

This is framework code that needs the Next.js server, so it is not standalone-runnable.

// app/api/hello/route.ts
export async function GET(): Promise<Response> {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    start(controller) {
      controller.enqueue(encoder.encode("chunk-1\n"));
      controller.enqueue(encoder.encode("chunk-2\n"));
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Streaming Over Time with async start

The real power shows when chunks arrive over time. The start method can be async, letting you await between enqueues.

Here a small delay simulates work (an AI provider, a slow query, a job step). Each line reaches the client the moment it is enqueued, not when the loop ends.

  • Use await to pace output without blocking the event loop.
  • Never forget controller.close() or the connection hangs open.
const encoder = new TextEncoder();
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

const stream = new ReadableStream({
  async start(controller) {
    for (let i = 1; i <= 3; i++) {
      await sleep(50);
      controller.enqueue(encoder.encode(`step ${i}\n`));
    }
    controller.close();
  },
});

const reader = stream.getReader();
const decoder = new TextDecoder();
let out = "";
let result = await reader.read();
while (!result.done) {
  out += decoder.decode(result.value);
  result = await reader.read();
}
console.log(out.trim());

Streaming AI Tokens

The classic use case: piping an LLM's token stream straight to the browser so text appears word-by-word. Most AI SDKs expose an async iterable of partial chunks.

You loop over that iterable inside start and enqueue each token's text delta. The user sees the answer build in real time, just like a chat UI.

// app/api/chat/route.ts
import { openai } from "@/lib/openai";

export async function POST(req: Request): Promise<Response> {
  const { prompt } = await req.json();
  const encoder = new TextEncoder();

  const completion = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    stream: true,
    messages: [{ role: "user", content: prompt }],
  });

  const stream = new ReadableStream({
    async start(controller) {
      for await (const part of completion) {
        const token = part.choices[0]?.delta?.content ?? "";
        if (token) controller.enqueue(encoder.encode(token));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Server-Sent Events (SSE) Format

For structured, named events the browser's EventSource understands, use the SSE wire format and the text/event-stream content type.

Each message is a line beginning with data: followed by a payload, terminated by a double newline (\n\n). You can serialize JSON after data:.

  • Content-Type: text/event-stream
  • Cache-Control: no-cache so proxies do not buffer.
  • Connection: keep-alive on the Node runtime.
// app/api/events/route.ts
export async function GET(): Promise<Response> {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      for (const status of ["queued", "running", "done"]) {
        const payload = JSON.stringify({ status });
        controller.enqueue(encoder.encode(`data: ${payload}\n\n`));
        await new Promise((r) => setTimeout(r, 300));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

Streaming Progress Logs

Long-running jobs (imports, builds, batch processing) benefit from streaming a progress log. Each completed step is enqueued so the client can update a live console without polling.

The pattern is identical: do work, enqueue a line, repeat. Below is a runnable simulation of a multi-step job emitting NDJSON (one JSON object per line).

const encoder = new TextEncoder();
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const steps = ["fetch", "transform", "upload"];

const stream = new ReadableStream({
  async start(controller) {
    for (let i = 0; i < steps.length; i++) {
      await sleep(30);
      const line = JSON.stringify({ step: steps[i], pct: ((i + 1) / steps.length) * 100 });
      controller.enqueue(encoder.encode(line + "\n"));
    }
    controller.close();
  },
});

const reader = stream.getReader();
const decoder = new TextDecoder();
let buf = "";
let r = await reader.read();
while (!r.done) {
  buf += decoder.decode(r.value);
  r = await reader.read();
}
for (const l of buf.trim().split("\n")) console.log(JSON.parse(l).step);

Handling Client Disconnects

If the user closes the tab mid-stream, you should stop doing work. The Request carries an AbortSignal on req.signal that fires when the connection drops.

Check req.signal.aborted inside your loop, and optionally use the stream's cancel() callback to release resources (close an LLM connection, abort a DB cursor).

// app/api/long/route.ts
export async function GET(req: Request): Promise<Response> {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 100; i++) {
        if (req.signal.aborted) break; // client left
        controller.enqueue(encoder.encode(`tick ${i}\n`));
        await new Promise((r) => setTimeout(r, 200));
      }
      controller.close();
    },
    cancel(reason) {
      console.log("stream cancelled:", reason);
    },
  });

  return new Response(stream, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Error Handling Inside a Stream

Once you have returned the Response, the HTTP status is already 200 and headers are sent. You cannot switch to a 500 mid-stream.

So wrap risky work in try/catch and surface failures as a chunk (e.g. an SSE event: error line or a JSON error object), then close. Use controller.error(e) only when you want to abruptly tear down the stream.

// app/api/job/route.ts
export async function GET(): Promise<Response> {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      try {
        const data = await riskyWork();
        controller.enqueue(encoder.encode(JSON.stringify(data) + "\n"));
      } catch (err) {
        const msg = err instanceof Error ? err.message : "unknown";
        controller.enqueue(encoder.encode(JSON.stringify({ error: msg }) + "\n"));
      } finally {
        controller.close();
      }
    },
  });

  return new Response(stream, {
    headers: { "Content-Type": "application/x-ndjson" },
  });
}

Edge Runtime and Backpressure

Streaming shines on the Edge runtime. Opt in with export const runtime = "edge". The Edge runtime is built on Web Streams, so the same ReadableStream code works unchanged and starts flushing instantly from a location near the user.

Backpressure: if the client reads slowly, controller.enqueue still buffers. For high-volume producers, prefer a pull-based source or check controller.desiredSize to pace yourself and avoid unbounded memory growth.

// app/api/edge-stream/route.ts
export const runtime = "edge";

export async function GET(): Promise<Response> {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        // desiredSize < 0 means the consumer is behind
        if ((controller.desiredSize ?? 1) > 0) {
          controller.enqueue(encoder.encode(`edge ${i}\n`));
        }
        await new Promise((r) => setTimeout(r, 100));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Consuming the Stream on the Client

On the browser side, fetch gives you response.body, which is itself a ReadableStream. Read it with a reader and decode chunks as they arrive to update the UI progressively.

For SSE specifically you can instead use the native EventSource API. For raw text or NDJSON, the reader loop below is the universal approach.

// components/StreamReader.ts
export async function readStream(url: string, onChunk: (text: string) => void) {
  const res = await fetch(url);
  if (!res.body) throw new Error("No response body to stream");

  const reader = res.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    onChunk(decoder.decode(value, { stream: true }));
  }
}

Quick Check

Test your understanding of streaming Route Handlers.

Recap

You learned how to stream incremental data from Next.js 15 Route Handlers:

  • ReadableStream with start(controller) plus controller.enqueue() / controller.close() is the core primitive; return it inside a Response.
  • An async start lets you await between chunks for AI tokens, progress logs, and SSE events.
  • Use text/event-stream + data: ...\n\n for SSE, or NDJSON for line-delimited JSON.
  • Watch req.signal.aborted for disconnects and clean up in cancel().
  • Status and headers are fixed once you return, so report mid-stream errors as chunks.
  • The Edge runtime (runtime = "edge") runs the same Web Streams code; mind backpressure via desiredSize.

常见问题解答

「处理程序中的流式响应与 ReadableStream」课时是免费的吗？

是的 — 「处理程序中的流式响应与 ReadableStream」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Next.js 15 Fullstack (App Router + Server Actions) 课程的其余内容，请升级到 CoddyKit PRO。 Next.js 15 Fullstack (App Router + Server Actions) 课程共包含 4 节课。

「处理程序中的流式响应与 ReadableStream」这节课中我会学到什么？

使用 ReadableStream 为人工智能令牌、日志和渐进式负载返回增量数据。 你通过在浏览器中直接运行的动手代码来练习 Next.js 15 Fullstack (App Router + Server Actions)，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Next.js 15 Fullstack (App Router + Server Actions) 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Next.js 15 Fullstack (App Router + Server Actions) 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。

「处理程序中的流式响应与 ReadableStream」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Next.js 15 Fullstack (App Router + Server Actions) 课中编写并运行代码吗？

能。每节 Next.js 15 Fullstack (App Router + Server Actions) 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 使用 Web 请求 API 设计 RESTful 路由处理程序
  2. Node 运行时与 Edge 运行时的权衡
  3. 处理程序中的流式响应与 ReadableStream
  4. 使用 Zod 验证请求并返回类型化 JSON
← 返回 Next.js 15 Fullstack (App Router + Server Actions)