03工程笔记

2026 · 02 · 28

9 分钟

基于 html-react-parser 的 Markdown 渲染管线改造

告别 dangerouslySetInnerHTML，用标签处理器映射表 + html-react-parser 构建一套可扩展的 Markdown → React 组件渲染管线。

背景：原有方案的局限

在一个 Next.js + Markdown 驱动的博客 / 作品展示站点中，内容渲染通常经过这样一条链路：

text

Markdown 文件 → marked.parse() → HTML 字符串 → dangerouslySetInnerHTML → 页面

这条链路简单直接，但存在几个明显的痛点：

无法插入 React 组件。代码块高亮、Mermaid 图表、链接预览等增强功能需要 React 组件渲染，dangerouslySetInnerHTML 无法做到。
扩展困难。原有方案用正则把 HTML 拆分为"普通片段"和"代码块"，手动调度渲染。每新增一种特殊标签就要改正则和渲染分支，维护成本高。
不安全。dangerouslySetInnerHTML 直接注入未经过滤的 HTML，存在 XSS 风险隐患。

我们需要的是一套"标签 → 组件"的声明式映射机制：遇到 <pre><code> 就渲染 CodeBlock，遇到外部 <a> 就渲染 LinkPreview，未来新增 <video-info> 就渲染 VideoCard——而核心解析引擎不需要改动。

设计思路

灵感来自 AI 对话产品中的内容渲染模式。核心流程如下：

加载中…

关键设计决策：

标签处理器映射表：一个 Record<string, TagHandler> 对象，键是 HTML 标签名，值是处理函数。新增标签支持只需加一行。
html-react-parser：它遍历 HTML 的每个 DOM 节点，对每个节点调用我们的 replace 回调。如果回调返回 React 元素就替换，返回 undefined 就保留原节点。
customHandlers prop：支持页面级覆盖或扩展，不同页面可以有不同的标签行为。

实现

1. 安装依赖

bash

npm install html-react-parser

html-react-parser 底层使用 htmlparser2（与 cheerio 同源），解析速度极快，支持 SSR 和 CSR。

2. 核心组件 ProseContent

完整实现位于 src/components/frontend/ProseContent.tsx：

tsx

"use client"

import { useMemo } from "react"
import parse, {
  domToReact,
  type HTMLReactParserOptions,
  Element,
  type DOMNode,
} from "html-react-parser"
import { CodeBlock } from "@/components/ui/code-block"
import { MermaidBlock } from "@/components/frontend/MermaidBlock"
import { LinkPreview } from "@/components/ui/link-preview"

2.1 类型定义

tsx

// 与 html-react-parser 的 replace 签名对齐
type ReplaceResult = React.JSX.Element | string | null | boolean | object | void

// 标签处理器：接收 DOM 元素，返回 React 节点或 null（保持原样）
type TagHandler = (node: Element, options: HTMLReactParserOptions) => ReplaceResult

踩坑提醒：replace 回调的返回类型不是 React.ReactNode！React.ReactNode 包含 number、bigint、Promise 等类型，而 replace 只接受 JSX.Element | string | null | boolean | object | void。如果用 React.ReactNode 会报 TS 类型错误。

2.2 代码块处理器

tsx

function handlePreCodeBlock(node: Element): ReplaceResult {
  const codeEl = node.children?.find(
    (child): child is Element =>
      child instanceof Element && child.name === "code"
  )
  if (!codeEl) return null

  const classAttr = codeEl.attribs?.class || ""
  const langMatch = classAttr.match(/language-(\S+)/)
  const language = langMatch ? langMatch[1] : "text"

  const rawCode = extractText(codeEl)
  const code = decodeHtmlEntities(rawCode).trim()

  if (language === "mermaid") {
    return (
      <div className="not-prose my-6">
        <MermaidBlock code={code} />
      </div>
    )
  }

  return (
    <div className="not-prose my-6">
      <CodeBlock language={language} code={code} filename="" />
    </div>
  )
}

这个处理器做了三件事：

从 <pre> 中找到 <code> 子元素
从 class="language-xxx" 中提取语言标识
根据语言分流到 MermaidBlock（图表）或 CodeBlock（语法高亮）

2.3 链接处理器

tsx

function handleLink(
  node: Element,
  options: HTMLReactParserOptions
): ReplaceResult {
  const href = node.attribs?.href
  if (!href) return null

  const isExternal =
    href.startsWith("http://") || href.startsWith("https://")
  if (!isExternal) return null

  const children = domToReact(node.children as DOMNode[], options)

  return <LinkPreview url={href}>{children}</LinkPreview>
}

只对外部链接启用 LinkPreview（hover 时展示目标页截图预览），内部链接保持原样。注意 domToReact 的使用——它将子节点递归转为 React 元素，保证链接内的加粗、图片等嵌套内容正常渲染。

2.4 标签处理器映射表

tsx

const TAG_HANDLERS: Record<string, TagHandler> = {
  pre: (node) => handlePreCodeBlock(node),
  a:   (node, opts) => handleLink(node, opts),
  img: (node) => handleImage(node), // 预留扩展点
}

这就是整套方案的"注册中心"。扩展时只需在此添加一行，无需改动解析引擎。

2.5 解析引擎

tsx

