像ChatGPT一样逐字输出：React + TypeScript 流式接收与“打字机”效果实现方案

1. 背景与痛点

在 AI 助手场景中，用户期望"模型一边思考，内容一边逐渐显示"，而不是等待完整响应回来后一次性展示。这要求前端同时解决两个问题：

如何读取流式接口：响应体分块到达，同一条消息可能被拆分到不同 chunk；且接口兼容 data: {...} 的 SSE-like 行流格式。

如何实现"打字机"节奏：每次收到增量后，不是整段替换，而是逐字/分段渐显，形成"正在输入"的体验。

本文基于真实项目（React + TypeScript，Vite 构建）的经验，给出完整实现方案。

2. 适用场景与目标

2.1 场景

扁平化输出：纯文本流式增长，打字机效果逐步写入当前消息框。

模块化输出：结构化结果在流式生成过程中被增量解析为多个分区，通过 onPartialResult 持续刷新。

2.2 核心目标

稳定读取 SSE-like 行流，正确处理 chunk 边界（半行 JSON）与 DONE 结束标记。

将解析出的增量文本按顺序累积，并以可控的"打字机节奏"更新 UI。

抽象出可复用的工具函数，与 React 解耦，便于测试和维护。

3. 技术栈与模块职责

分类	技术/模块	职责
前端框架	React + TypeScript	状态驱动 UI 更新
构建代理	Vite	开发环境转发 AI 网关请求
流式读取	fetch + ReadableStream	读取 resp.body 分块
流式解析	sseLikeStreamText.ts（新增）	buffer 拼接、行分割、JSON 解析、增量提取
打字机决策	typewriter.ts（新增）	纯函数计算下一帧展示内容及停止条件
UI 组件	AIChatPanel.tsx / AIMessage.tsx	渲染文本输出区域与结构化消息
状态管理	useAiChatSessions.ts	管理消息列表、流式请求、打字机循环

核心文件路径（基于 src/app/）：

services/
  aiChatClient.ts               # streamChat() / streamDiagnosis()
  sseLikeStreamText.ts          # accumulateSseLikeJsonStreamText()
  aiChatSessionStorage.ts
hooks/
  useAiChatSessions.ts          # 状态 + 打字机循环
utils/
  typewriter.ts                 # decideTypewriterTick()
components/
  AIChatPanel.tsx
  AIMessage.tsx
  shared/device/AIDiagnosisEntry.tsx   # 模块化输出入口

4. 整体链路（一图看懂）

4.1 打字机逐字渲染主流程

onDelta
nextContent
AIChatPanel
useAiChatSessions.sendMessage
aiChatClient.streamChat
fetch + stream
accumulateSseLikeJsonStreamText
appendTypingDelta
queueTyping
pumpTypingTask（每帧）
decideTypewriterTick
patchMessage 更新
React 重渲染，逐字出现

4.2 模块化增量输出流程

模块区 Card accumulateSseLikeJsonStreamText streamDiagnosis AIDiagnosisEntry 模块区 Card accumulateSseLikeJsonStreamText streamDiagnosis AIDiagnosisEntry loop 每收到一个 delta 触发诊断 fetch + 流式读取 onDelta(delta) rawText += delta, 尝试解析部分结构 onPartialResult(partial) setResult(partial) 渐进刷新

5. 核心实现详解

5.1 流式解析：处理 SSE-like 行流与 chunk 边界

5.1.1 协议形态

流式接口返回文本行流，每行可能是：

data: {"response": {...}} （SSE 格式）

纯 JSON 文本

DONE 表示结束

由于网络分块，一个完整的 JSON 行可能被拆到两个 chunk 中，必须用 buffer 拼接。

5.1.2 工具函数：accumulateSseLikeJsonStreamText

位置：src/app/services/sseLikeStreamText.ts（示例文件名）

核心逻辑：

export async function accumulateSseLikeJsonStreamText<T>({
  stream,
  signal,
  parseJson,
  extractText,
  onDelta,
}: {
  stream: ReadableStream<Uint8Array> | null;
  signal: AbortSignal;
  parseJson: (text: string) => T;
  extractText: (parsed: T) => string | undefined;
  onDelta: (delta: string) => void;
}) {
  const reader = stream?.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split(/\n+/);
    buffer = lines.pop() ?? ""; // 保留最后一个可能不完整的行

    for (const rawLine of lines) {
      const line = rawLine.trim();
      if (!line) continue;
      processLine(line);
    }
  }

  function processLine(rawJsonText: string) {
    let jsonText = rawJsonText.trim();
    if (jsonText.startsWith("data:")) {
      jsonText = jsonText.slice(5).trim();
    }
    if (!jsonText || jsonText === "[DONE]") return;

    try {
      const parsed = parseJson(jsonText);
      const delta = extractText(parsed);
      if (delta) onDelta(delta);
    } catch {
      // 忽略不完整 JSON，等待后续 buffer 补全
    }
  }
}

