从Markdown到生成式UI：AI应用流式渲染的完整实践指南

“为什么我的 AI 应用渲染一个 Markdown 流都要卡半天？”这是我最近在做一个生成式 AI 产品原型时，被问得最多的问题。很多开发者一开始都会想：AI 输出文本嘛，用 Markdown 渲染不就行了？但真到了实际场景里，你会发现事情远没那么简单——AI 的输出是流式的，逐字逐token地到达，如果再遇到代码块、表格、甚至嵌套组件，直接塞给 Markdown 解析器就会疯狂抖动或直接崩掉。这篇文章，就是把我从“简单用 Markdown 渲染”到“做一套支持生成式 UI 的流式渲染链路”的完整实践过程拆给你看。我会讲清楚为什么要做流式渲染，Markdown 在流式场景下有哪些天然的坑，以及怎样设计一套既能渲染文本又能动态渲染组件的架构。不管你是刚接触 AI 应用开发，还是已经在做相关产品，这篇文章都应该能帮你少走不少弯路。

1. 为什么 AI 应用的输出天然需要流式渲染

1.1 从“一次性返回”到“打字机效果”的体验变迁

最早做 AI 应用的时候，很多人的做法是：用户输入问题，后台调用模型接口，等整个回复全部生成完之后，一次性把结果返回给前端。这种做法在交互上有一个致命的缺点——用户在发起请求后，面对的是长达十几秒乃至几十秒的白屏等待。即便你在界面上加一个 loading 动画，用户依然会感到焦虑，甚至会怀疑应用是不是挂了。后来大家开始采用流式输出，也就是把模型生成的内容一个个token地推送给前端，界面上像打字机一样逐字显示。这个体验的提升是巨大的，用户能看着内容一点点生成，心理上的等待感被大大冲淡了。

但流式输出也带来了一个新的问题：后端给到前端的不是完整的、最终态的内容，而是一个不断增长的、可能在任何地方断开的字符串流。如果你只是把它当作一个纯文本串，直接显示在 div 里，还行；但如果你希望界面能正确展示 Markdown 格式，比如标题、加粗、列表、表格，甚至更复杂的 UI 组件，流式场景下的处理难度就陡然上升了。

1.2 为什么纯 Markdown 渲染不足以支撑生成式 UI

Markdown 是一种轻量级标记语言，非常适合表达结构化文本。但 AI 生成的内容往往不只是文本，还包括图表、流程图、任务列表、卡片、甚至可交互的表格。这类内容用 Markdown 来表达是非常吃力的，即便能表达（比如用 Mermaid 语法画图），最终也要靠前端解析成对应的组件。也就是说，我们需要的并不是“渲染 Markdown 字符串”，而是“根据 AI 输出的指令或数据，动态渲染出对应的 UI 组件”。

于是问题被拆成了两层：第一层，AI 输出的原始内容是什么？第二层，我们如何把这一坨不断增长的内容，安全又高效地转成界面上的真实组件？这两个问题合在一起，就是我们今天要讨论的“从 Markdown 到生成式 UI 的流式渲染实践”。

1.3 流式渲染的本质：增量数据 + 增量渲染

所谓流式渲染，本质上就是“增量处理”。后端产生一段数据就推一段数据，前端收到一段数据就更新一次视图。这里最核心的挑战其实是：如何保证每一次增量更新都高效、无感、不出错。如果每次收到新数据都全量重新解析、重新渲染整棵 UI 树，那么随着内容越来越多，性能会急剧下降。如果每次都拿不完整的 Markdown 去解析，还会频繁出现解析错误、渲染闪烁。

我的理解是，流式渲染的核心不是“快”，而是“稳”。这里的稳包含三层含义：一是渲染结果稳定，不要因为中间态导致布局剧烈抖动；二是解析过程稳定，不要因为不完整的语法而直接抛异常或渲染空白；三是更新性能稳定，不要因为内容变长就越来越卡。后面我讲的整个方案，都是围绕这三层“稳”展开的。

2. 流式数据管道的设计与关键取舍

2.1 传输层：SSE 还是 WebSocket

先解决后端到前端的数据传输。目前主流方案有两种：SSE（Server-Sent Events）和 WebSocket。SSE 是单向的，服务器向客户端推送数据，底层就是 HTTP 长连接，非常适合 AI 生成这种“客户端请求、服务端持续返回”的场景。WebSocket 是双向的，功能更强大，但复杂度也更高，需要处理心跳、重连、消息协议等一系列问题。

我个人的建议是：如果只是做 AI 聊天或内容生成，优先用 SSE，不折腾 WebSocket。原因很简单，SSE 天然就是为“流式文本推送”设计的，浏览器原生支持 EventSource 接口，断线重连也有内置机制。WebSocket 更适合需要客户端频繁上报状态、而且双向交互非常密集的场景，比如远程协作编辑器。当然，如果你已经在项目里集成了 WebSocket，用它的 Message 事件来做流式推送也完全可行，只是要多处理一些细节。

