Streamdown：Vercel 开源的 AI 流式 Markdown 渲染库

本文介绍 Streamdown，一个由 Vercel 开源的 React Markdown 渲染库，专为 AI 流式输出场景设计。它可以完美替代 react-markdown，在流式 token 输出过程中也能正确渲染未完成的 Markdown 结构。

项目简介

Streamdown 是由 Vercel 团队开发并维护的开源项目，主要用 TypeScript 编写。截至目前，该项目在 GitHub 上已获得 5200+ stars。它内置于 AI SDK Elements 的 Message 组件，也可以单独安装使用。

在 AI 应用开发中，流式输出是标配体验，但普通的 Markdown 渲染库并不擅长处理「残缺」内容——比如代码块还没闭合、表格行还没写完。Streamdown 针对这一场景做了专项优化。

核心特性

Drop-in 替换：API 与 react-markdown 完全兼容，几乎零迁移成本
流式优化：专为逐 token 渲染设计，处理不完整 Markdown 不会报错或闪烁
未终止块解析：基于 remend 构建，流式过程中代码块、表格等结构提前正确展示
GitHub Flavored Markdown：支持表格、任务列表、删除线
数学公式：通过 KaTeX 渲染 LaTeX 公式
Mermaid 图表：代码块中的 Mermaid 语法可一键渲染为流程图
代码高亮：集成 Shiki，支持多语言语法高亮
安全优先：使用 rehype-harden 防止 XSS 注入
性能优化：Memoized 渲染，避免流式过程中不必要的重绘

技术栈

TypeScript — 主要开发语言
React — 渲染层
remend — 流式 Markdown 解析核心
Shiki — 代码语法高亮
KaTeX — 数学公式渲染
rehype-harden — 安全渲染
Tailwind CSS + shadcn/ui — 样式系统

安装

bash

npm i streamdown

安装完成后，在 Tailwind globals.css 中添加 source 路径，让 Tailwind 能扫描到 Streamdown 使用的工具类：

css

@source "../node_modules/streamdown/dist/*.js";

路径需相对于你的 CSS 文件指向 node_modules。在标准 Next.js 项目中（globals.css 位于 app/ 目录），上面的默认路径即可直接使用。

Monorepo 项目配置

如果项目是 monorepo（npm workspaces、Turbo、pnpm 等），依赖通常被提升到根目录的 node_modules，需要相应调整路径：

css

/* apps/web/app/globals.css → 向上 3 级到达根 node_modules */
@source "../../../node_modules/streamdown/dist/*.js";

CSS 变量配置

Streamdown 基于 shadcn/ui 的设计系统，依赖 CSS 自定义属性。如果项目已使用 shadcn/ui，无需额外配置；否则需在全局 CSS 中添加以下最小变量集：

css

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --border: oklch(0.922 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --border: oklch(0.269 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --radius: 0.625rem;
}

快速开始

结合 Vercel AI SDK 使用的完整示例：

tsx

import { useChat } from "@ai-sdk/react";
import { Streamdown } from "streamdown";
import { code } from "@streamdown/code";
import { mermaid } from "@streamdown/mermaid";
import { math } from "@streamdown/math";
import "katex/dist/katex.min.css";
import "streamdown/styles.css";

export default function Chat() {
  const { messages, status } = useChat();

  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          {message.role === 'user' ? 'User: ' : 'AI: '}
          {message.parts.map((part, index) =>
            part.type === 'text' ? (
              <Streamdown
                key={index}
                animated
                plugins={{ code, mermaid, math }}
                isAnimating={status === 'streaming'}
              >
                {part.text}
              </Streamdown>
            ) : null,
          )}
        </div>
      ))}
    </div>
  );
}

animated 属性开启流式动画效果，isAnimating 接收当前是否正在流式输出的状态，确保动画与 token 生成同步。

插件系统

Streamdown 通过插件扩展功能，按需安装：

插件	包名	功能
代码高亮	`@streamdown/code`	Shiki 语法高亮
数学公式	`@streamdown/math`	KaTeX LaTeX 渲染
Mermaid	`@streamdown/mermaid`	流程图、时序图渲染
CJK	`@streamdown/cjk`	中日韩文字优化排版

每个插件安装后，需在 globals.css 中添加对应的 @source 路径：

css

@source "../node_modules/@streamdown/code/dist/*.js";

与 react-markdown 对比

特性	react-markdown	streamdown
流式输出支持	❌ 不稳定	✅ 专项优化
未完成块处理	❌ 报错/闪烁	✅ 优雅降级
插件系统	remark/rehype 生态	独立插件体系
代码高亮	需自行配置	内置 Shiki
Mermaid 支持	需自行配置	官方插件
API 兼容性	—	Drop-in 替换

项目链接

GitHub 仓库：vercel/streamdown
官方文档：streamdown.ai/docs
npm 包：npmjs.com/package/streamdown
AI SDK Elements：ai-sdk.dev/elements