从 Markdown 到 HTML 的正确构建路径

在现代 Web 开发中，将 Markdown 转化为 HTML 是一个极高频的需求。无论是在构建博客系统、文档站点，还是处理用户评论，这一过程看似简单，实则暗藏玄机。许多开发者习惯于依赖简单的正则替换或过时的库，这不仅会导致渲染结果不符合标准，更可能引入严重的跨站脚本攻击（XSS）漏洞。

构建一个健壮的转换流程，核心在于选择正确的解析器以及实施严格的安全清洗。

解析器的选择与基础渲染

不要尝试自己编写正则表达式来解析 Markdown。CommonMark 规范包含了大量复杂的边缘情况，自制解析器几乎不可避免地会出现渲染错误。在 JavaScript 生态系统中，Markdown-it 是目前最稳健的选择。它遵循标准，性能优异，并且拥有庞大的插件生态，能够满足从基础文本到复杂数学公式的各种渲染需求。

Markdown-it 官方文档： https://markdown-it.github.io/

基础的转换代码非常直观，初始化实例后调用渲染方法即可。

javascript 复制代码

const MarkdownIt = require('markdown-it');
const md = new MarkdownIt();
const result = md.render('# Hello World');
console.log(result);

这段代码会将 Markdown 文本转换为标准的 HTML 标签。如果你的应用场景涉及 Cloudflare Workers 或其他 Serverless 环境，尽量在构建阶段或缓存层完成这一步，避免在每次请求时消耗计算资源。

至关重要的安全清洗

Markdown 语法原生支持内嵌 HTML 标签。这意味着如果不对输出结果进行处理，用户输入的恶意脚本将会被直接执行。这是 Web 应用中最常见的安全隐患之一。仅仅依靠 Markdown 解析器自带的 HTML 转义功能往往不够灵活，特别是当你需要允许部分安全标签（如 iframe 视频嵌入）通过时。

DOMPurify 是处理这一问题的行业标准工具。它能够剥离所有潜在的恶意代码，只保留安全的 HTML 结构。在 Node.js 环境中使用时，通常需要配合 JSDOM 来模拟浏览器环境。

OWASP XSS 防御备忘录： https://cheatsheetseries.owasp.org/

引入安全清洗后的处理流程如下。

javascript 复制代码

const MarkdownIt = require('markdown-it');
const createDOMPurify = require('dompurify');
const { JSDOM } = require('jsdom');

const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);
const md = new MarkdownIt({ html: true });

const rawMarkdown = 'Hello <script>alert(1)</script>';
const dirtyHtml = md.render(rawMarkdown);
const cleanHtml = DOMPurify.sanitize(dirtyHtml);

经过这一步处理，原本包含恶意脚本的输入会被净化为无害的内容，从而保护你的用户和站点安全。

样式注入与视觉呈现

转换生成的 HTML 只是纯粹的结构，没有任何样式信息。直接将其放入页面中，视觉效果会非常原始且难以阅读。为了提供良好的阅读体验，你需要为这些生成的标签应用 CSS 样式。

一种高效的做法是使用现成的 CSS 库，例如 github-markdown-css。你只需要引入该样式文件，并在包裹内容的容器元素上添加对应的类名。这种方式能够快速复刻 GitHub 的文档渲染效果，保证代码块、表格和引用等元素的视觉一致性。如果你使用 Tailwind CSS，官方提供的 Typography 插件也是极佳的选择，它允许你通过简单的类名控制所有子元素的排版细节。

GitHub Markdown CSS 仓库： https://github.com/sindresorhus/github-markdown-css

将转换逻辑、安全清洗和样式应用结合起来，你就拥有了一个完整且可靠的 Markdown 渲染管线。这不仅提升了开发效率，更从根本上解决了内容呈现的安全性和美观性问题。