Web 端实现 AI 内容流式传输与实时 Markdown 渲染

Web 端实现 AI 内容流式传输与实时 Markdown 渲染#

在 AI 时代，用户对响应速度的要求越来越高传统的”等待加载”体验已无法满足需求。刚好做了一个项目踩了不少坑，分享如何实现AI 内容流式传输与实时 Markdown 渲染。

什么是流式传输？#

流式传输（Streaming）是指服务器端持续向客户端发送数据，客户端实时处理并展示，无需等待完整响应。与传统请求-响应模式不同，流式传输能让用户立即看到内容生成过程，大幅提升用户体验。

核心技术栈#

1. Server-Sent Events (SSE)#

轻量级实时通信协议，实现服务器向客户端的单向推送：

1
const response = await fetch('/api/chat-stream', {
2
  method: 'POST',
3
  headers: { 'Content-Type': 'application/json' },
4
  body: JSON.stringify({ question: '你好' })
5
});

2. ReadableStream API#

浏览器原生流式数据处理接口：

1
const reader = response.body?.getReader();
2
const decoder = new TextDecoder();
3

4
while (true) {
5
  const { done, value } = await reader.read();
6
  if (done) break;
7
  const chunk = decoder.decode(value, { stream: true });
8
  processChunk(chunk);
9
}

实现步骤#

第一步：后端流式 API 设计#

后端使用 SSE 格式推送数据（每行以 data: 开头，\n\n 结尾）：

1
// Node.js 后端示例
2
app.post('/api/generate-content-stream', async (req, res) => {
3
  res.writeHead(200, {
4
    'Content-Type': 'text/event-stream',
5
    'Cache-Control': 'no-cache',
6
    'Connection': 'keep-alive'
7
  });
8

9
  // 模拟流式生成内容
10
  const content = await generateContent(req.body);
11

12
  for (const token of content) {
13
    const data = JSON.stringify({ content: token });
14
    res.write(`data: ${data}\n\n`);
15
  }
16

17
  res.write('data: [DONE]\n\n');
18
  res.end();
19
});

第二步：前端流式数据接收#

1
async function streamGenerateContent(
2
  params: GenerateParams,
3
  onChunk: (content: string) => void
4
) {
5
  const response = await fetch('/api/generate-content-stream', {
6
    method: 'POST',
7
    body: JSON.stringify(params)
8
  });
9

10
  const reader = response.body?.getReader();
11
  const decoder = new TextDecoder();
12
  let buffer = '';
13

14
  while (true) {
15
    const { done, value } = await reader!.read();
16
    if (done) break;
17

18
    buffer += decoder.decode(value, { stream: true });
19
    const lines = buffer.split('\n');
20
    buffer = lines.pop() || '';
21

22
    for (const line of lines) {
23
      if (line.startsWith('data: ')) {
24
        const data = line.slice(6);
25
        if (data && data !== '[DONE]') {
26
          try {
27
            const parsed = JSON.parse(data);
28
            if (parsed.content) {
29
              // 累积内容（关键点：追加而非替换）
30
              onChunk(parsed.content);
31
            }
32
          } catch (e) {
33
            console.error('JSON 解析失败:', e);
34
          }
35
        }
36
      }
37
    }
38
  }
39
}

第三步：实时 Markdown 渲染#

使用 Streamdown 库实现增量 Markdown 渲染：

1
npm install streamdown
2
import { Streamdown } from 'streamdown';
3

4
function ContentReader({ content, isLoading }) {
5
  return (
6
    <div className="markdown-content">
7
      {isLoading ? (
8
        <div>正在生成内容...</div>
9
      ) : (
10
        <Streamdown>{content}</Streamdown>
11
      )}
12
    </div>
13
  );
14
}

为什么使用 Streamdown？

✅ 支持不完整的 Markdown 片段
✅ 增量渲染，无需等待完整内容
✅ 自动处理语法未闭合的情况

第四步：状态管理与增量更新#

1
function ChatPanel() {
2
  const [messages, setMessages] = useState<Message[]>([]);
3
  const [isStreaming, setIsStreaming] = useState(false);
4

5
  const sendMessage = async (question: string) => {
6
    // 创建用户消息
7
    const userMsg: Message = { id: Date.now(), type: 'user', content: question };
8
    setMessages(prev => [...prev, userMsg]);
9

10
    // 创建 AI 消息占位符
11
    const aiMsgId = `ai-${Date.now()}`;
12
    const aiMsg: Message = { id: aiMsgId, type: 'ai', content: '' };
13
    setMessages(prev => [...prev, aiMsg]);
14
    setIsStreaming(true);
15

16
    // 流式接收回复
17
    await streamChat(
18
      { question, history: messages },
19
      (chunk: string) => {
20
        // 增量更新 AI 消息内容（关键！）
21
        setMessages(prev => prev.map(msg =>
22
          msg.id === aiMsgId
23
            ? { ...msg, content: msg.content + chunk }
24
            : msg
25
        ));
26
      },
27
      () => setIsStreaming(false)
28
    );
29
  };
30

31
  return (
32
    <div className="chat-container">
33
      {messages.map(msg => (
34
        <div key={msg.id} className={msg.type}>
35
          <Streamdown>{msg.content}</Streamdown>
36
        </div>
37
      ))}
38
    </div>
39
  );
40
}

关键实现要点#

1. 数据累积模式#

1
// ❌ 错误：替换内容会导致闪烁
2
setContent(newContent);
3

4
// ✅ 正确：累积内容
5
setContent(prev => prev + newChunk);

2. 缓冲区管理#

1
let buffer = '';
2
buffer += chunk;
3
const lines = buffer.split('\n');
4
buffer = lines.pop() || ''; // 保留未完整的一行

3. 首块优先响应#

1
let isFirstChunk = true;
2
onChunk((chunk) => {
3
  if (isFirstChunk) {
4
    setLoading(false); // 立即关闭加载态
5
    isFirstChunk = false;
6
  }
7
  setContent(prev => prev + chunk);
8
});

最佳实践#

错误处理：每个流操作都应有 onError 回调
连接管理：SSE 自动处理重连，无需手动干预
性能优化：使用 useCallback 避免不必要的重渲染
用户体验：

显示”正在生成…“提示
收到首块数据后立即隐藏加载态
提供取消操作选项

完整示例#

完整代码可参考 LearnOS 项目：

流式 API：src/lib/api/courseService.ts (第 539 行)
实时渲染：src/components/learning/organisms/MainContentReader.tsx (第 111 行)

踩坑列表#

使用react-markdown组件，无法适配流式渲染，试了很久
后端流式发送消息块的时候一定要进行编码，不然前端收到的可能被转码导致接受内容和发送的不一致

总结#

流式传输 + 实时 Markdown 渲染的核心是：

使用 SSE 协议持续推送数据
ReadableStream 实时读取流
Streamdown 增量渲染 Markdown
累积式状态更新避免闪烁

通过这套方案，就可以实现即输入即得结果的流畅体验。