2.2 协议设计：给每个片段编号的流式协议

在数据传输时，最忌讳的是把一堆文本直接用字符串流发过去，前端自己切分。这样不仅容易切错，还会导致状态管理混乱。我的做法是设计一个简单的 JSON 格式的数据帧，每一帧包含序号、类型、数据。序号用来确保前端能正确拼接和识别缺失的帧，类型用来区分这是普通文本增量、Markdown 内容还是组件指令，数据就是实际的内容片段。

举个例子，后端推送的消息大致是这样：

{"id": 1, "type": "text", "data": "你要的报表结果如下"} {"id": 2, "type": "md", "data": "| 月份 | 销售额 |"} {"id": 3, "type": "component", "data": {"name": "BarChart", "props": {"data": [...]}}}

前端拿到这些帧之后，不是直接把它们拼成一个字符串，而是维护一个有序的消息队列。文本和 Markdown 内容走解析渲染的管道，组件指令则直接进入组件注册表，去动态实例化对应的 UI 组件。这种设计把“展示什么内容”和“内容长什么样子”解耦开，非常灵活。

2.3 增量缓冲区的设计：如何吞下不完整的 Markdown

流式数据有一个天然的问题：你永远不知道下一帧会不会补全上一帧的语法。比如后端正在发送一个表格：

| 名称 | 数量 |后面还没有跟着| 分数 | 81 |以及最后的结束管道符。那么前端接收到第一行时，这个表格是不完整的，直接解析必然出错。解决这个问题，需要一个增量缓冲区。

缓冲区的工作原理可以这么理解：每收到一个新的文本片段，就把它追加到缓冲区末尾，然后对整个缓冲区做一次“尝试性解析”。如果解析成功，就把新渲染出来的部分同步到界面上；如果解析失败，说明内容还不完整，那就继续等待下一片段的到来。但是这里有一个问题：如果每次都全量解析，性能依然比较差。所以我会配合一个“脏区域标记”：记录上一次解析结果中哪些部分是稳定的、哪些部分处于未完成状态。比如一个表格在最后一次管道符出现之前都是不稳定区域；一个列表在连续两个换行之前，最后一项可能还在变化。对这些区域做增量更新，只重新渲染变化的部分，而不是整棵树重绘。

3. Markdown 流式解析的难点与实战策略

3.1 不完整语法的三种典型表现

在实际处理中，不完整的 Markdown 语法主要有三类问题会频繁出现。

第一类是块级元素未闭合，比如代码块。AI 在生成代码时，通常会先输出```python和第一行代码，然后逐步输出更多代码，最后才输出结束的```。如果前端的解析器不够健壮，一旦遇到未闭合的代码块，可能会把后面所有内容都当作代码的一部分，直接导致整个页面布局错乱。

第二类是表格行不完整。前面也提到过，表格必须有一行表头加一行分隔线才能被识别，如果只发过来第一行，解析器可能不知道怎么处理，有的解析器会直接把它当成普通段落，那么等后续内容到达时，就会出现渲染结果的“跳跃”——一会儿是段落，一会儿突然变成表格，导致界面闪烁。

第三类是嵌套列表的缩进问题。AI 生成的列表常常有两种缩进形式同时出现，而且子列表的父级项还没结束，子列表就开始了，这种不完整的树状结构也很容易让解析器报错。

3.2 一个安全增量解析器的设计思路

我在实践中总结了一个比较稳妥的策略，叫“分层渐进解析”。大致分两层：第一层是“粗粒度分段”，第二层是“细粒度堆积”。

粗粒度分段指的是，先将缓冲区中的文本按“可能完整的分割点”切分。什么是可能完整的分割点？比如连续两个换行符、一个表格的完整行、一个列表项的结束符\n且下一行不是列表语法时。这些分割点共同构成了一条“安全边界”。只要在这个边界内，我们可以保证块级元素的完整性。

细粒度堆积指的是，对于没有达到安全边界的内容，统一放入一个“待定区”暂存。待定区的内容不会直接渲染，而是等待后续数据到达后重新判断。例如收到第一行表格时，它被放进待定区，继续收到分隔行后，这两行一起进入待定区，直到收到数据行，确认这三行能组合成一张表格，才一次性把这个表格渲染出来。这种“延迟到完整再渲染”的思路，虽然稍微有点时延，但换来了界面的绝对稳定。

3.3 避免渲染闪烁的另一个关键：锚定更新

除了解析上的策略，还有一个前端渲染上的技巧叫“锚定更新”。想象一下，用户正在阅读一个长回答，屏幕上已经显示了好几百个字。此时如果从某个位置插入新的一行，或者某个列表项突然变成了标题，浏览器默认会重新布局整个文档，导致阅读位置跳来跳去。为了对用户友好，我们需要在每次更新时，记录当前可视区域的锚点元素，比如用户眼睛正在看的那个段落，然后在下一次更新时，优先保持这个锚点的位置不变，只让变化的内容在锚点之后插入。

