Vue Markdown渲染时样式丢失或HTML不解析怎么办？

Question

在 Vue 中使用 `vue-markdown` 或 `marked` 渲染 Markdown 时，常出现样式丢失（如代码块无高亮、标题无层级缩进）或 HTML 标签未解析（如 `
` 被转义为纯文本）的问题。根本原因通常是：① 渲染器默认禁用 HTML 解析（`sanitize: true` 或 `dangerouslySetInnerHTML` 未启用）；② 缺少配套 CSS（如 `github-markdown-css` 未引入）；③ 未集成语法高亮插件（如 `highlight.js` 或 `shiki`）；④ 在 Vue 3 组合式 API 中错误地将 Markdown 字符串直接 `v-html`，却未经 `marked.parse()` 处理。此外，若使用 `vue-markdown-it`，还需确认 `html: true` 选项已开启，且 `linkify`、`typographer` 等扩展配置正确。解决方案包括：启用安全 HTML 渲染、按需引入标准化样式、绑定高亮回调函数，并严格校验渲染流程的执行顺序与上下文（如 SSR 环境需服务端同步支持）。

Answer 1

```html

一、现象层：典型症状与可复现的失败场景

• 代码块渲染为纯灰底无语法高亮（```js 区域未着色）
• 标题（# H1, ## H2）无层级缩进，字号/间距与文档流脱节
• <br />、<hr> 等内联 HTML 标签被原样输出为文本，而非换行或分隔线
• 链接点击无响应，[Vue](https://vuejs.org) 渲染为不可点击纯文字
• 在 Vue 3 的 <script setup> 中直接 v-html="mdText"，页面空白或报错

二、配置层：四大核心配置缺失诊断表

问题类型	对应库	关键配置项	错误默认值	正确设置
HTML 解析禁用	marked	sanitize	true	false 或显式启用 dangerousHTML: true
样式未注入	通用	CSS 资源加载	未 import 'github-markdown-css'	需 @import '~github-markdown-css/github-markdown.css' 并包裹 .markdown-body
代码高亮失效	marked + highlight.js	highlight 回调	未传入高亮函数	需绑定 marked.setOptions({ highlight: (code, lang) => hljs.highlight(code, { language: lang }).value })

三、架构层：Vue 3 组合式 API 渲染流程图

flowchart TD
  A[Markdown 字符串] --> B{是否已解析？}
  B -->|否| C[marked.parseAsync/mdText]
  B -->|是| D[v-html 绑定]
  C --> E[注入 highlight.js 高亮]
  E --> F[包裹 .markdown-body 类]
  F --> G[CSS 变量/字体/间距生效]
  G --> D
  D --> H[DOM 安全插入]

四、集成层：vue-markdown-it 的深度配置范式

当选用 vue-markdown-it 时，仅 <vue-markdown-it :source="md"></vue-markdown-it> 不足以保障功能完备：

• 必须启用 html: true（否则所有 HTML 标签被转义）
• 推荐启用 linkify: true 自动识别 URL 并生成 <a>
• 启用 typographer: true 支持智能引号、破折号等排版增强
• 通过 plugins 注册 markdown-it-container 或 markdown-it-footnote 扩展语义能力
• SSR 场景下需在服务端同步初始化 markdown-it 实例并预载插件

五、工程层：生产就绪的模块化封装方案

建议构建 MarkdownRenderer.vue 组件，内聚以下能力：

1. 响应式监听 props.source，防抖触发解析（避免高频更新卡顿）
2. 内置 useHighlight Composable，自动注册 highlight.js 语言包（按需 import）
3. 支持 slot 注入自定义渲染器（如数学公式用 KaTeX 替代）
4. 提供 onRenderError 事件暴露解析异常（如 YAML front matter 解析失败）
5. 内置 data-md-rendered 属性标记完成状态，便于 E2E 测试断言

六、演进层：从 marked 到 shiki 的现代迁移路径

对比 highlight.js，shiki 提供更精准的语法树解析与主题一致性：

• shiki 基于 TextMate 语法，支持 VS Code 同源主题（如 min-dark）
• 无需客户端运行时高亮，可在构建时静态生成 HTML（SSG 友好）
• Vue 3 中通过 shiki/core + shiki/langs 按语言动态加载
• 配合 vite-plugin-shiki 可实现主题热更新与代码块 SSR 预渲染
• 注意：需禁用 marked 的默认高亮，改由 shiki 的 codeToHtml 替代

```