代码高亮的正确位置:Highlight.js、Shiki 与安全 Markdown 渲染
本文目录
预览里仍显示 # 标题,首先说明 Markdown 解析没有得到预期输入,不是“缺一个高亮插件”。标题、列表和引用由 Markdown 解析器处理;代码高亮只处理代码块内部的语言标记。
建立清楚的流水线
原始 Markdown → 解析 → 代码块高亮 → HTML 净化 → 渲染。实际框架可能融合这些阶段,但安全边界不能丢失。重复转义会把标签显示成文字;未转义的用户内容则可能变成可执行 HTML。先定位数据在哪一层发生变化,再加插件。
Highlight.js 可以在浏览器与服务端使用;有语言标签时显式选择语言比自动猜测更可控。Shiki 适合把语法主题高亮放在构建或服务端,并按需要加载语言。不要把全部语言、主题和运行时都发送给每位读者。
服务端高亮示例
import { codeToHtml } from 'shiki';
const allowed = new Set(['javascript', 'typescript', 'json', 'css', 'html', 'bash']);
export async function renderCode(code, language) {
if (typeof code !== 'string' || code.length > 50_000) {
throw new Error('代码块过大');
}
const lang = allowed.has(language) ? language : 'text';
return codeToHtml(code, { lang, theme: 'github-light' });
}
这是高亮函数,不是完整 Markdown 渲染器。长度上限是示例预算,实际要结合文档大小、超时和机器资源。主题名、语言名应来自白名单,不能把用户字符串拼成任意模块导入路径。
常见固定主题与语言可使用可复用 highlighter,避免每个代码块重新初始化。高亮缓存 key 包含代码、语言、主题和渲染器版本;升级版本后不能继续误用旧 HTML。
Highlight.js 的浏览器边界
对于浏览器高亮,把源代码先作为 textContent 写入 code 节点,再交给库处理。不要拿用户内容直接设置 innerHTML,也不要对已经高亮过的节点反复处理。SPA 切换时只处理新插入的块,失败时保留纯文本代码。
自动语言识别有误判与计算成本,长日志、JSON 和纯文本最好显式标为 text 或指定语言。高亮器不应阻塞整篇文章打开,非必要部分可以延后处理。
净化不止是删 script
允许的 HTML 标签、属性、URL 协议和 iframe 来源都要有策略。代码高亮输出一般需要 span、class 和部分样式属性;配置净化器时先确认它保留必要主题能力,又不会放开任意事件属性。外部链接、图片和内嵌媒体也走同一套来源规则。
管理员编辑的内容仍可能含粘贴来的不可信片段,不能只在投稿场景净化。服务端与前端预览尽量共用解析配置,防止“编辑器看着正常,发布后结构完全不同”。
代码块的移动端样式
.article pre {
max-width: 100%; overflow-x: auto;
overscroll-behavior-inline: contain;
padding: 16px; border-radius: 10px;
}
.article pre code { white-space: pre; tab-size: 2; }
.article :not(pre) > code { overflow-wrap: anywhere; }
长代码在块内滚动,行内路径可以换行。复制按钮位于代码块标题栏,不覆盖第一行;复制源代码而不是着色后的 HTML。成功提示使用 aria-live,不打断阅读。
验收样本
同时放一份标题、嵌套列表、表格、公式、引用、未知语言、含尖括号字符串和超长 URL 的 Markdown。检查预览与发布页的 DOM 结构一致;代码中的 <script> 必须显示为文本。再测试中英混合、Emoji、移动端、深色主题和一百个代码块的初始化成本。
官方资料
资源发现来源:25 项前端资源清单。
实战:预览为什么把井号也显示出来
先查看真正交给解析器的字符串,不要只看编辑框。以下几种输入看上去相似,输出应当不同:
| 输入情况 | 正确判断 | 应处理的位置 |
|---|---|---|
# 标题 | 一级标题 | 正常交给块级 Markdown 解析 |
四个空格后接 # 标题 | 缩进代码块 | 若非用户本意,修复存储/导入缩进 |
围栏代码块里的 # 标题 | 原样显示代码 | 不应强行变成标题 |
| 反斜杠转义的井号 | 普通文本 | 尊重作者转义 |
| 用 JSON 保存的字符串还带外层引号 | 数据尚未解包 | 接口边界只解一次 JSON |
| 字符串包含字面量反斜杠 n | 尚未成为换行 | 修复序列化,不全局猜测替换 |
另外,parseInline 处理行内语法,不能替代整篇块级解析。若 DOM 已经有 h1,只是字号像正文,才应追查 CSS reset、作用域选择器或主题覆盖。若 DOM 只有 pre/code,先看输入缩进和围栏;若页面直接出现 <h1> 文字,检查 HTML 是否被当作 textContent 再转义。这些问题换一个高亮库通常无效。
只在文档开头移除一个编辑器带入的 BOM 是可解释的兼容;不要全局删除零宽字符、emoji 连接符或所有缩进。那些字符可能是正文和代码的一部分。下面示例只做换行统一与开头 BOM 兼容,保持其它内容不动。
一份可运行的服务端安全基线
先做“结构正确、危险 HTML 不执行、代码可读”的最小基线,再加主题、公式、图表和媒体。创建独立练习目录,使用项目选定并审查过的依赖版本,提交锁文件。在练习目录安装 marked 和 sanitize-html,把以下内容存为 render-markdown.mjs。示例使用 Marked 的实例 API,净化规则是正文需要的严格子集。
import { Marked } from 'marked';
import sanitizeHtml from 'sanitize-html';
const parser = new Marked({ gfm: true, breaks: false, async: false });
const limits = { document: 100_000, html: 1_000_000 };
export function renderMarkdownBaseline(source) {
if (typeof source !== 'string') throw new TypeError('正文必须是字符串');
if (source.length > limits.document) throw new RangeError('正文超过示例预算');
const normalized = source.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
const html = parser.parse(normalized);
if (html.length > limits.html) throw new RangeError('渲染结果超过示例预算');
return sanitizeHtml(html, {
allowedTags: [
'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'br', 'hr',
'blockquote', 'ul', 'ol', 'li', 'strong', 'em', 'del',
'pre', 'code', 'a', 'table', 'thead', 'tbody', 'tr', 'th', 'td',
],
allowedAttributes: {
a: ['href', 'title'],
code: ['class'],
ol: ['start'],
},
allowedClasses: { code: ['language-*'] },
allowedSchemes: ['http', 'https', 'mailto'],
allowProtocolRelative: false,
});
}
这里有意不接受图片、iframe、SVG、表单、样式或事件属性,也没有插入高亮生成的 HTML。相对链接仍可以存在,展示层需要指定可信的文档基址,不能拿投稿者的任意 base 标签决定解析结果。相对链接允许并不代表服务端可以去抓取目标地址;链接点击、附件代理与 SSRF 是不同的边界。
标注 language-javascript 只保存语言提示,不会自动变成有颜色的代码。想接 Shiki 时,在代码块渲染阶段调用前面的 renderCode,再对全部结果净化。Shiki 的样式与本例白名单不同,应该单独设计允许的 span/class/颜色策略;直接套本例会失去高亮样式。不要为了保留颜色就开放任意 style,更不能把高亮器输出拼到净化后的 HTML 后面。
同样可以在浏览器采用 DOMPurify,但运行位置与依赖不同:浏览器自带 DOM,Node 环境则需要受维护的 DOM 实现或服务端净化器。别把 DOMPurify 包本身当作 Node 已具备 DOM 的证明。净化库和解析器都要跟随安全更新,锁文件用于可复现安装,并不是永远不升级的承诺。
用同一个脚本检查结构和攻击样本
另存为 check-markdown.mjs,然后用 Node.js 运行它:
import assert from 'node:assert/strict';
import { renderMarkdownBaseline } from './render-markdown.mjs';
assert.match(renderMarkdownBaseline('# 标题'), /<h1>标题<\/h1>/);
assert.match(renderMarkdownBaseline(' # 标题'), /<pre><code># 标题/);
const quoted = renderMarkdownBaseline('```html\n<script>demo()<\/script>\n```');
assert.ok(quoted.includes('<script>'));
assert.ok(!quoted.includes('<script>'));
const unsafe = renderMarkdownBaseline(
'<script>demo()<\/script>\n\n[跳转](javascript:demo())\n\n<img src=x onerror=demo()>',
);
assert.ok(!unsafe.includes('<script'));
assert.ok(!unsafe.includes('javascript:'));
assert.ok(!unsafe.includes('<img'));
assert.match(renderMarkdownBaseline('| A | B |\n| - | - |\n| 1 | 2 |'), /<table>/);
这几项能发现结构退化与显式危险标签,不能替代真实 DOM、复杂 URL、浏览器差异和净化库自身的安全测试。应用还应设置合理的内容安全策略;不要把 CSP 当成允许输出未净化 HTML 的理由。异步高亮或插件在净化后继续改 DOM 时,也要重新检查是否跨越了这条边界。
缓存、异步预览和版本如何一起工作
高亮缓存至少包含原代码、规范语言、主题、解析/高亮器版本。最终 HTML 缓存还应包含净化策略版本、Markdown 插件配置及权限上下文。密码文章的正文不能放进公共页面缓存;解锁前也不能把正文藏在 HTML、JSON 数据属性或描述元数据里。缓存命中只是少算一次,不应绕过当前访问权限。
编辑时输入 A → B,A 的高亮可能最后完成。为每轮预览记录递增序号,只有当前序号可以更新 DOM;切换文档或卸载后让旧序号失效。文档大时把解析放到 Worker,配合大小限制、超时与终止,不要仅给一个 setTimeout 就声称计算能被中断:同线程同步解析会阻塞那个定时器。
单个代码块过大、未知语言或主题加载失败时,优先回退转义后的纯文本,并提示局部高亮不可用;Markdown 整体解析失败则保留草稿与错误状态,不把旧预览冒充最新结果。复制按钮读原代码;不能从包含行号、提示和按钮的容器 textContent 一把复制。
手机代码块:把横向滚动限制在块内
文章在 grid/flex 中时,祖先内容列先设置 min-width: 0;仅给 pre 写 max-width: 100% 可能挡不住祖先的最小内容宽度。长行保留缩进并在块内横滚,表格另有自己的滚动容器,避免整篇文章出现第二条横向滚动条。代码字体不应为了塞下内容缩小到无法阅读。
标题栏可展示语言和复制按钮;按钮至少保留约 44px 触摸区域,使用实际 button、清楚的焦点框和简短成功提示。代码块被键盘聚焦时可以滚动;成功提示采用非打断式播报。深色主题要同时检查代码文字、选区、滚动条、行内代码和错误提示,不能只换背景色。
可按这组顺序验收:320px 长 JavaScript 行 → 中文注释与 emoji → 复制后逐字比对源串 → 深浅主题 → 站内换页后的新代码块 → 连续切换两篇文档 → 故意让旧高亮请求迟到。最后才统计首屏和一百个代码块的性能;不必为没有出现的代码预先下载全部语言包。
补充资料与文章分工
- Marked 用法与安全提示:解析器本身不负责净化 HTML。
- sanitize-html 配置:本例的服务端允许列表依据。
- Highlight.js 核心 API:区分字符串高亮与 DOM 节点高亮。
- Shiki Highlighter:按当前版本核对复用与加载策略。
以上是原创的故障定位和安全基线,不镜像资源清单里的外链正文。富文本的文档模型、导入导出与协作另见站内 编辑器文档契约,避免把两个专题写成重复的编辑器产品列表。
留言提交后直接公开,请友善交流。