streamdown

Streamdown

针对流式传输优化的 React Markdown 渲染器。可直接替代 react-markdown，内置流式传输支持、安全功能和交互式控件。

快速设置

1. 安装

npm install streamdown

可选插件（仅安装所需插件）：

npm install @streamdown/code @streamdown/mermaid @streamdown/math @streamdown/cjk

2. 配置 Tailwind CSS（必需）

这是最容易遗漏的一步。 Streamdown 使用 Tailwind 进行样式设置，必须扫描 dist 文件。

Tailwind v4 — 添加到 globals.css：

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

仅为已安装的包添加 @source 插件行（省略未安装的插件可避免 Tailwind 报错）。确切路径请参阅插件页面：

• Code：@source "../node_modules/@streamdown/code/dist/*.js";
• CJK：@source "../node_modules/@streamdown/cjk/dist/*.js";
• Math：@source "../node_modules/@streamdown/math/dist/*.js";
• Mermaid：@source "../node_modules/@streamdown/mermaid/dist/*.js";

Tailwind v3 — 添加到 tailwind.config.js：

module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/streamdown/dist/*.js",
  ],
};

3. 基本用法

import { Streamdown } from 'streamdown';

<Streamdown>{markdown}</Streamdown>

4. 配合 AI 流式传输使用（Vercel AI SDK）

'use client';
import { useChat } from '@ai-sdk/react';
import { Streamdown } from 'streamdown';
import { code } from '@streamdown/code';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();

  return (
    <>
      {messages.map((msg, i) => (
        <Streamdown
          key={msg.id}
          plugins={{ code }}
          caret="block"
          isAnimating={isLoading && i === messages.length - 1 && msg.role === 'assistant'}
        >
          {msg.content}
        </Streamdown>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} disabled={isLoading} />
      </form>
    </>
  );
}

5. 静态模式（博客、文档）

<Streamdown mode="static" plugins={{ code }}>
  {content}
</Streamdown>

主要属性

属性	类型	默认值	用途
children	string	—	Markdown 内容
mode	"streaming" | "static"	"streaming"	渲染模式
plugins	{ code?, mermaid?, math?, cjk? }	—	功能插件
isAnimating	boolean	false	流式传输指示器
caret	"block" | "circle"	—	光标样式
components	Components	—	自定义元素覆盖项
controls	boolean | object	true	交互式按钮；download: { filename } 可设置自定义下载文件名
linkSafety	LinkSafetyConfig	{ enabled: true }	链接确认弹窗
shikiTheme	[light, dark]	['github-light', 'github-dark']	代码主题
className	string	—	容器类
allowedElements	string[]	all	允许的标签名称
disallowedElements	string[]	[]	禁止的标签名称
allowElement	AllowElement	—	自定义元素过滤器
unwrapDisallowed	boolean	false	保留被禁止元素的子元素
skipHtml	boolean	false	忽略原始 HTML
urlTransform	UrlTransform	defaultUrlTransform	转换／净化 URL

完整 API 参考请参阅 references/api.md。

插件速查

插件	包	用途
Code	@streamdown/code	语法高亮（Shiki，支持 200 多种语言）
Mermaid	@streamdown/mermaid	图表（流程图、时序图等）
Math	@streamdown/math	通过 KaTeX 渲染 LaTeX（需要导入 CSS）
CJK	@streamdown/cjk	中文／日文／韩文文本支持

Math 需要 CSS：

import 'katex/dist/katex.min.css';

插件配置详情请参阅 references/plugins.md。

参考资料

如需深入了解实现细节，请参阅：

• references/api.md — 完整的属性、类型和接口
• references/plugins.md — 插件设置、配置和自定义
• references/styling.md — CSS 变量、数据属性、自定义组件、主题示例
• references/security.md — 安全加固、链接安全、自定义 HTML 标签、生产环境配置
• references/features.md — 光标、remend、静态模式、控件、GFM、记忆化、故障排查

示例配置

从 assets/examples/ 复制并进行调整：

• basic-streaming.tsx — 使用 Vercel AI SDK 的极简 AI 聊天
• with-caret.tsx — 带块状光标的流式输出
• full-featured.tsx — 包含所有插件、光标、链接安全机制和控件
• static-mode.tsx — 博客／文档渲染
• custom-security.tsx — 针对 AI 内容的严格安全设置

常见问题

1. 缺少 Tailwind 样式 — 为 node_modules/streamdown/dist/*.js 添加 @source 指令或 content 条目
2. 数学公式无法渲染 — 导入 katex/dist/katex.min.css
3. 未显示光标 — 必须同时设置 caret 属性和 isAnimating={true}
4. 流式输出期间的复制按钮 — 设置 isAnimating={true} 时会自动禁用
5. 出现链接安全弹窗 — 默认启用；使用 linkSafety={{ enabled: false }} 禁用
6. Next.js 中的 Shiki 警告 — 显式安装 shiki，并将其添加到 transpilePackages
7. allowedTags 不起作用 — 仅适用于默认 rehype 插件
8. 数学公式使用 $$ 而不是 $ — 默认禁用单美元符号，以避免与货币符号冲突