一条 Markdown 渲染管线的全部细节：Worker 源行标注与按需加载

MarkView （markview.art）的右侧预览区，看起来只是「把 Markdown 变成 HTML」。但真正跑起来的是一条跨线程、按需加载、带序号防乱序的管线：marked 解析、KaTeX 公式、highlight.js 高亮全部在 Web Worker 里跑完，Mermaid 因为需要真实 DOM 被单独留在主线程，最后串行提交到预览区。

本文把这条链路拆开讲。

一、链路全景

从一次击键到 DOM 落地，大致是这样：

 复制代码content 变化
 └─ previewRenderSession.render(source)              [主线程]
     └─ markdownRenderer.render(source) → seq++
         └─ worker.postMessage({ seq, source })
             └─ renderMarkdown(source)               [Worker 线程]
                 ├─ extractFrontmatter               抽 YAML，换行占位保行号
                 ├─ lexer(body)                      marked 词法（含数学扩展）
                 ├─ annotateSourceLines(tokens)      注入 token.sourceLine
                 ├─ scanRenderNeeds → 按需 await     加载 hljs / KaTeX
                 └─ parser(tokens, { extensions })   同步渲染出 HTML
             └─ postMessage({ seq, html, toc })
     └─ apply(seq, result)                           [主线程] 丢弃过期 seq
         └─ preparePreviewHtml(html, theme)          Mermaid 落成 SVG
             └─ publishQueue 串行 → html.value = …

线程边界很干脆：纯字符串、零 DOM 的部分全在 Worker；需要 DOM 的部分（Mermaid）留在主线程。

Worker 入口只有九行：

 复制代码// src/core/markdown/renderMarkdown.worker.js
// Web Worker：把 Markdown 渲染（marked + KaTeX + highlight.js，纯 JS、零 DOM）搬离主线程，
// 大文档编辑时主线程不再卡顿。收 { seq, source }，回传 { seq, html, toc }。
self.onmessage = async (event) => {
    const { seq, source } = event.data
    const { html, toc } = await renderMarkdown(source)
    self.postMessage({ seq, html, toc })
}

二、data-source-line：一切定位的地基

滚动同步、搜索定位、任务列表勾选回写——这些功能全都依赖一个东西：预览区的每个块级元素知道自己来自源码第几行。

MarkView 的做法是在 lex 之后、parse 之前遍历 token 树，用 token.raw 在源文里做游标式定位：

 复制代码// src/core/markdown/renderMarkdown.js
// 用 token.raw 在源文中定位块级 token 的起始行，输出 data-source-line。
// 该属性是「编辑区行号 ↔ 预览 DOM」的唯一粘合契约，滚动同步与搜索定位都依赖它。
const annotateSourceLines = (tokens, source) => {
    let cursorIndex = 0
    let cursorLine = 1    tokens.forEach((token) => {
        if (!token.raw) return        const tokenIndex = source.indexOf(token.raw, cursorIndex)
        if (tokenIndex < 0) return        cursorLine += countLines(source.slice(cursorIndex, tokenIndex))        if (SOURCE_LINE_TYPES.has(token.type)) {
            token.sourceLine = cursorLine
        }
        if (token.type === 'list') annotateListItemLines(token)        cursorIndex = tokenIndex + token.raw.length
        cursorLine += countLines(token.raw)
    })
}

游标 cursorIndex 单调推进，所以虽然写着 indexOf，实际接近线性。

真正的麻烦在嵌套列表。marked 会把嵌套列表的 raw 逐行去掉父级缩进，导致 indexOf 直接失效。这里换了一种定位法：

 复制代码// 列表项内的嵌套列表：其 raw 被 marked 逐行去除了父级缩进，无法直接 indexOf，
// 改用「首行内容去缩进后精确相等」在 item.raw 的行中定位起始行——若某行去掉缩进后
// 与嵌套列表首行完全一致，它本就会被解析成列表，故不会误中普通文字行。
const childFirstLine = child.raw.split('n', 1)[0].trim()
const lineOffset = itemLines.findIndex(
    (text, index) => index >= searchFrom && text.trim() === childFirstLine
)

