boos
e0a5f57793
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
128 lines
4.9 KiB
Markdown
128 lines
4.9 KiB
Markdown
---
|
|
description: 按症状定位 markstream-vue 的 CSS 顺序、peer 依赖、SSR、自定义标签与流式性能问题。
|
|
---
|
|
|
|
# 按症状排查
|
|
|
|
当你知道“哪里不对”，但还不确定问题到底是 CSS 顺序、peer 依赖、SSR 边界、自定义标签接法，还是渲染器选择不当时，就先从这页开始。
|
|
|
|
如果你已经明确知道是哪一层出了问题，也可以直接跳到每个分支下面链接过去的深度页面。
|
|
|
|
## 先按你看到的现象分流
|
|
|
|
| 你看到的问题 | 先看这里 | 然后看 |
|
|
| --- | --- | --- |
|
|
| 样式错乱、间距不对、Tailwind 抢样式 | [样式错乱？先做这几件事](/zh/guide/troubleshooting#css-looks-wrong-start-here) | [Tailwind 集成与样式顺序](/zh/guide/tailwind) |
|
|
| `<thinking>` 这类可信标签被当成原生 HTML | [文档站与 VitePress 集成](/zh/guide/vitepress-docs-integration) 或 [自定义标签与高级组件](/zh/guide/custom-components) | [API 参考](/zh/guide/api) |
|
|
| `window is not defined` 或浏览器专属依赖在 SSR 崩掉 | [排查问题](/zh/guide/troubleshooting) | [Nuxt SSR](/zh/nuxt-ssr) |
|
|
| Mermaid、KaTeX、Monaco、D2 没有渲染出来 | [安装](/zh/guide/installation) | [渲染器与节点组件](/zh/guide/components) |
|
|
| 聊天输出卡、频繁重解析、长内容越来越慢 | [AI 聊天与流式输出](/zh/guide/ai-chat-streaming) | [性能](/zh/guide/performance) |
|
|
| 内置节点形态不适合业务 | [覆盖内置组件](/zh/guide/component-overrides) | [渲染器与节点组件](/zh/guide/components) |
|
|
|
|
## 1. 样式看起来不对
|
|
|
|
常见现象：
|
|
|
|
- 段落、表格、列表间距很奇怪
|
|
- 代码块、图片、引用像是没吃到样式
|
|
- Tailwind / UnoCSS 把渲染器样式盖掉了
|
|
|
|
按这个顺序检查：
|
|
|
|
1. reset 是否在 `markstream-vue/index.css` 之前导入
|
|
2. 用了 Tailwind / UnoCSS 时，CSS 是否放在 `@layer components`
|
|
3. 如果启用了数学公式，是否导入了 `katex/dist/katex.min.css`
|
|
4. 如果渲染器嵌在大系统里，是否用 `custom-id` 做了作用域隔离
|
|
|
|
先从 CSS 清单开始： [排查问题](/zh/guide/troubleshooting#css-looks-wrong-start-here)
|
|
|
|
## 2. 自定义标签或自定义组件没有生效
|
|
|
|
常见现象：
|
|
|
|
- `<thinking>` 被原样输出成 HTML
|
|
- 自定义 Vue 组件一直没有渲染
|
|
- 某个页面能用，换个地方就失效
|
|
|
|
按这个顺序检查：
|
|
|
|
1. 标签是否加入了 `custom-html-tags`
|
|
2. 是否用 `setCustomComponents(customId, mapping)` 注册了映射
|
|
3. 页面渲染时是否传了匹配的 `custom-id`
|
|
4. 如果你在 VitePress 里，注册逻辑是否放在 `enhanceApp`
|
|
|
|
最适合继续看的路径：
|
|
|
|
- 文档站 / 主题场景： [文档站与 VitePress 集成](/zh/guide/vitepress-docs-integration)
|
|
- 应用内自定义标签： [自定义标签与高级组件](/zh/guide/custom-components)
|
|
|
|
## 3. SSR 报错或浏览器专属依赖崩掉
|
|
|
|
常见现象：
|
|
|
|
- `window is not defined`
|
|
- Mermaid / Monaco 本地能跑，但 SSR 环境报错
|
|
- 服务端和客户端 hydration 对不上
|
|
|
|
按这个顺序检查：
|
|
|
|
1. 先确认出问题的 peer 是否本来就只能在浏览器里运行
|
|
2. 把这部分初始化放到 client-only 边界之后
|
|
3. 让基础 `MarkdownRender` 仍然走服务端安全路径
|
|
|
|
最适合继续看的路径：
|
|
|
|
- 通用检查项： [排查问题](/zh/guide/troubleshooting)
|
|
- Nuxt 专用规则： [Nuxt SSR](/zh/nuxt-ssr)
|
|
|
|
## 4. 重型能力没有渲染出来
|
|
|
|
常见现象：
|
|
|
|
- Mermaid fence 只显示源码
|
|
- 数学公式是空白
|
|
- Monaco 代码块是空的
|
|
- D2 退回成原始文本
|
|
|
|
这类问题多数不是 parser 出错，而是下面几类原因：
|
|
|
|
- peer 依赖没装
|
|
- 必需 CSS 没导，尤其是 KaTeX
|
|
- SSR 或 worker 边界处理不对
|
|
|
|
先从 [安装](/zh/guide/installation) 开始，再去 [渲染器与节点组件](/zh/guide/components) 对照各组件的注意事项。
|
|
|
|
## 5. 流式输出或聊天界面越来越慢
|
|
|
|
常见现象：
|
|
|
|
- 每来一个 token 页面就明显抖动
|
|
- 长聊天记录越来越重
|
|
- 每次更新都在整篇重解析 Markdown
|
|
|
|
这类问题通常不是“调个样式”能解决的，而是接法需要调整：
|
|
|
|
- 把解析移到 `MarkdownRender` 外部
|
|
- 改用 `nodes` + `final`
|
|
- 重型 peers 按需启用，不要默认全开
|
|
|
|
最适合继续看的路径： [AI 聊天与流式输出](/zh/guide/ai-chat-streaming)，再配合 [性能](/zh/guide/performance)
|
|
|
|
## 6. 还是拿不准？
|
|
|
|
如果你还无法判断是哪一层的问题：
|
|
|
|
1. 先在 playground 里用最小 Markdown 示例复现
|
|
2. 暂时去掉可选 peers，把问题缩小
|
|
3. 对照最接近的场景页：
|
|
`文档站与 VitePress 集成`、`AI 聊天与流式输出`、`使用与流式渲染`
|
|
|
|
如果最后看起来确实像 bug，再准备这些信息：
|
|
|
|
- 最小 Markdown 示例
|
|
- 框架 / 运行时信息
|
|
- 是否用了 Tailwind、UnoCSS、SSR
|
|
- 当前安装了哪些可选 peers
|
|
|
|
然后再使用 [排查问题](/zh/guide/troubleshooting) 里的测试页或 issue 链接。
|