export function ProseContent({
  html,
  className,
  customHandlers,
}: ProseContentProps) {
  const parsedContent = useMemo(() => {
    const mergedHandlers = { ...TAG_HANDLERS, ...customHandlers }

    const options: HTMLReactParserOptions = {
      replace: (domNode) => {
        if (!(domNode instanceof Element)) return

        const handler = mergedHandlers[domNode.name]
        if (handler) {
          const result = handler(domNode, options)
          if (result !== null) return result
        }
      },
    }

    return parse(html, options)
  }, [html, customHandlers])

  return <div className={className}>{parsedContent}</div>
}

核心逻辑只有 5 行：

合并内置和自定义处理器
遍历每个 DOM 节点，按标签名查找处理器
有处理器就执行替换，没有就保留原节点

useMemo 确保只在 html 或 customHandlers 变化时重新解析。

3. 页面接入

博客详情页

tsx

// src/app/(frontend)/blog/[slug]/page.tsx
import { ProseContent } from "@/components/frontend/ProseContent"

// 在 JSX 中：
{contentHtml ? (
  <ProseContent html={contentHtml} />
) : (
  content.split("\n").map((line, i) => (
    <p key={i}>{line || "\u00A0"}</p>
  ))
)}

作品详情页

tsx

// src/app/(frontend)/works/[slug]/page.tsx
import { ProseContent } from "@/components/frontend/ProseContent"

// 替换原来的 dangerouslySetInnerHTML：
{contentHtml ? (
  <ProseContent html={contentHtml} />
) : (
  content.split("\n").map((line, i) => (
    <p key={i}>{line || "\u00A0"}</p>
  ))
)}

作品详情页之前只能渲染纯 HTML，现在也自动获得了代码高亮、Mermaid 图表、链接预览等全部能力。

4. 工具函数

tsx

/** 递归提取 DOM 元素中的纯文本 */
function extractText(el: Element): string {
  let text = ""
  for (const child of el.children ?? []) {
    if (child.type === "text") {
      text += (child as unknown as { data: string }).data
    } else if (child instanceof Element) {
      text += extractText(child)
    }
  }
  return text
}

/** 反转义 marked 输出的 HTML 实体 */
function decodeHtmlEntities(str: string): string {
  return str
    .replace(/&lt;/g, "<")
    .replace(/&gt;/g, ">")
    .replace(/&amp;/g, "&")
    .replace(/&quot;/g, '"')
    .replace(/&#39;/g, "'")
}

extractText 递归收集文本节点内容，decodeHtmlEntities 反转义 marked 输出中的 HTML 实体。两者配合从 <code> 元素中还原出原始代码文本。

改造前后对比

旧方案（ProseCodeBlock）

text

HTML 字符串
  ↓ 正则匹配 <pre><code>
  ↓ 手动拆分为 segments[]
  ├── type: "code" → CodeBlock / MermaidBlock
  └── type: "html" → dangerouslySetInnerHTML

问题：只能处理代码块这一种标签。新增其他特殊标签需要增加正则和分支逻辑。

新方案（ProseContent）

text

HTML 字符串
  ↓ html-react-parser 遍历 DOM 树
  ↓ 对每个节点查询 TAG_HANDLERS 映射表
  ├── 命中 → 返回 React 组件
  └── 未命中 → 保留原节点

优势：

维度	旧方案	新方案
扩展性	改正则 + 改渲染逻辑	映射表加一行
支持标签数	仅 `<pre><code>`	任意标签
嵌套处理	不支持	`domToReact` 递归处理
dangerouslySetInnerHTML	大量使用	仅 parser 内部安全处理
页面级定制	不支持	`customHandlers` prop

扩展示例

假设未来需要在 Markdown 中嵌入视频卡片，只需：

1. 创建处理函数

tsx

function handleVideoInfo(node: Element): ReplaceResult {
  const rawJson = extractText(node)
  try {
    const data = JSON.parse(rawJson)
    return <ContentVideo content={data} />
  } catch {
    return null
  }
}

2. 注册到映射表

tsx

const TAG_HANDLERS: Record<string, TagHandler> = {
  pre:          (node) => handlePreCodeBlock(node),
  a:            (node, opts) => handleLink(node, opts),
  img:          (node) => handleImage(node),
  'video-info': (node) => handleVideoInfo(node), // 新增
}

3. 在 Markdown 中使用

html

这是一段介绍文字。

<video-info>{"title":"演示视频","url":"https://example.com/video.mp4"}</video-info>

继续其他内容。

html-react-parser 会自动将 <video-info> 标签路由到我们的处理函数，无需修改任何解析逻辑。

或者，你也可以只在某个特定页面启用：

tsx

<ProseContent
  html={contentHtml}
  customHandlers={{
    'video-info': (node) => handleVideoInfo(node),
  }}
/>

总结

这次改造的核心思想是将 HTML 标签与 React 组件的映射关系从"硬编码在渲染逻辑中"提升为"声明式的配置表"。

实际变更非常小：新增 1 个文件（ProseContent.tsx），修改 2 个页面的 import 和 JSX 引用。但架构上从"只能处理代码块"变成了"可处理任意自定义标签"，为未来的内容增强（实体卡片、广告组件、交互式组件等）奠定了基础。

从停机部署到零停机：蓝绿部署实践→