Markdown 编辑器性能优化：基于 marked.js 的按区块增量渲染方案

你是不是也遇到过这种情况：网页里的 Markdown 编辑器，敲到一两百行的时候还很流畅，等到文档写到四五千行，每敲一个字符都要等上几百毫秒，光标飘忽不定，输入体验直接回到十年前。大多数人第一个想到的优化是换一个渲染库，可问题是业务里已经用了 marked.js，模板、定制渲染器全都是在它上面写的，不是说换就能换。我在做公司内部文档平台的时候就撞上了这道坎，最后折腾出来的方案，就是标题里写的这套……按行、按区块的最小增量更新。

文章写给谁？两类人最适用：一类是在网页里用 marked.js 做预览区，文档规模上来之后卡到没法用的前端开发者；另一类是已经在用 markdown-it、Remark 等解析器，想给编辑器加增量渲染能力的技术负责人。下面不会讲太多虚的，都是我在真实项目里一步步踩出来的架构选型和实现细节。

1. 从一次大文档卡顿说起：marked 全量解析的瓶颈到底在哪

我先说一个真实场景。公司文档平台改版后，技术负责人拿一份接近 1 万行的架构说明文档来压测。当时的预览区就是最朴素的实现：textarea 输入，每次 change 都调一次 marked.parse(markdown)，然后把结果塞到预览 div 里。4000 行以前还勉强能看，到 7000 行以后，一个简单的回车要等 300 到 500 毫秒，输入框光标跟着抽搐，整个页面像是开了慢动作。

那段时期我一度想换掉 marked，但翻了翻代码库，七八个自定义 renderer、两三个自定义 tokenizer，全跟 marked 强耦合，换库等于重写整个编辑器。没办法，只能基于它做优化。最后做出来的方案就是按行分区、按区块最小增量更新。

1.1 marked 内部到底做了几件事

要理解为什么全量渲染慢，得先拆开 marked.parse 的流程。marked 从 v4 开始，核心是 Lexer + Parser 两段式：

• Lexer 负责把原始 Markdown 文本拆成 token 列表。它是一个逐行扫描的状态机，内部维护了 fence 上下文、列表栈、引用层级等状态。
• Parser 负责把 token 列表渲染成 HTML 字符串，用的是 token 对应的 renderer，默认的或者你自定义的。

也就是说，哪怕你只改了一个字，marked 都会把整个文本重新 tokenize 一遍，再把全部 token 渲染一遍。这还没算上浏览器渲染 HTML 字符串的那部分。

tokenize 的过程对 5000 行文档来说通常只要几毫秒到几十毫秒，看着不严重，但它不是最贵的。最贵的是后面这步：把生成的完整 HTML 字符串重新赋给预览容器，浏览器要回收旧 DOM、解析新 HTML、创建整棵 DOM 树、重新做样式计算和布局。

1.2 实测：全量渲染到底慢在哪一步

我当时在项目里加了段临时埋点，分别统计了 marked.parse 的耗时和 innerHTML 赋值的耗时。用一份 2000 行的文档（包含标题、列表、表格、代码块、引用块），在普通笔记本的 Chrome 里测：

以上是我本地的实测参考，不同机器差异很大，但规律是一致的：marked.parse 只占一部分，真正的瓶颈是浏览器重建整棵预览 DOM。这两个加起来，打字时每敲一个键都要承担几百毫秒，体感就是卡死。

所以最小增量更新的关键，不只是“少 parse 一点”，更重要的是“少让浏览器重建一点”。把一次全量 innerHTML 替换，变成一次局部 DOM 替换，收益比很多人想象的大得多。

2. 按行增量更新：最直觉的方案，也是最容易翻车的方案

我最早的想法很简单：既然 marked 是逐行扫描的，那我维护一个“行号到 DOM 节点”的映射，用户修改第 n 行，就只重新解析第 n 行，替换第 n 行对应的 DOM，不就行了吗？

这个思路听起来很顺，但真正写起来就会碰到一个无法绕开的问题：Markdown 的块级语法不是按行独立的。

2.1 按行更新的基本模型

