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

MarkView 的右侧预览区域看似只是将 Markdown 转换为 HTML，但实际运行着一条跨线程、按需加载、带序号防乱序的复杂管线：marked 解析、KaTeX 公式渲染、highlight.js 代码高亮，全部在 Web Worker 中完成；而 Mermaid 图表因需要真实 DOM，被单独留在主线程处理。最终，这些内容串行提交到预览区。这条链路从一次键盘输入到 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: x\n--- 从源码中切除再解析，后面所有 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 `
${getSourceLineAttr(token)}>${escapeHtml(token.text)}
`
}

主线程侧有三个必须处理的问题。

其一，串行化处理。 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
    ? '
等待图表内容…
'
    : `
Mermaid 渲染失败：${escapeHtml(error?.message || String(error))}
`

其三，首屏不等待它。 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

先去掉控制字符和空白再提取协议——专门防范 ja va\0script:、ja va\t script: 这类绕过方式。链接白名单是 http/https/mailto/tel，图片收紧为 http/https 加上受限的 data:image/*;base64。

被拒绝时不是输出空 href，而是整体降级为纯文本 / alt 文本——测试中断言的是 ja vascript: 链接渲染成

bad