在 React 和 Vue 项目中集成 marked.js 的正确方式与注意事项

在现代前端工程中，将 Markdown 文本转换为富文本视图是内容系统、文档工具及 AI 交互界面的基础需求。marked.js 凭借轻量、解析速度极快和扩展性良好的特点，成为了开发者的常见选择。然而，在 React 和 Vue 项目中集成 marked.js 并非单纯调用一次解析函数那么简单。若缺乏规范的工程链路，极易引发跨站脚本攻击（XSS）、响应式组件频繁无序重绘、服务端水合失败以及样式作用域丢失等严重问题。本文将详细讲解在 React 与 Vue 3 环境中集成 marked.js 的标准架构、防御方案与实现细节。

一、为什么必须建立独立的安全解析流水线

在深入代码实现前，必须理清 marked.js 的定位与职责边界。marked.js 的核心功能是将符合 CommonMark 或 GFM 规范的 Markdown 字符序列转换为等价的 HTML 字符串。它是一个纯粹的高性能编译器，并不负责浏览器环境下的运行时安全检测。

过去部分开发者依赖 marked.js 的历史配置项（如 sanitize: true）试图自动剔除危险代码。但在 marked.js 现代版本中，该项已被官方明确弃用并彻底废除。原因非常明确：基于简单正则过滤 HTML 标签的方案无法应对复杂的 XSS 攻击向量（如畸形嵌套、特殊编码及伪协议绕过），正规的做法必须交由专门维护白名单与 DOM 树的工业级消毒工具处理。

因此，正规的集成范式必须是一条三段式单向数据流：首先由 marked.js 负责解析语法，随后通过 DOMPurify 进行全量安全消毒，最后才交由前端框架的底层 HTML 接口挂载渲染。

二、标准依赖配置与跨环境准备

在 React 或 Vue 项目中，集成 marked.js 和 DOMPurify 需要安装两个核心库及其在 TypeScript 环境下的类型声明定义：

# 核心运行时依赖
npm install marked dompurify

# TypeScript 开发环境类型支持
npm install -D @types/dompurify

为了保证整个团队或项目中解析逻辑与安全策略的一致性，应当在工具库（如 src/utils/markdown.ts）中封装一个专用的解析模块：

// src/utils/markdown.ts
import { marked } from 'marked';
import DOMPurify from 'dompurify';

// 1. 全局配置 marked 规则
marked.setOptions({
  gfm: true,        // 启用 GitHub Flavored Markdown 规范
  breaks: true      // 启用软换行回车转为 <br>
});

// 2. 自定义 Renderer：针对链接增加安全属性
const renderer = new marked.Renderer();
renderer.link = ({ href, title, text }) => {
  const titleAttr = title ? ` title="${title}"` : '';
  // 外部链接一律补充 noopener noreferrer 并新窗口打开
  return `<a href="${href}"${titleAttr} target="_blank" rel="noopener noreferrer">${text}</a>`;
};

marked.use({ renderer });

// 3. 封装统一的输出函数
export function renderSafeMarkdown(content: string): string {
  if (!content) return '';
  // 同步解析 markdown 为 html
  const rawHtml = marked.parse(content, { async: false }) as string;
  // 严格执行 DOMPurify 清洗，允许 target 属性保留
  return DOMPurify.sanitize(rawHtml, {
    ADD_ATTR: ['target']
  });
}

三、在 React 项目中的正确集成方式

在 React 中，将 HTML 字符串注入到 DOM 树必须通过 dangerouslySetInnerHTML 属性。许多开发者常犯的一个严重性能错误是：直接在 JSX 的返回结构中调用解析函数：

// ❌ 错误示范：每次组件重新渲染都会执行昂贵的解析计算
function BadMarkdownViewer({ text }: { text: string }) {
  return <div dangerouslySetInnerHTML={{ __html: renderSafeMarkdown(text) }} />;
}

由于 React 的渲染机制在父组件状态变化或自身不相关 state 变化时都会触发重新计算，直接在函数体或 JSX 中调用 marked.parse 会使 CPU 重复解析相同的长文本，导致卡顿与掉帧。

正确的做法是使用 useMemo 建立以 Markdown 内容为依赖项的记忆缓存：

// src/components/MarkdownViewer.tsx
import React, { useMemo } from 'react';
import { renderSafeMarkdown } from '../utils/markdown';
import './markdown.css'; // 导入排版样式（如 github-markdown-css）

interface MarkdownViewerProps {
  content: string;
  className?: string;
}

export const MarkdownViewer: React.FC<MarkdownViewerProps> = ({ content, className = '' }) => {
  // 仅在 content 发生实质变更时重新执行解析与消毒
  const sanitizedHtml = useMemo(() => {
    return renderSafeMarkdown(content);
  }, [content]);

  return (
    <article 
      className={`markdown-body ${className}`}
      dangerouslySetInnerHTML={{ __html: sanitizedHtml }}
    />
  );
};

如果应用涉及从后端流式（Streaming）接收 Markdown（例如接入大语言模型的流式打字输出），由于 content 会频繁更新（每秒数十次），此时应当引入防抖（Debounce）或节流（Throttle）机制，或者使用 requestAnimationFrame 降低解析频率，避免渲染主线程处于长任务（Long Task）阻塞状态。

四、在 Vue 3 项目中的正确集成方式

