marked.js 与 markdown-it 对比：性能、体积及扩展性该怎么选择？

在 JavaScript 与 TypeScript 生态中，如果需要在浏览器或 Node.js 环境中将 Markdown 转换为 HTML，marked.js 与 markdown-it 是两个最主流且经受过长期工业检验的选择。两者在工程设计理念上存在根本差异：如果追求极小的打包体积、毫秒级的单文本吞吐速度，且仅需要标准格式渲染，marked.js 是更轻量敏捷的选择；如果项目依赖严谨的 CommonMark 规范、需要支持数学公式、代码高亮、提示容器等复杂的自定义语法扩展，或者需要依靠庞大的社区插件库，markdown-it 则是更为健壮稳固的基石。

缩略概览：marked.js 与 markdown-it 核心特性与适用倾向横向一览

一、底层解析架构对比：正则扫描与状态机流

评估 Markdown 解析器的首要维度是其底层的编译流水线设计。解析器的语法分析模式直接决定了内存占用、异常输入的容错能力以及复杂嵌套语法的解析正确性。

1. marked.js 的正则驱动（Lexer-Tokenizer）模式

marked.js 的核心架构依托一组预编译的正则表达式。其解析流程高度精简：输入原始字符串后，词法分析器（Lexer）自顶向下通过正则匹配块级元素（如标题、段落、列表、代码块），匹配成功后切分字符串并生成 Token 对象数组，接着递归解析行内元素（如粗体、链接、代码片段），最后由 Parser 和 Renderer 逐个将 Token 转换为 HTML 字符串输出。

这种设计的优势在于执行路径极短，代码量小，V8 引擎对正则表达式有深度 JIT 优化。然而，纯正则在应对多层嵌套结构（如多层嵌套的列表穿插引用块与代码围栏）时，容易遇到语法歧义或因贪婪匹配产生性能波动，对复杂排版边界的推断灵活性相对受限。

2. markdown-it 的三层分权状态机与 Token 流

markdown-it 摒弃了单一正则贯穿到底的思路，采用接近传统编译器前端的三层管道架构，划分为 Core、Block 和 Inline 三个独立的 Ruler（规则链）：

• Core 规则链：负责全局文本规整（Normalization）以及挂载宏观拦截器。
• Block 规则链（StateBlock）：使用双指针与行列游标维护状态机，严格依据行首缩进、空行和定界符判定块级边界。
• Inline 规则链（StateInline）：在块级上下文确定后，逐字符扫描行内定界符，按规范计算嵌套深度与括号配对。

markdown-it 最终输出的是成对出现的 Token 序列（例如 paragraph_open、inline、paragraph_close），每个 Token 带有精确的行列映射（map）与属性列表（attrs）。这种设计严格保证了与 CommonMark 规范的 100% 兼容，并在深层嵌套场景下表现出极强的确定性。

图 1：marked.js 与 markdown-it 核心解析流水线对比

二、打包体积与运行时环境差异

在前端打包（如 Vite、Webpack、Rollup）与无服务器环境（Serverless / Edge Workers）中，库的依赖规模与体积占用是不可忽视的指标。

1. 依赖与 Bundle Size 量化对比

我们以现代 npm 发行版本为基准对二者的产物体积与依赖进行横向对比：

三、性能表现与解析吞吐量分析

在实际业务中，性能通常表现为两种形式：一是在用户打字时客户端对 Markdown 的高频实时重新渲染；二是在服务端或构建阶段对成千上万篇 Markdown 文档进行批量静态渲染（SSG）。

1. 纯文本基准测试与吞吐差异

在标准文本（10 KB 到 500 KB 的长篇 Markdown 文档）测试中，marked.js 的每秒执行操作数（ops/sec）通常是 markdown-it 的 1.5 倍至 3 倍。这一差距的核心原因在于：

• Token 构造开销：markdown-it 为每一个标签生成独立的 Open/Close Token 对象并维护属性数组，对象分配与垃圾回收（GC）频率显著高于 marked.js。
• 状态跟踪开销：markdown-it 持续维护行号映射（source map）以及多重分界符栈（delimiter run stack），以确保完全符合 CommonMark 规约中的边缘情况。

2. 安全防护与 XSS 防御策略

性能不能以牺牲安全性为代价。在渲染不可信的用户输入（例如评论区、协作编辑器）时，XSS 防护是核心考核项：

• markdown-it 的默认防线：默认配置下，html: false 会自动对用户输入的原始 HTML 标签进行实体编码转义，同时自动验证链接协议（仅放行 http、https、mailto 等白名单），具有良好的默认防御能力。
• marked.js 的安全策略：marked.js 早期曾内置 sanitize: true 选项，但因无法彻底防范变种 XSS 攻击，官方已正式废弃该选项，强制建议配合专业的 HTML 净化库（如 DOMPurify）。

图 3：marked.js 与 markdown-it 核心性能与功能指标量化矩阵

四、扩展机制与插件开发实操

扩展性往往是技术选型的分水岭。如果你的业务需要支持类似 VuePress 的自定义容器语法（例如 ::: warning 警告内容 :::）或支持类似 Obsidian 的特殊语法标记，两者的扩展实现路径截然不同。

图 2：Markdown 自定义语法扩展开发四步实施流程

1. marked.js 的扩展实现示例

marked.js 自 v2.1 引入了统一的 marked.use() 扩展系统。以下示例展示如何通过自定义 Tokenizer 与 Renderer，为文章注入一个自定义徽章（Badge）语法 !badge[文本](类型)：