5.1.3 在 aiChatClient.ts 中复用

await accumulateSseLikeJsonStreamText<StreamChunk>({
  stream: resp.body,
  signal,
  parseJson: (text) => JSON.parse(text),
  extractText: extractTextFromChunk,
  onDelta,
});

其中 extractTextFromChunk 遍历 chunk.response.output\[\].content\[\]，找到 type === "output_text" 的 text 字段并返回。

5.2 打字机渲染：从 delta 到逐字显示

5.2.1 节奏控制参数

TYPEWRITER_INTERVAL_MS = 20：每帧间隔

TYPEWRITER_STEP = 2：每次推进的字符数（可调）

5.2.2 纯函数决策器：decideTypewriterTick

位置：src/app/utils/typewriter.ts

输入当前可见内容、目标内容、当前状态等，输出"是否需要 patch、下一帧内容、是否停止、是否继续排程"。

export function decideTypewriterTick(params: {
  currentVisibleContent: string;
  targetContent: string;
  currentStatus: string;
  step: number;
  completionStatus?: string;
}) {
  const { currentVisibleContent, targetContent, currentStatus, step, completionStatus } = params;

  // 情况1：内容已完全一致
  if (currentVisibleContent === targetContent) {
    if (completionStatus && currentStatus !== completionStatus) {
      return { patchRequired: true, nextContent: targetContent, nextStatus: completionStatus, shouldStop: true, scheduleNext: false };
    }
    return { patchRequired: false, shouldStop: true, scheduleNext: false };
  }

  // 情况2：目标内容与当前可见内容不匹配（比如错误强制同步）
  if (!targetContent.startsWith(currentVisibleContent)) {
    const nextStatus = completionStatus ?? "streaming";
    return {
      patchRequired: true,
      nextContent: targetContent,
      nextStatus,
      shouldStop: completionStatus !== undefined,
      scheduleNext: false,
    };
  }

  // 情况3：正常推进
  const nextContent = targetContent.slice(0, currentVisibleContent.length + step);
  return {
    patchRequired: true,
    nextContent,
    nextStatus: "streaming",
    shouldStop: false,
    scheduleNext: true,
  };
}

5.2.3 Hook 中消费决策

useAiChatSessions.ts 内的 pumpTypingTask：

const decision = decideTypewriterTick({
  currentVisibleContent: currentContent,
  targetContent: typingTask.targetContent,
  currentStatus: message.status,
  step: TYPEWRITER_STEP,
  completionStatus: typingTask.completionStatus, // 'done' 或 'error'
});

if (decision.patchRequired) {
  patchMessage(sessionId, messageId, (msg) => ({
    ...msg,
    content: decision.nextContent ?? msg.content,
    status: decision.nextStatus,
  }));
}

if (decision.shouldStop) {
  typingTaskRef.current = null;
  finalizeStreamingStateIfIdle();
  return;
}

if (decision.scheduleNext) {
  typingTimerRef.current = setTimeout(pumpTypingTask, TYPEWRITER_INTERVAL_MS);
}

5.3 结构化消息渲染

AIMessage.tsx 不参与逐字动画，仅根据 message.content 实时解析结构：

按换行分割

以 【标题】 格式识别段落标题

标题下的行作为正文渲染为

由于打字机每帧都会更新 message.content，React 自动重渲染，从而实现渐进显示。

6. 验证与效果

6.1 验证步骤

触发一次 AI 对话，观察文字是否按固定节奏逐字出现。

检查停止/错误场景：状态是否正确转为 done 或 error，内容是否完整显示。

触发模块化输出（如诊断结果），观察分区是否在部分解析时持续刷新。

6.2 预期效果

文本区域内容平滑增长，无突兀跳变。

流式结束时自动停止打字机循环。

模块区卡片内容随解析进度逐步填充。

7. 踩坑与注意事项

chunk 边界半行 JSON

必须保留 buffer 中最后一行，不能直接按行解析每个 chunk。

data: 前缀处理

SSE 格式必须去掉 data: 再 JSON.parse。

JSON 解析失败容忍

不完整 JSON 直接跳过，等待后续 chunk 补全。

频繁 patch 的性能

当前每帧都会触发 React 重渲染和 localStorage 写入（如有持久化）。若消息极长，可考虑对 storage 写入做节流。

8. 总结

本文从项目真实需求出发，系统性地实现了：

SSE-like 行流解析器：处理 buffer、行分割、协议前缀、DONE，输出纯增量文本。

打字机节奏决策器：纯函数决定每帧显示多少内容，何时停止。

与 React 的集成：在自定义 hook 中驱动定时器，每次 patch 消息状态，自动触发 UI 更新。

这两类抽象完全解耦于框架，可直接复用到任何需要"流式增量 + 渐进展示"的前端项目中。如果你也在实现类似 AI 对话效果，不妨参考本文的拆分方式，能让代码更清晰、更容易维护