markstream-vue

环境要求

• 已有一个 Vue 3 / Nuxt / VitePress 前端项目（markstream-vue 只服务 Vue 系框架）
• 本机已安装 Node.js 并可使用 pnpm（README 的安装命令基于 pnpm）
• 需要 Mermaid 图表、KaTeX 公式、代码高亮等能力由该渲染器内置提供

安装与启动步骤

1. 1确认项目环境

   markstream-vue 是 Vue 3 / Nuxt / VitePress 的流式 Markdown 渲染器，React、Svelte、Angular 等请改用同系列兄弟包，不要装这个。

2. 2安装 markstream-vue

   在项目根目录用 pnpm 安装；用 npm 的项目把命令换成 npm install markstream-vue。2.x 是 npm 的 latest 稳定版。

   pnpm add markstream-vue

   复制

3. 3引入组件与样式

   务必同时引入 markstream-vue/index.css，否则渲染样式会缺失。content 传流式文本，final 表示是否已输出完成。

   <script setup lang="ts">
   import MarkdownRender from 'markstream-vue'
   import 'markstream-vue/index.css'
   
   defineProps<{
     content: string
     isDone: boolean
   }>()
   </script>
   
   <template>
     <MarkdownRender mode="chat" :content="content" :final="isDone" />
   </template>

   复制

4. 4锁定 1.x 版本

   如果应用在 2.x 切换期必须留在 1.x，用 @1 安装；1.x 也保留在 npm 的 legacy 标签上，预发布在 legacy-next。

   pnpm add markstream-vue@1

   复制

5. 5SSR 预解析节点

   在服务端或 Worker 里先解析成结构化节点，把 nodes 传给客户端渲染，可避免客户端解析并保持 SSR/水合结果确定。

   // server or worker
   import { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
   
   const md = getMarkdown()
   const nodes = parseMarkdownToStructure('# Hello\n\nThis is parsed once', md)
   // send `nodes` JSON to the client
   
   const nodes = parseMarkdownToStructure(source, md, { final: true })

   复制

6. 6客户端渲染节点

   客户端直接接收服务端传来的 nodes 渲染，不再自行解析 Markdown，适合需要确定性输出的场景。

   <MarkdownRender :nodes="nodesFromServer" />

   复制

关键配置

如何确认成功

页面上出现正确的 Markdown 渲染结果，内容随流式输出逐步更新且无明显抖动，HTML/CSS 样式正常。

常见问题

注意事项

• 2.x 是 npm latest 稳定线，1.x 保留在 legacy 标签、预发布在 legacy-next，跨 2.x 升级可参考官方 1.x→2.0 迁移指南。
• MarkdownRender 自己解析 content 时，parseOptions.streamParse 默认是 true；如需最终内容走常规解析，传 'auto' 或 false。
• 代码块运行时在 2.0 有变化，从 1.x 升级前先看迁移指南再动手。
• 安装命令要按自己项目的包管理器替换，README 同时给出了 pnpm 与 npm 两种写法。