实现起来确实很直观。先把 Markdown 源码按 \n 切分成行数组，预览区也按行渲染，给每个行级 DOM 节点挂一个自定义属性，比如 data-line="n"：

javascript复制function renderLine(line, lineNo) {
  // 自己写一套“单行分类”，不要直接调 marked.parse
  if (/^#{1,6}\s/.test(line)) {
    return `<h2 data-line="${lineNo}">${escapeHtml(line.replace(/^#{1,6}\s*/, ''))}</h2>`;
  }
  if (/^>\s?/.test(line)) {
    return `<blockquote data-line="${lineNo}">${escapeHtml(line.replace(/^>\s?/, ''))}</blockquote>`;
  }
  // 其他情况...
  return `<p data-line="${lineNo}">${escapeHtml(line)}</p>`;
}

用户修改第 n 行时，只需要 document.querySelector('[data-line="n"]') 找到旧节点，再替换成新的行节点。这样无论文档多长，更新的成本都只跟当前行内容有关。

2.2 行的类型判断：为什么不能直接调 marked.parse

这里有个关键问题：不要对单行直接调 marked.parse。marked 的块级解析器是针对“整个文档”设计的，它不知道“上下文”。你把一个孤零零的 - item 丢给 marked.parse，它会认为这是一个列表，但如果这一行原本是一个代码块里的内容，那样解析就错了。

所以我写了一个“行级分类器”，用若干正则判断行的类型：ATX 标题、引用、无序列表项、有序列表项、围栏代码块开始/结束、表格分隔行、空行、普通文本。分类器只负责“猜测这一行可能是哪种块”，真正需要的上下文信息（比如是否在代码块里），由外层增量模块维护。

2.3 按行方案的边界：跨行结构一多就破功

按行更新在小文档、以段落为主的内容里表现还行，但一遇到真正的 Markdown 完整语法，问题就暴露了：

• 代码块从第 10 行开始，到第 20 行结束，你在第 15 行改了一个字符，按行更新只会替换第 15 行的内容，但整个代码块是一个 <pre><code> 节点，被拆成 11 个行级节点后，视觉和语义都变了。
• 表格是由表头、分隔行、数据行共同组成的，单独更新某一行会导致表格结构错乱。
• 列表项内部可能有嵌套列表，上一行的缩进变化会改变下一行的层级。
• 普通段落本来是连续多行合并成一个 <p>，按行渲染会把一个段落拆成多个 <p>，渲染结果和 marked 原生结果不一致。

说白了，行粒度太细，细到和 Markdown 的块级语法对不上。这个方案最后被我降级成“编辑器处于纯文本模式时的快速路子”，或者作为一种降级容错方案保留着。真正的生产级解法，是下面要说的按区块更新。

3. 按区块增量更新：用“状态快照”找到真正的最小重渲区间

“区块”是 marked 里 token 的顶层概念：一段连续文本构成 paragraph，一段以 > 开头的连续行构成 blockquote，一个 ``` 围栏内的连续行构成 code，一个表头加上若干表格行构成 table。按区块更新，就是让“重渲的最小单元”跟这些块级 token 对齐。

3.1 为什么需要状态快照

Markdown 的块级语法是有上下文的。一个 fence 出现后，后面所有行都处于 code 状态，直到出现另一个匹配的 fence；一个引用开始后，连续的引用行会合并成同一个 blockquote；一个表格需要先看到表头行，再看到分隔行，之后的数据行才组成表格。

这意味着，要判断“第 n 行到第 m 行之间的区块是否需要重新渲染”，不能只看这 m-n+1 行的内容，还要看它们前面的解析状态。我用了一个简单但有效的办法：在首次全量解析时，记录每一行的“状态快照”（state snapshot）。

状态快照至少包含这些字段：

javascript复制{
  inFence: false | '`' | '~',   // 是否处于围栏代码块内，围栏字符类型
  fenceCharCount: 0,            // 围栏长度，用于匹配结束围栏
  listStack: [],                // 当前列表嵌套栈（ordered/unordered + indent）
  quoteLevel: 0,                // 引用嵌套层级
  inTable: false,               // 是否处于表格模式
  tableColumns: 0,              // 表格列数
  listTight: false,             // 当前列表是否 tight
}