还有个容易忽略的坑：frontmatter。如果直接把 ---ntitle: xn--- 从源码里切掉再解析，后面所有 token 的行号都会整体偏移。解法是用等量换行占位：

 复制代码// 抽出 frontmatter，并用等量换行占位替换原区域——保留后续 token 的源码行号，
// 否则 annotateSourceLines 里 data-source-line 全部错位，滚动同步会失准。
const consumed = match[0]
const newlineCount = countLines(consumed)
const blanked = 'n'.repeat(newlineCount) + source.slice(consumed.length)

这个契约在消费端也有明确声明（PreviewController.js 的文件头注释写着「data-source-line 契约由 renderMarkdown 与这里闭环，Vue 组件不感知该属性」）——生产方和消费方各一处，中间层完全不用知道它存在。

三、绕开「renderer 不能 async」

marked 的 renderer 必须同步返回字符串。但代码高亮要 highlight.js，公式要 KaTeX，这两个都是几十上百 KB 的重依赖，不该无脑打进主包。

MarkView 的解法是把渲染拆成三拍：先 lex，再扫描 token 树看这次到底需要什么，异步加载完，最后同步 parse。

 复制代码// marked 的 renderer 必须同步返回字符串，无法在其中 await；
// 故在 parse 前先按 token 需求预加载重依赖，加载好后再走同步渲染。
const needs = scanRenderNeeds(tokens)
await Promise.all([needs.hljs ? loadHighlighter() : null, needs.katex ? loadKatex() : null])

scanRenderNeeds 递归遍历 token 树（子 token 分布在 tokens / items / header / rows 四个字段，其中 rows 还是二维的），判断本次渲染是否真的出现了非 mermaid 的代码块、是否出现了公式。没有就不加载——一篇纯文字的文档首屏，既不会下载 hljs，也不会下载 KaTeX。

CSS 也是同样的按需策略，探测方式甚至不建 DOM，直接字符串匹配：

 复制代码// src/preview/preparePreviewHtml.js
// KaTeX 样式改为按需注入：仅当预览实际含公式时才加载 katex.min.css（缓存，仅注入一次）。
// 与 mathExtension 的 JS 懒加载配套，让无公式文档的首屏彻底不碰这份较大的样式表。
let katexCssPromise = null
const ensureKatexCss = () => {
    if (!katexCssPromise) {
        katexCssPromise = import('katex/dist/katex.min.css').catch(() => {})
    }
    return katexCssPromise
}

而且不 await——CSS 加载和 DOM 渲染并行，公式先无字体显示、样式到位后自动补上，比整体阻塞体验好。

四、行内公式与货币符号的战争

$…$ 作为行内公式定界符有个经典问题：「这件衣服 $100，那件 $200」会被识别成一个公式。

MarkView 采用了 Pandoc / GitHub 的定界规则，整条正则的推导过程被完整写在注释里：

 复制代码// src/core/markdown/mathExtension.js
// 行内公式 $...$：不匹配 $$，内部不跨行、不含裸 $。
// 采用 Pandoc/GitHub 的定界规则规避货币误判（如「买 $100 和 $200」不应被当公式）：
//   1. 开 $ 右侧紧邻非空白        (?=S)         —— 排除「$ 100」这类
//   2. 闭 $ 左侧紧邻非空白        [^$ns] 结尾  —— 「$100 和 $」的闭 $ 前是空格，不成立
//   3. 闭 $ 右侧不接数字          (?![$d])      —— 「$5 到 $10」的 $10 不误开公式
// 内容首尾均须非空白，故用「(?=S) + …以非空白结尾」表达，避免 lookbehind（旧版 Safari 不支持）。
// 转义 `$` 无需在此处理：marked 内置的 escape tokenizer 会先消费它，落为字面 $。
const INLINE_MATH_RE = /^$(?!$)(?=S)([^$n]*[^$ns])$(?![$d])/

