Skip to main content
LLM 天然生成 Markdown 格式的文本，包括标题、列表、代码块、表格和行内格式。将这些内容渲染为纯文本会浪费模型提供的结构信息。本模式向你展示如何在代理流式传输过程中实时解析和渲染 Markdown，适用于所有主流前端框架。

​
Markdown 渲染的工作原理

渲染流程包含三个步骤：
  1. 接收： useStream 将流式文本累积到每条 AI 消息的 msg.text 中，并在新 token 到达时响应式更新。
  2. 解析： Markdown 解析器将原始文本转换为 HTML（或 React 元素树）。此过程在每次更新时运行，但对于聊天长度的内容足够快（5 KB 消息 < 5ms）。
  3. 渲染： 解析后的输出被渲染到 DOM 中。React 使用虚拟 DOM 差异比较；Vue 和 Svelte 使用 v-html / {@html} 并配合净化后的 HTML。

​
设置 useStream

Markdown 模式使用一个简单的聊天代理，无需特殊配置。将 useStream 与你的代理 URL 和助手 ID 连接起来。 定义一个与你的代理状态模式匹配的 TypeScript 接口，并将其作为类型参数传递给 useStream，以实现对状态值的类型安全访问。在下面的示例中，将 typeof myAgent 替换为你的接口名称： 
import type { BaseMessage } from "@langchain/core/messages";

interface AgentState {
  messages: BaseMessage[];
}

import { useStream } from "@langchain/react";
import { AIMessage, HumanMessage } from "@langchain/core/messages";

const AGENT_URL = "http://localhost:2024";

export function Chat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "simple_agent",
  });

  return (
    <div>
      {stream.messages.map((msg) => {
        if (AIMessage.isInstance(msg)) {
          return <Markdown key={msg.id}>{msg.text}</Markdown>;
        }
        if (HumanMessage.isInstance(msg)) {
          return <p key={msg.id}>{msg.text}</p>;
        }
      })}
    </div>
  );
}

​
选择 Markdown 库

每个框架都有其自然的 Markdown 渲染选择：
框架库输出原因
Reactreact-markdown + remark-gfmReact 元素基于组件，虚拟 DOM 差异比较，无需 dangerouslySetInnerHTML
Vuemarked + dompurify通过 v-html 输出净化后的 HTML轻量、快速，内置 GFM 支持
Sveltemarked + dompurify通过 {@html} 输出净化后的 HTML与 Vue 相同，API 一致
Angularmarked + dompurify通过 [innerHTML] 输出净化后的 HTML与 Vue/Svelte 相同
React 的 react-markdown 直接将 Markdown 转换为 React 元素，因此不需要 HTML 净化。不涉及 dangerouslySetInnerHTML。对于 Vue、Svelte 和 Angular，渲染前务必使用 dompurify 净化解析后的 HTML。

​
构建 Markdown 组件

import ReactMarkdown from "react-markdown";
import remarkGfm from "remark-gfm";

export function Markdown({ children }: { children: string }) {
  return (
    <div className="markdown-content">
      <ReactMarkdown remarkPlugins={[remarkGfm]}>
        {children}
      </ReactMarkdown>
    </div>
  );
}

​
净化 HTML 输出

当将解析后的 Markdown 作为原始 HTML 渲染时（v-html、{@html}、[innerHTML]），必须净化输出以防止跨站脚本攻击（XSS）。LLM 响应可能包含任意文本，包括 Markdown 解析器可能转换为可执行 HTML 的标记。 使用 dompurify 剥离危险元素： 
import DOMPurify from "dompurify";

const safeHtml = DOMPurify.sanitize(rawHtml);
DOMPurify 会移除 <script> 标签、onclick 属性、javascript: URL 和其他 XSS 向量，同时保留安全的 Markdown 输出，如标题、列表、代码块、表格和链接。
React 的 react-markdown 不需要 dompurify，因为它直接生成 React 元素，不涉及原始 HTML 注入。

​
流式传输注意事项

useStream 在每个 token 到达时响应式更新 msg.text。Markdown 组件在每次更新时重新解析。对于典型的聊天消息，这具有良好的性能：
  • marked 解析速度约为 ~1 MB/s。5 KB 消息耗时 < 5ms
  • react-markdown + remark 管道对于聊天长度的内容同样快速
  • 浏览器的布局引擎能高效处理 DOM 更新
对于非常长的响应（> 50 KB），请考虑以下优化：
  • 节流渲染： 使用 requestAnimationFrame 以 60fps 批量更新，而不是在每个 token 时重新渲染。
  • 增量解析： 仅解析新内容并追加到已渲染的缓冲区（高级用法，通常聊天 UI 不需要）。
对于大多数聊天应用，在每个 token 时重新解析完整消息的简单方法已足够。仅在观察到非常长的消息导致滚动卡顿或丢帧时才进行优化。

​
设置 Markdown 内容样式

将样式应用于 .markdown-content 类以控制渲染后 Markdown 的外观。以下是基本样式： 
.markdown-content p {
  margin: 0.4em 0;
}

.markdown-content ul,
.markdown-content ol {
  margin: 0.4em 0;
  padding-left: 1.4em;
}

.markdown-content pre {
  overflow-x: auto;
  border-radius: 0.375rem;
  background: rgba(0, 0, 0, 0.05);
  padding: 0.5rem;
  font-size: 0.75rem;
}

.markdown-content code {
  border-radius: 0.25rem;
  background: rgba(0, 0, 0, 0.08);
  padding: 0.125rem 0.25rem;
  font-size: 0.75rem;
}

.markdown-content blockquote {
  margin: 0.4em 0;
  padding-left: 0.75em;
  border-left: 3px solid currentColor;
  opacity: 0.8;
}

.markdown-content table {
  border-collapse: collapse;
  margin: 0.4em 0;
}

.markdown-content th,
.markdown-content td {
  border: 1px solid #e5e7eb;
  padding: 0.25em 0.5em;
}
为聊天气泡保持 Markdown 样式紧凑。聊天消息比博客文章小，因此使用比典型散文样式表更紧凑的边距和更小的字体大小。

​
最佳实践

  • 始终净化： 当使用 v-html、{@html} 或 [innerHTML] 时，务必通过 dompurify 运行解析后的输出。切勿信任来自 Markdown 解析器（处理 LLM 输出）的原始 HTML。
  • 启用 GFM： GitHub 风格 Markdown 添加了表格、删除线、任务列表和自动链接。这些功能常被 LLM 使用。
  • 处理空内容： 解析前检查空字符串，以避免渲染空容器。
  • 使用 breaks: true： 启用换行符转换，使 LLM 输出中的单个换行符渲染为 <br> 而不是被忽略。LLM 常使用单个换行符进行视觉分隔。
  • 为聊天上下文设置样式： 使用适合聊天气泡的紧凑边距和大小，而非全宽文章布局。
  • 使用丰富内容测试： 使用标题、嵌套列表、长行代码块、宽表格和引用块验证渲染，以捕获溢出或布局问题。
连接这些文档 到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。