这个快照不需要完整还原 marked 内部所有状态，只要能把“影响后续行归属的关键上下文”记录下来就行。

3.2 增量扫描：从编辑行向后找到稳定点

假设用户编辑发生在第 startLine 行，我把它叫做 dirtyStart。更新过程分四步：

1. 更新行数组，把 startLine 之后的行重新编号。
2. 从 startLine 开始，用 marked 的块级规则重新解析每一行，同时更新当前状态快照。
3. 每解析到一行，就把“新状态快照”和旧快照数组里对应行位置的快照做对比。
4. 如果某行的新快照和旧快照完全一致，并且从这一行开始，未来能遇到的所有语法边界（fence、表格、列表嵌套）预期也与旧状态一致，就认为这一行是稳定点（stableLine）。

于是 dirty range 就是 [dirtyStart, stableLine - 1]。只需要对这个范围重新生成 token、重新渲染 HTML，然后局部替换 DOM。

这里要特别说明第 4 步里的“预期一致”是什么意思。只看当前行状态相同还不够，比如当前行状态都是 inFence: false，但旧文档里下一行就是 fence 开始，而新文档里下一行不再是 fence，那从下一行开始的状态就不一样了。所以通常要多往后扫描若干行，或者扫描到出现明确的“边界 token”（比如 fence 结束、表格结束）才算数。

3.3 区块边界的识别：哪些块必须整体重渲

实践下来，我把块分成三类：

表格我直接整表重渲，不拆列。因为表格列数可能在编辑分隔行时变化，拆列更新的复杂度远高于收益。代码块同理，整体重渲。其实“区块最小增量更新”不是说每个 token 都必须拆到最小，而是“跟全量更新相比，能用最小代价完成事”。

引用块和列表比较特殊。引用块的嵌套层级会变化，但内部主要是普通段落和嵌套块，我可以把整个引用块作为一个“脏区块”重渲；列表则是“列表栈”变化时影响后续所有项，所以我通常把受影响的外层列表整体重渲。

有一个可以明显提速的优化：在 dirty range 内，如果某个区块是 paragraph 且没有跨行，我可以直接 diff 出它内部变化的文本子串，只更新文本节点。但对于大部分场景，这种优化引入的复杂度大于收益，我最后只在代码块和表格这种“大块”里做了整块替换。

3.4 脏区块与旧 DOM 的替换策略

渲染出 dirty range 的 HTML 后，怎么替换进现存的预览 DOM？我的做法是：

• 全量解析初次渲染时，给每个“顶层块容器”加一个 data-block-id。
• 增量解析时，把所有受影响顶层块（可能是一个或多个）对应的 DOM 节点收集起来，在容器里用一个 DocumentFragment 承接新的渲染结果。
• 先定位脏区块起点对应的 DOM 锚点，把新 fragment 插到锚点前，然后移除旧的脏区块 DOM 节点。

如果是 Vue 或 React 项目，这里有个容易踩的坑：不要让框架去 diff 整棵预览树，否则 1000 行的 vdom diff 又把性能吃回去。用 ref 拿到预览容器，直接手动操作 DOM，框架只管编辑区。

4. 把方案落到 marked.js：代码结构和接入方式

说了这么多原理，下面是我在项目里的实际落地结构。整体原则：不改 marked 源码，全部封装在外层。

4.1 核心类的最小骨架

我用一个 IncrementalMarkdown 类来管理行数组、状态快照和 DOM 映射：

javascript复制class IncrementalMarkdown {
  constructor(markedInstance, previewEl) {
    this.marked = markedInstance;
    this.previewEl = previewEl;
    this.lines = [];
    this.lineStates = [];
    this.blockDomMap = new Map(); // blockId -> DOM element
  }

  init(text) {
    this.lines = splitLines(text);
    this.lineStates = this.scanStates(this.lines);
    this.previewEl.innerHTML = this.renderAll();
    this.indexBlockDom();
  }

  applyEdit(startLine, removeLineCount, newLines) {
    this.lines.splice(startLine, removeLineCount, ...newLines);
    const stableLine = this.findStableLine(startLine);
    this.patchRange(startLine, stableLine);
    this.lineStates = this.scanStates(this.lines); // 简化版；实际可以局部重扫
  }
}