四个决策叠在一条正则里：$$ 前瞻排除、货币三规则、刻意不用 lookbehind 兼容旧 Safari、转义交给 marked 内置的 escape tokenizer 先消费而不自己处理。

块级 $$ 也有讲究——start 函数只认行首：

 复制代码// 只认行首的 $$，避免把段落中行内代码 `$$` 误当块级公式起点而截断段落。
start(src) {
    const match = /(^|n)$$/.exec(src)
    return match ? match.index + match[1].length : undefined
},

这些规则在测试里都是独立用例：买 $100 和 $200 一共 $300 全不成公式、区间 $ x $ 不成公式、$5 走 marked 的 escape 路径。

顺带一个体积细节：KaTeX 渲染时传的是 output: 'html' 而非默认的 htmlAndMathml，DOM 直接少一半。

五、Mermaid：唯一留在主线程的一段

Mermaid 渲染需要真实 DOM（内部要往 document 插临时容器测量文本尺寸），Worker 里没有 DOM。所以它被单独切出去：Worker 只吐占位块，主线程再异步替换成 SVG。

 复制代码// mermaid：不做语法高亮，输出占位块，源码作为文本子节点，由预览层异步渲染成图。
if (language === 'mermaid') {
    return `<div class="mermaid-block"${getSourceLineAttr(token)}>${escapeHtml(token.text)}</div>`
}

主线程侧有三个非做不可的处理。

其一，串行化。 mermaid.initialize 是全局单例配置，并发调用会互相污染主题：

 复制代码// src/preview/mermaidRenderer.js
// Mermaid SVG 生产器：按需加载、按主题和源码缓存，并串行保护全局 initialize + render。
const cacheKey = (code, theme) => `${theme === 'dark' ? 'dark' : 'default'}n${code}`
// ...
renderQueue = render.catch(() => undefined)

最后那行很关键：队列尾节点必须吞掉异常，否则一次渲染失败会把后续所有渲染串死。