import { marked } from 'marked';

// 注册自定义扩展
marked.use({
  extensions: [{
    name: 'badge',
    level: 'inline', // 行内语法
    start(src) {
      return src.match(/!badge\[/)?.index;
    },
    tokenizer(src) {
      const rule = /^!badge\[([^\]]+)\]\((info|warning|success)\)/;
      const match = rule.exec(src);
      if (match) {
        return {
          type: 'badge',
          raw: match[0],
          text: match[1],
          badgeType: match[2]
        };
      }
    },
    renderer(token) {
      const typeClass = token.badgeType === 'warning' ? 'bg-amber' : 'bg-blue';
      return `<span class="badge ${typeClass}">${token.text}</span>`;
    }
  }]
});

// 测试渲染
const md = '这是一个自定义标记：!badge[测试通过](success)';
const html = marked.parse(md);
// 输出：<p>这是一个自定义标记：<span class="badge bg-blue">测试通过</span></p>

对于行内简单语法或修改既有 HTML 标签（如强制外链添加 target="_blank"），marked.js 的代码非常紧凑。但如果要实现跨行、多层嵌套且内部允许渲染正常 Markdown 语法的复杂块级容器，正则匹配模式容易变得脆弱难维护。

2. markdown-it 的插件生态与状态机扩展

markdown-it 的插件架构是其最核心的竞争壁垒。其生态系统拥有 markdown-it-anchor（自动锚点）、markdown-it-toc-done-right（目录生成）、markdown-it-katex（数学公式渲染）以及 markdown-it-container 等极其完备的工具链。

以下示例展示如何使用官方推崇的 markdown-it-container 快速创建高灵活度的块级提示框：

import MarkdownIt from 'markdown-it';
import markdownItContainer from 'markdown-it-container';

const md = new MarkdownIt({
  html: false,
  linkify: true,
  typographer: true
});

// 注册 warning 自定义容器
md.use(markdownItContainer, 'warning', {
  validate: function(params) {
    return params.trim().match(/^warning\s*(.*)$/);
  },
  render: function (tokens, idx) {
    const token = tokens[idx];
    if (token.nesting === 1) {
      // opening tag
      const info = token.info.trim().slice('warning'.length).trim();
      const title = info ? md.utils.escapeHtml(info) : '注意';
      return `<div class="custom-block warning"><p class="custom-block-title">${title}</p>
`;
    } else {
      // closing tag
      return '</div>
';
    }
  }
});

// 测试包含嵌套 Markdown 的输入
const rawMarkdown = `
::: warning 生产提示
请确认以下配置项已正确填写：
- 数据库连接端口
- 密钥鉴权 Token
:::
`;

const result = md.render(rawMarkdown);

在上述代码中，由于 markdown-it 是成对生成 open 与 close Token，容器内部的无序列表会继续交由标准的 Block/Inline Ruler 进行递归解析，无需开发者手动处理内部的换行与缩进，稳定性极高。

五、工程化选型决策指南

在实际项目立项时，选择 marked.js 还是 markdown-it 不应当仅仅依据个人习惯，而应紧扣项目的**架构环境**与**功能边界**。

图 4：Markdown 解析库业务场景技术选型决策树

1. 推荐选用 marked.js 的典型场景

1. 实时双向同步编辑器：用户在输入框打字时，前端需要以 60 FPS 或高频触发实时预览。marked.js 的快速通道能有效压低每次渲染耗时，避免输入卡顿。
2. 极小体积的前端组件：例如轻量级 SDK、聊天窗口组件、嵌入式 FAQ 弹窗，要求引入的所有第三方库体积总和受限。
3. 边缘计算与 Serverless 页面网关：在 Cloudflare Workers、Vercel Edge Functions 等限制 Cold Start 启动时间与内存配额的场景下，零依赖的 marked.js 冷启动损耗更小。
4. 标准规范的极简展示：仅需将常见的主流 Markdown（标题、列表、表格、代码块）转化为常规 HTML，无需任何特殊语法插件。

2. 推荐选用 markdown-it 的典型场景

1. 技术文档站点与知识库系统：如 VuePress、VitePress、Docute 等现代化文档引擎均以 markdown-it 为核心。技术文档通常严重依赖行号高亮、警告卡片（Callout）、代码组切换、自定义锚点与目录大纲。
2. 学术与专业内容平台：需要深度整合 LaTeX / KaTeX 数学公式、脚注（Footnote）、任务列表（Task lists）及复杂表格。
3. 对 CommonMark 规范有严格一致性要求的场景：需要确保不同作者、不同客户端在边缘排版情况下渲染出的 DOM 树完全一致。
4. 团队自建丰富 DSL 语法的 CMS 系统：需要依托成熟的 Token 流模型，平稳编写与管理大量自定义业务语法。

六、总结与落地配置推荐

简而言之，marked.js 是以“极速、极简、轻量”为核心诉求的冲锋枪，适合轻装上阵的客户端交互；而 markdown-it 是以“规范、严谨、可塑性强”为核心诉求的重型装甲车，适合承载复杂内容生产体系。

在实际落地时，建议搭配以下经检验的最佳生产依赖组合：

• 轻量级组合：marked + DOMPurify + marked-highlight（配合 highlight.js 实现轻量语法高亮）。
• 全功能文档组合：markdown-it + DOMPurify + markdown-it-anchor + markdown-it-container + markdown-it-katex。