VitePress 构建时 Markdown 尖括号转义难题：从“Element is missing end tag”到自定义预处理插件

1. 当Markdown遇上尖括号：VitePress构建报错之谜

最近在给团队搭建技术文档站点时，我遇到了一个让人头疼的问题。每当Markdown文件中出现数学公式里的<T>泛型符号，或者示例代码中的尖括号时，VitePress就会在构建时抛出"Element is missing end tag"的错误。这就像是你想写个简单的数学表达式1 < 2，结果系统却认为你在写一个不完整的HTML标签。

这个问题特别容易出现在以下几种场景：

• 技术文档中需要展示泛型代码示例（如TypeScript的Array<T>）
• 数学公式中包含不等式符号（如x < y）
• 需要展示XML/HTML标签的文档内容（如<div>的用法说明）

我最初尝试了最直接的方法——手动将尖括号转义为<和>。这确实能解决问题，但每次写文档都要手动转义实在太麻烦了，而且容易遗漏。更糟的是，当文档中同时包含需要转义的尖括号和真正的HTML标签时，情况就变得复杂起来。

2. 问题根源：Markdown解析的层层关卡

2.1 Markdown-it的解析流程

要理解这个问题，我们需要看看VitePress底层使用的markdown-it解析器是如何工作的。当VitePress处理Markdown文件时，它会经历以下几个关键步骤：

1. 原始文本输入：读取.md文件内容
2. HTML预处理：识别并处理HTML标签
3. Markdown解析：将Markdown语法转换为HTML
4. HTML后处理：对生成的HTML进行最终调整

问题就出在第二步——HTML预处理阶段。在这个阶段，任何看起来像HTML标签的内容（包括单独的<T>这样的泛型标记）都会被当作HTML标签处理。如果这些"标签"没有正确闭合，就会触发"Element is missing end tag"错误。

2.2 为什么常规解决方案无效

我最初尝试了几种常见解决方案：

1. 配置markdown-it：设置html: false可以禁用HTML解析，但这会同时禁用所有合法的HTML标签，这不是我们想要的。
2. 自定义markdown-it插件：尝试在文本渲染阶段转义尖括号，但由于解析顺序问题，错误在插件介入前就已经发生了。
3. 全局搜索替换：简单粗暴地替换所有尖括号，但这会破坏代码块中的合法内容。

这些方法要么不彻底，要么会引入新的问题。经过多次尝试，我意识到需要在更早的阶段介入处理——在Markdown解析开始之前。

3. 终极解决方案：自定义Vite预处理插件

3.1 插件设计思路

有效的解决方案需要满足以下几个条件：

• 只转义普通文本中的尖括号，保留代码块中的原始内容
• 在Markdown解析前完成处理
• 不影响正常的HTML标签功能

这引导我开发一个自定义Vite插件，在VitePress处理Markdown文件之前进行预处理。以下是完整的实现方案：

// .vitepress/config.js import { defineConfig } from 'vitepress' import fs from 'fs' import path from 'path' // 转义Markdown中的尖括号，但保留代码块内容 function escapeMarkdownBrackets(markdownContent) { // 匹配代码块（包括内联代码和多行代码块） const codeBlockPattern = /```[\s\S]*?```|`[\s\S]*?`/g // 临时存储代码块内容 const codeBlocks = [] // 用占位符替换所有代码块 const contentWithoutCodeBlocks = markdownContent.replace( codeBlockPattern, (match) => { codeBlocks.push(match) return `__CODE_BLOCK_${codeBlocks.length - 1}__` } ) // 转义普通文本中的尖括号 const escapedContent = contentWithoutCodeBlocks .replace(/</g, '&lt;') .replace(/>/g, '&gt;') // 恢复代码块原始内容 return escapedContent.replace( /__CODE_BLOCK_(\d+)__/g, (_, index) => codeBlocks[index] ) } // 自定义Vite插件 const markdownBracketEscaper = { name: 'markdown-bracket-escaper', enforce: 'pre', // 确保在其他插件前执行 async transform(code, id) { // 只处理Markdown文件 if (!id.endsWith('.md')) return null try { // 读取文件内容 const rawContent = await fs.promises.readFile(id, 'utf-8') // 执行转义处理 const escapedContent = escapeMarkdownBrackets(rawContent) return escapedContent } catch (err) { console.error('处理Markdown文件出错:', err) return code // 出错时返回原始内容 } } } export default defineConfig({ markdown: { config: (md) => { // 保留其他Markdown配置 md.set({ html: true, // 仍然允许真正的HTML标签 breaks: true, linkify: true }) } }, vite: { plugins: [markdownBracketEscaper] // 注册我们的插件 } })

3.2 关键实现细节解析

这个解决方案有几个精妙之处值得注意：

1. 代码块保护机制：使用正则表达式/```[\s\S]*?```|[\s\S]*?``/g`可以同时匹配多行代码块和内联代码。在转义前先将它们替换为占位符，处理完后再恢复，确保代码内容不受影响。

2. 精确的转义时机：通过设置enforce: 'pre'，确保我们的插件在Vite处理流水线的最早阶段执行，这样就能在markdown-it解析前完成必要的转义。

3. 错误处理：插件包含完整的错误处理逻辑，即使处理过程中出现问题，也会返回原始内容，避免构建过程完全中断。

4. HTML兼容性：保持html: true配置，确保文档中合法的HTML标签仍能正常工作。

4. 进阶技巧与优化建议

4.1 处理更复杂的场景

在实际使用中，你可能会遇到一些更复杂的情况：

1. 数学公式中的特殊符号：如果你使用KaTeX或MathJax渲染数学公式，可能需要额外处理公式中的特殊符号。可以在插件中添加对公式块的识别：

const mathBlockPattern = /\$\$[\s\S]*?\$\$|\$[\s\S]*?\$/g

2. 自定义容器中的内容：VitePress的自定义容器（如::: warning）可能需要特殊处理。可以通过扩展正则表达式来识别这些块：

const containerPattern = /:::\s*\w+[\s\S]*?:::/g

4.2 性能优化考虑

对于大型文档项目，处理性能也很重要。以下是几个优化建议：

1. 缓存处理结果：可以添加简单的缓存机制，避免重复处理未修改的文件。
2. 增量构建：确保插件与Vite的增量构建机制良好配合。
3. 选择性处理：只对确实包含尖括号的文件进行处理，可以通过快速扫描内容决定是否需要转义。

4.3 测试策略

为确保插件的可靠性，建议为以下场景编写测试用例：

• 包含泛型符号的普通文本（如List<T>）
• 混合了HTML标签和需要转义符号的内容
• 各种类型的代码块（JavaScript、TypeScript、HTML等）
• 内联代码与多行代码块
• 数学公式块和自定义容器

5. 替代方案比较与选择

在最终确定这个解决方案前，我探索了几种不同的方法，以下是它们的优缺点比较：

1. 全局替换方案：

   • 优点：实现简单
   • 缺点：会破坏代码块中的合法尖括号

2. markdown-it插件方案：

   • 优点：符合Markdown生态系统惯例
   • 缺点：介入时机太晚，无法阻止初始解析错误

3. 预处理插件方案（本文方案）：

   • 优点：精准控制，不影响代码块
   • 缺点：实现相对复杂

4. 修改VitePress核心：

   • 优点：从根本上解决问题
   • 缺点：维护成本高，升级困难

经过实际测试，预处理插件方案在灵活性、可靠性和维护成本之间取得了最佳平衡。它不需要修改VitePress核心代码，可以随着项目升级而继续使用，同时又能精确解决我们的特定问题。