Markstream

简体中文

English

简体中文

English

Appearance

...

按症状排查 ​

还不知道问题出在哪一层？先从下面的症状卡片入手：按你实际看到的现象——样式丢失、图表不渲染、SSR 崩掉、peer 警告——找到对应的卡片，照着“最可能原因”逐条检查。如果所有卡片都对不上，再按本页下方的子系统分层排查。

SSR / 构建报错（Nuxt、hydration、worker）

  • 服务端渲染或构建时 window is not defined
  • 服务端与客户端的 hydration 输出对不上
  • 浏览器专属 peer 在服务端被初始化
Nuxt SSR 指南

另见：排查问题

流式输出时内容跳动 / 闪烁

  • 每个 token 都在 MarkdownRender 里重新解析
  • 没有用 nodes + final 做增量更新
  • 流式过程中一直开着重型渲染器
AI 聊天与流式输出

另见：性能优化

peer 依赖警告（katex、mermaid 等）

  • katex、mermaid 这类可选 peer 没有安装
  • peer 装了，但对应的 CSS 没有导入
  • 安装的版本超出了受支持范围
安装指南

另见：数学公式（KaTeX）

还是没头绪？带上诊断信息再问

复制一份 issue 模板（含环境、症状、复现步骤占位），粘贴到 GitHub issue 后填好，维护者能更快帮你定位。

已经知道是哪个子系统？直接跳转 ​

你看到的问题先看这里然后看
样式错乱、间距不对、Tailwind 抢样式样式错乱？先做这几件事Tailwind 集成与样式顺序
<thinking> 这类可信标签被当成原生 HTML文档站与 VitePress 集成 或 自定义标签与高级组件API 参考
window is not defined 或浏览器专属依赖在 SSR 崩掉排查问题Nuxt SSR
Mermaid、KaTeX、stream-diffs、D2 没有渲染出来安装渲染器与节点组件
聊天输出卡、频繁重解析、长内容越来越慢AI 聊天与流式输出性能
内置节点形态不适合业务覆盖内置组件渲染器与节点组件

1. 样式看起来不对 ​

常见现象：

  • 段落、表格、列表间距很奇怪
  • 代码块、图片、引用像是没吃到样式
  • Tailwind / UnoCSS 把渲染器样式盖掉了

按这个顺序检查：

  1. reset 是否在 markstream-vue/index.css 之前导入
  2. 用了 Tailwind / UnoCSS 时，是否使用 @import '...' layer(components)
  3. 如果启用了数学公式，是否导入了 katex/dist/katex.min.css
  4. 如果渲染器嵌在大系统里，是否用 custom-id 做了作用域隔离

先从 CSS 清单开始： 排查问题

2. 自定义标签或自定义组件没有生效 ​

常见现象：

  • <thinking> 被原样输出成 HTML
  • 自定义 Vue 组件一直没有渲染
  • 某个页面能用，换个地方就失效

按这个顺序检查：

  1. 标签是否加入了 custom-html-tags
  2. 是否用 setCustomComponents(customId, mapping) 注册了映射
  3. 页面渲染时是否传了匹配的 custom-id
  4. 如果你在 VitePress 里，注册逻辑是否放在 enhanceApp

最适合继续看的路径：

3. SSR 报错或浏览器专属依赖崩掉 ​

常见现象：

  • window is not defined
  • Mermaid / stream-diffs 本地能跑，但 SSR 环境报错
  • 服务端和客户端 hydration 对不上

按这个顺序检查：

  1. 先确认出问题的 peer 是否本来就只能在浏览器里运行
  2. 把这部分初始化放到 client-only 边界之后
  3. 让基础 MarkdownRender 仍然走服务端安全路径

最适合继续看的路径：

4. 重型能力没有渲染出来 ​

常见现象：

  • Mermaid fence 只显示源码
  • 数学公式是空白
  • stream-diffs 增强代码块是空的（未安装 stream-diffs 时回退为普通 <pre>）
  • D2 退回成原始文本

这类问题多数不是 parser 出错，而是下面几类原因：

  • peer 依赖没装
  • 必需 CSS 没导，尤其是 KaTeX
  • SSR 或 worker 边界处理不对

先从 安装 开始，再去 渲染器与节点组件 对照各组件的注意事项。

5. 流式输出或聊天界面越来越慢 ​

常见现象：

  • 每来一个 token 页面就明显抖动
  • 长聊天记录越来越重
  • 每次更新都在整篇重解析 Markdown

这类问题通常不是“调个样式”能解决的，而是接法需要调整：

  • 把解析移到 MarkdownRender 外部
  • 改用 nodes + final
  • 重型 peers 按需启用，不要默认全开

最适合继续看的路径： AI 聊天与流式输出，再配合 性能

6. 还是拿不准？ ​

如果你还无法判断是哪一层的问题：

  1. 先在 playground 里用最小 Markdown 示例复现
  2. 暂时去掉可选 peers，把问题缩小
  3. 对照最接近的场景页： 文档站与 VitePress 集成、AI 聊天与流式输出、使用与流式渲染

如果最后看起来确实像 bug，再准备这些信息：

  • 最小 Markdown 示例
  • 框架 / 运行时信息
  • 是否用了 Tailwind、UnoCSS、SSR
  • 当前安装了哪些可选 peers

页面顶部的“复制 issue 模板”按钮已经把这些占位整理好了，直接复制粘贴即可。然后再使用 排查问题 里的测试页或 issue 链接。