Vue 3 推荐使用 Composition API（<script setup>）。在模板中，注入原生 HTML 必须使用 v-html 指令。

在 Vue 3 中同样不能在模板表达式中直接执行方法调用（如 v-html="renderSafeMarkdown(content)"），因为组件模板在任何响应式依赖触发重绘时都会重新调用该方法。应当利用 Vue 细粒度的 computed 计算属性来包装解析结果。

<!-- src/components/MarkdownViewer.vue -->
<script setup lang="ts">
import { computed } from 'vue';
import { renderSafeMarkdown } from '../utils/markdown';

const props = withDefaults(
  defineProps<{
    content: string;
    className?: string;
  }>(),
  {
    content: '',
    className: ''
  }
);

// 基于响应式 props.content 计算安全 HTML
const sanitizedHtml = computed(() => {
  return renderSafeMarkdown(props.content);
});
</script>

<template>
  <div 
    class="markdown-body" 
    :class="className" 
    v-html="sanitizedHtml"
  />
</template>

<style scoped>
/* 注意：Markdown 生成的 DOM 元素在编译期不存在于模板中 */
/* 如果使用 scoped，必须使用 :deep() 深度作用选择器 */
.markdown-body :deep(h1),
.markdown-body :deep(h2) {
  border-bottom: 1px solid #DFD8CB;
  padding-bottom: 0.3em;
}

.markdown-body :deep(pre) {
  background-color: #2B343D;
  padding: 16px;
  border-radius: 6px;
  overflow-x: auto;
}

.markdown-body :deep(a) {
  color: #AD8B58;
  text-decoration: none;
}

.markdown-body :deep(a:hover) {
  text-decoration: underline;
}
</style>

五、生产环境高频避坑与进阶优化

1. 代码高亮集成（Highlight.js / Prism.js）

纯 marked.js 解析生成的代码块仅包含原生 <pre><code class="language-js">，无任何语法高亮样式。要在生产环境中呈现美观的代码块，应在 marked 阶段结合代码高亮库处理。从 marked.js v12+ 开始，官方推荐使用 marked-highlight 扩展包：

npm install marked-highlight highlight.js

配置示例：

import { marked } from 'marked';
import { markedHighlight } from 'marked-highlight';
import hljs from 'highlight.js';
import 'highlight.js/styles/github-dark.css'; // 选择喜爱的主题

marked.use(
  markedHighlight({
    emptyLangClass: 'hljs',
    langPrefix: 'hljs language-',
    highlight(code, lang) {
      const language = hljs.getLanguage(lang) ? lang : 'plaintext';
      return hljs.highlight(code, { language }).value;
    }
  })
);

2. 超长文档的 Web Worker 离屏解析

当 Markdown 长度达到数万行或数十万字符（如大型技术手册或抓取的日志）时，marked.parse 加上 DOMPurify.sanitize 可能会消耗 200ms 至 800ms 的 CPU 计算时间。如果在主线程直接运行，会导致页面出现明显的卡死与点击无响应。

此时应当将解析工作移至 Web Worker：

• 主线程向 Web Worker 发送原始 Markdown 文本；
• Worker 线程中执行 marked.parse；（注意：Worker 中无 DOM，若要在 Worker 中做 DOMPurify 需使用 isomorphic-dompurify 或在主线程接收 HTML 后进行快速清洗）；
• Worker 将解析结果发回主线程，通过 useMemo / computed 呈现。

3. 服务端水合一致性（Hydration Mismatch）

在 Next.js 或 Nuxt 等框架中，如果服务端解析出的 HTML 字符串与客户端初次渲染出的 HTML 字符串有微小差异（例如客户端根据浏览器环境动态补充了时间戳，或者 DOMPurify 规则在 Node 端与浏览器端存在差异），框架会抛出严重的 Hydration Mismatch 警告，甚至导致客户端全量卸载重挂载。

规避方案：确保服务端与客户端使用完全相同的配置对象，或者在富文本视图组件外包裹一层客户端挂载守卫（如仅在 mounted 为 true 时才挂载真实富文本），保证双端水合树完全对齐。

六、工程落地核心总结

在 React 与 Vue 项目中集成 marked.js，本质上是在解决“非受控 HTML 字符串向受控虚拟 DOM 视图转化”的过程。要确保整个过程安全且高效，开发者应当始终落实以下四条核心原则：

1. 防御闭环永远优先于渲染：不要抱有“输入数据绝对安全”的侥幸心理。无论数据来自内部后台还是外部用户，只要使用 dangerouslySetInnerHTML 或 v-html，就必须在 marked.js 之后串联 DOMPurify 进行不可逆的安全清洗。
2. 解析行为与生命周期绑定：严禁在组件渲染主路径上执行裸调用。React 端必须使用 useMemo，Vue 端必须使用 computed。面对流式打字或频繁变动的内容，应引入时间窗口节流机制。
3. 明晰 Scoped CSS 边界：动态注入的 HTML 节点不在单文件组件编译期范围，Vue 用户要主动使用 :deep()，React 用户建议采用独立的命名空间容器包裹预置样式（如 markdown-body）。
4. 环境差异前置规避：若项目包含 SSR（Next.js / Nuxt），提早引入同构消毒工具（isomorphic-dompurify）或执行挂载守卫，杜绝服务端执行时的 DOM 缺失崩溃与客户端水合警告。