其中 findStableLine 就是第三部分说的“从 dirtyStart 向后扫，找到状态快照与旧快照一致且预期边界稳定的行”。这个函数是性能关键，建议内部做两个限制：最大扫描行数（比如 3000 行），超过就直接回退全量渲染。

注意：上面的 this.lineStates = this.scanStates(this.lines) 是为了让代码好读，真实实现里应该只在 dirty range 内重扫状态快照，否则每次编辑都全量扫状态就失去意义了。

4.2 扫描状态快照的简化实现

用一个简化版的状态机来演示：

javascript复制function scanStates(lines) {
  const states = [];
  let cur = emptyState();
  for (let i = 0; i < lines.length; i++) {
    cur = nextState(cur, lines[i]);
    states.push(cur.snapshot());
  }
  return states;
}

function nextState(state, line) {
  // 1. fence 状态优先
  if (state.inFence) {
    // 检查是否遇到与开始围栏匹配的结束行
    if (isClosingFence(line, state.fenceMark, state.fenceLen)) {
      return { ...state, inFence: false };
    }
    return state;
  }
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    return { ...state, inFence: true, fenceMark: fenceMatch[1][0], fenceLen: fenceMatch[1].length };
  }
  // 2. 表格模式：表头 + 分隔行 + 后续数据行
  // 3. 列表缩进栈、引用层级处理
  // 4. 其他行处理
  return state;
}

这个状态机不需要覆盖 marked 的所有细节，但一定要覆盖你文档里能用到的语法。如果漏了某种语法，就会导致稳定点判断错误，结果要么重渲范围偏大（影响了性能），要么重渲范围偏小（渲染结果错误）。

4.3 接入 React/Vue 时的局部替换方式

我的项目是 React。一开始我直接在编辑器组件里 setState(previewHtml)，但最后放弃了，改成 ref + 手动 DOM 替换，原因前面说过：React 对整棵预览树做 diff 的成本，在真正的大文档下仍然不可忽视。

在 React 里接入的做法：

javascript复制function Editor({ markdown, onChange }) {
  const previewRef = useRef(null);
  const incrRef = useRef(null);

  useEffect(() => {
    if (!incrRef.current) {
      incrRef.current = new IncrementalMarkdown(marked, previewRef.current);
      incrRef.current.init(markdown);
      return;
    }
    // 把 textarea 的 change 换算成 startLine/removeLineCount/newLines
    incrRef.current.applyEdit(startLine, removeLineCount, newLines);
  }, [markdown]);

  return (
    <div>
      <textarea value={markdown} onChange={handleChange} />
      <div ref={previewRef} className="preview" />
    </div>
  );
}

然后配合一个 debounce（比如 150ms）或 requestAnimationFrame 合并输入，避免每敲一个字都触发一次区块替换。这里还有个小技巧：输入时先只更新 textarea，预览更新放到下一个动画帧执行，这样输入框的光标操作永远不被阻塞。

4.4 自定义 tokenizer 和 renderer 怎么兼容

如果项目里用了 marked.use({ tokenizer, renderer }) 注册了自定义语法，增量模块要注意两点：

• 状态快照里要给自定义语法留状态位。比如我加过一套 callout 语法，用 :::tip 开头，就必须在状态机里加一个 callout 状态，否则它会被当成普通段落，稳定点判断直接失效。
• renderer 不用改。增量模块只负责决定“重渲哪些区块”，区块内的渲染还是交给 marked 自己的 tokenizer + renderer。

我在改造时还发现，marked 的 walkTokens 很有用，可以趁全量初始化阶段把每个 token 的行号范围收集出来，建立“token -> 行区间”索引。这个索引在找脏区块时能省掉很多线性扫描。

4.5 复用旧 token 的时机

marked 渲染的中间产物是 token，本质上是普通 JS 对象。我们可以保留每个区块的 token 引用，编辑时如果判断“该区块类型未变、结构未变”，就只需要更新 token.raw / token.text，再调用对应 renderer 重新生成 HTML。这样能省掉重新 tokenize 的开销。

