故障排查

缩减复现时保留完整源文本、包版本、配置与框架环境。

没有样式或数学排版异常

检查适配器 CSS 与导入顺序。React 使用 typography 样式，Vue 使用 styles.css，Mantine 在 Mantine 样式之后导入集成样式。KaTeX CSS 单独导入，详见快速开始。

请求结束后还在逐字显示

数据源结束时，已收到的文字可能还没显示完。请观察平滑流式 Hook 或组合式函数返回的状态。取消生成还需要应用中止网络请求，只设置 streaming=false 不会取消请求。见流式输入。

引用仍是字面文本或脚注缺失

先用一个渲染器传入完整文档。确需拆分时检查文档容器、共享显式 ID、稳定 key 和排序。React 保持 blockMemo 开启。服务端的跨片段贡献尚不可用，孤立定义也受策略影响。

URL 被移除

清洗器可能先拒绝协议，最终 urlTransform 也可能拒绝 URL。仅放宽其中一个步骤并不足够。自定义组件输出需自行执行策略。

光标隐藏

代码、数学、图片等不支持的尾部，以及没有本地可见目标的引用定义，会隐藏测量光标。React 需要显式传光标组件，Vue 默认开启。空内容应由应用显示等待占位。

水合不一致或更新缓慢

保持服务端和首帧客户端的内容、身份及配置一致。性能问题要分别测量预处理、未冻结尾部、框架转换、高亮、图表和布局，不要把增量解析理解为恒定更新成本。

深层 HTML 显示为文本

仅 EngineRawHtmlDepthError 触发专用文本降级，下一帧恢复尝试正常解析。任意插件异常不在此兜底范围。

Vue 平滑包装器不再更新

传入读取实时 .value 的 getter，不要捕获初始化时的配置快照。渲染函数读取返回 computed ref 的 .value，模板可解包顶层 ref。见 Vue 流式指南。