实现锚定更新的方法不复杂，大体是：每次渲染完成后，记录当前内容树中处于视口中心附近的元素标识；下一次更新时，在新增内容插入之前，先调整滚动位置，确保该元素仍然处于视口中心附近。这个方法虽然只是一小段代码，但对阅读体验的提升非常明显。

4. 从 Markdown 到生成式 UI：组件化渲染架构

4.1 当“内容”变成“指令”：Markdown 里如何携带组件意图

如果只是做一个普通聊天应用，渲染 Markdown 就够了。但如果要做“生成式 UI”，就必须让模型输出能够映射到具体的 UI 组件上。有两种常见的方式可以做到这件事。第一种是约定一种扩展语法，比如在 Markdown 中插入特定的 HTML 块、JSON 块或自定义标记，例如：

<div>const buffer = { text: '', // 文本缓冲区 nodes: [], // 已渲染的节点列表 pendingComponent: null, // 等待组件的插槽 }; const emitters = new Set(); // 订阅者，用于触发渲染 function appendChunk(chunk) { buffer.text += chunk.data; // 每一次追加都触发一次渲染更新 emitters.forEach(fn => fn(buffer)); }

前端通过 SSE 或 WebSocket 接收到数据帧后，调用appendChunk更新缓冲区。而视图层通过订阅buffer的变化来增量解析和渲染。这个“订阅-发布”模型是整个流式渲染管道的地基，它保证了无论数据从哪来，视图层都能有条不紊地响应。

5.2 增量解析器的简化实现

我们将解析器拆成两个核心方法：tryParse(text)和getIncompleteRanges(text)。tryParse负责把文本转成 AST；getIncompleteRanges负责找出哪些块还处于不完整状态，这些不完整块会被强制移入待定区。

整个算法大致可以这样写：

function analyzeBuffer(text) { const lines = text.split('\n'); const blocks = []; let i = 0; while (i < lines.length) { if (isTableStart(lines, i)) { // 从 i 开始向后找完整的表格结构 const table = consumeTable(lines, i); if (table.complete) { blocks.push({ type: 'table', node: table.node, range: table.range }); i = table.endIndex; } else { // 不完整则放入待定区 blocks.push({ type: 'pending', raw: lines.slice(i).join('\n') }); break; } } else if (isCodeBlockStart(lines[i])) { // 类似表格，检测代码块结束标记 // ... } else { // 普通段落或列表，按行聚合 } } return blocks; }

实际实现中还要处理很多边界情况，比如表格内的换行、代码块内的大括号、列表缩进宽度等。但核心思想是一致的：不完整的块不渲染，完整块进入最终渲染列表。

5.3 组件插槽的接入实现

假设协议中传过来一个组件指令帧，我们在文本缓冲区里先插入一个占位符：[[COMPONENT_3]]。解析器在生成节点时，会记录这个占位符的位置。当视图层渲染到该位置时，发现它属于一个组件插槽，就调用组件工厂创建实例。

function renderBuffer(buffer) { const root = document.getElementById('content'); root.innerHTML = ''; for (const block of buffer.blocks) { if (block.type === 'table') { root.appendChild(renderTable(block.node)); } else if (block.type === 'componentSlot') { const component = createComponent(block.componentName, block.props); root.appendChild(component.element); } else { root.appendChild(renderTextBlock(block)); } } }

为了性能，这个renderBuffer不应该构建整个 DOM，而应该做 diff 更新。具体到项目里，我常会用虚拟 DOM 库或细粒度的 DOM 替换策略，只在节点的增删位置做局部更新。

5.4 演示验证：AI 生成一份含表格、代码块和图表的结果

我用这个方案跑了一个真实场景：让模型输出一份包含成绩统计、代码示例和柱状图的数据分析报告。模型先输出一段文字，接着输出一个 Markdown 表格，再输出一段 Python 代码块，最后插入一个图表组件指令。

整个过程在没有做流式处理时，界面会经历：全屏空白→等待十几秒→一次性出现全部内容（包括图表）。用户无法感知生成进程，体验非常差。用了流式方案后，界面表现是：文字逐字出现，表格到完整边界时一次性成型，代码块在出现时就能从起始行开始按语法高亮显示，当文本提到“图表如下”时，组件插槽位置先显示一个骨架屏，随后图表数据逐渐到位，柱子平滑长出来。这种体验才是一个真正可用的 AI 应用该有的样子。

6. 常见问题、排查技巧与性能调优

6.1 解析状态错乱：多半是待定区处理不当

如果你发现屏幕上的内容偶尔会突然撤回、消失或者重影，大概率是增量解析时待定区处理出了问题。比如上一轮你把它当成“段落”渲染了，下一轮内容补齐后你把它重新当成“表格”渲染，但旧 DOM 没有被正确卸载，就会导致残留。我的排查办法是：在开发模式下，给每个渲染块加上一个>