重点：只有在开始和结束边界都一致的情况下才能复用。比如段落变成标题，不能复用；引用块内部层级变了，不能复用；代码块内容变了但 fence 还在，可以复用。我在实现里只对 code、table、blockquote 这三种大块做了 token 复用，其余类型太琐碎，复用反而容易出错。

5. 实测数据与踩坑记录：哪些场景不能只靠区块更新

到了这一节，说点真正有价值的实测和坑。我在核心方案跑通后，用一份接近 8000 行的长文档做了对比测试，同时也把过程中踩到的几个坑记录一下，希望能帮后面的人少走弯路。

5.1 增量更新和全量更新的实测对比

测试环境：公司配的 ThinkPad，Chrome 120，文档为 8000 行，内容包含大量标题、列表、表格、代码块。表格和代码块占总字数 40% 左右。

可以看到，普通段落编辑的提速非常明显；代码块和表格这类“有状态块”因为要整块重渲，收益会小一些，但仍然远快于全量更新。新增 30 行代码块的场景耗时偏高，是因为插入点附近从普通段落变成代码块，状态变化导致 dirty range 变大了。这个是正常现象，用户能感知到的延迟在 400ms 左右，不算优秀，但可以接受。

如果你对代码块内的编辑延迟特别敏感，可以在代码块内部再做一层“行级高亮更新”，把代码块拆成多行 span，只更新变化行。也就是把第二部分的“按行”思路，应用到“已经确定在代码块内”的局部场景里。这样能把代码块编辑的耗时从 40ms 压到 3ms 以内，但需要你自己处理代码高亮库，跟 marked 的渲染就解耦了。

5.2 踩坑一：未闭合 fence 导致的整篇重渲

一开始我的稳定点判断只比较“当前行快照是否相同”，结果遇到一个很阴险的 bug：文档里有个代码块忘记写结束 ``` ，但它在旧快照里是 inFence: true 状态。用户在这个残缺代码块之前的某行插入一个空行，我的增量扫描发现新状态到某行之后就不再变化了，于是把稳定点定得很早，实际上整个代码块后面的所有内容都应该被重新解析，渲染结果直接错误。

修复方式：状态快照比较时，必须把“当前是否处于 fence 内”作为一个强条件。如果 dirtyStart 往后扫描到最大行数时，仍然处于 fence 内，说明文档出现了未闭合围栏，这时候直接回退全量渲染，不要去猜。

5.3 踩坑二：表格列数变化导致的 DOM 错位

表格整体重渲后，我最初是记录“表格区块的起始行”，然后把旧表格 DOM 替换成新表格 DOM。看起来没什么问题，但连续操作时出过一次错：用户先在第一列新增了内容，表格列数不变，一切正常；然后他在分隔行把 |---|----| 改成 |---|----|----|，列数从 2 变成 3，我重渲的是整个表格，但后续的旧数据行 DOM 我没有全部清理干净，导致页面出现一个残留的旧表格尾巴。

原因是我的表格区块索引只记录到“分隔行”，没有把数据行也算进区块范围。修复就是：表格状态里记录完整的表格结束位置，数据行也纳入表格区块。

5.4 踩坑三：快捷键和 Enter 的编辑事件换算

textarea 的 change 事件给的是整个文本，如果你直接把它赋值给 this.lines，相当于又退回了全量。我后来是通过比对“上一次快照文本”和“当前文本”来算出最小编辑区间：

javascript复制function diffLines(oldLines, newLines) {
  let start = 0;
  let endOld = oldLines.length;
  let endNew = newLines.length;
  while (start < endOld && start < endNew && oldLines[start] === newLines[start]) start++;
  while (endOld > start && endNew > start && oldLines[endOld - 1] === newLines[endNew - 1]) {
    endOld--;
    endNew--;
  }
  return {
    startLine: start,
    removeLineCount: endOld - start,
    newLines: newLines.slice(start, endNew)
  };
}

这个比较是 O(文档长度) 的，但只比较字符串引用，成本很低。如果你连这个都不想每次做，可以在 onInput 里记录行号，但 Enter 换行、粘贴多行、撤销回退都会让