其二，区分「语法错误」和「还没写完」。 实时预览有个特有的状态：用户刚敲下 ```````mermaid ````这一行，围栏还没闭合，后面的正文被整段吞进代码块——这不是错误，是输入中间态：

 复制代码// 围栏尚未闭合时，后续正文会被整段吞进源码，mermaid 识别不出图表类型（UnknownDiagramError）。
// 这种「还不是图」的输入中间态按等待处理；只有已识别出类型的真实语法错误才展示错误块。
const unknownType =
    error?.name === 'UnknownDiagramError' || /no diagram type detected/i.test(error?.message || '')
block.innerHTML = unknownType
    ? '<p class="mermaid-empty">等待图表内容…</p>'
    : `<pre class="mermaid-error">Mermaid 渲染失败：${escapeHtml(error?.message || String(error))}</pre>`

其三，首屏不为它陪等。 Mermaid 库很大，加载 + 渲染可达数百毫秒。如果整份 HTML 都等它，右侧会长时间停在骨架屏。于是有了「抢先绘制」：

 复制代码// src/workspace/previewRenderSession.js
// 含 Mermaid 的原始 HTML 需按需加载庞大的 mermaid 库并异步渲染成 SVG，耗时可达数百毫秒。
// 首屏若整份等它，右侧会长时间停留在骨架屏。此处先把带占位块的原始 HTML 抢先交给调用方
// 绘制一次（仅撤骨架屏、让文本立即可读）。抢先绘制不推进 published，定位类消费方走
// whenPublished，仍等下方 SVG 就位后的最终发布，故定位精度不受影响。

「抢先绘制不推进 published」是这段设计的精髓：视觉上提前一步，但依赖精确布局的消费方（滚动定位、搜索跳转）走的是另一条 whenPublished 通道，不受影响。

主题跟随也顺势解决了——theme 进了缓存 key，切主题时不重新走 Markdown 渲染，只复用 latestRaw 重跑一遍 prepare。首次渲染的图打上 --fresh 做淡入，缓存命中的重发布不打标，避免每次按键都让所有图表重放动画。

六、两层序号，各防各的乱序

快速输入时会有多个渲染请求同时在途，旧结果不能覆盖新结果。MarkView 用了两层调度器，各有一套计数。

第一层在 Worker 调度：

 复制代码// src/workspace/markdownRenderer.js
const apply = (resultSeq, result) => {
    if (disposed || resultSeq < applied) return
    applied = resultSeq
    onResult(result, resultSeq)
    settleWaiters(true)
}

注意是 < 而非 <=——允许同一 seq 被重复 apply（主题切换的 refresh 场景要用）。

降级路径也在这一层。Worker 创建失败（老浏览器）和运行期崩溃是两条不同的路：

 复制代码try {
    worker = createWorker()
    worker.onmessage = (event) => apply(event.data.seq, { html: event.data.html, toc: event.data.toc })
    worker.onerror = () => {
        worker?.terminate()
        worker = null
        if (latestRequest && latestRequest.seq > applied) renderWithoutWorker(latestRequest)
    }
} catch {
    worker = null
}

崩溃时只补渲染 latestRequest（不重放整个队列），且只在它还没被应用时补。而 renderWithoutWorker 走的是动态 import——降级代码在正常路径下完全不进主包。

第二层在发布会话，管的是四件不同的事：latestRequested（只有最新请求值得 prepare）、prepareRunId（主题切换会对同一 sequence 再跑一次 prepare，光靠 sequence 分不清新旧）、publishQueue（串行化 DOM 提交）、published（对外的完成信号）。

因为 onResult 内部有 await nextTick()，await 期间状态可能变，所以发布体在 await 前后各查一次时序：

 复制代码const publish = publishQueue.then(async () => {
    if (disposed || runId !== prepareRunId || raw.sequence !== latestRequested) return false    await onResult({ ...raw.result, html: preparedHtml })
    if (disposed || runId !== prepareRunId || raw.sequence !== latestRequested) return false    published = Math.max(published, raw.sequence)
    // ...
})

这些交错情形没法靠手工点击复现，但注入 deferred promise 之后全是毫秒级单测：「先回 seq2 再回 seq1，断言 onResult 只被调用一次且是 second，而两个 waiter 都 resolve」——这种用例跑一遍比开浏览器试十遍都靠谱。

七、XSS 防线在渲染层，不在净化层

值得单说一句：MarkView 没有引 DOMPurify。它的策略是渲染即净化——renderer 从不输出原始 HTML，所有文本走 escapeHtml，URL 走白名单闸门：

 复制代码const compactUrl = url.replace(/[u0000-u001Fu007Fs]+/g, '')
const protocolMatch = compactUrl.match(/^([a-zA-Z][a-zA-Zd+.-]*):/)
if (!protocolMatch) return trueconst protocol = protocolMatch[1].toLowerCase()
if (allowedProtocols.includes(protocol)) return true

先剥掉控制字符和空白再取协议——专门防 javascript:、javatscript: 这类绕过。链接白名单是 http/https/mailto/tel，图片收紧为 http/https 加上受限的 data:image/*;base64。

被拒绝时不是输出空 href，而是整体降级为纯文本 / alt 文本——测试里断言的是 javascript: 链接渲染成 <p data-source-line="1">bad</p>，连 <a> 标签都不留。

结语

三条可以带走的经验：

1. 线程划分看依赖，不看「重不重」——mermaid 不是因为轻才留在主线程，是因为它要 DOM；其余全部纯字符串的部分，无论轻重都该搬走。
2. 「不能 async」不是绝路——lex → 扫描需求 → 异步预加载 → 同步 parse，用一次拆分绕开了 marked renderer 的同步限制，顺手拿到了按需加载。
3. 一个属性撑起半个应用——data-source-line 只是个字符串属性，但滚动同步、搜索定位、任务勾选全挂在它上面；这种跨模块契约值得在生产方和消费方各写一遍注释，中间层一概不知情。