代码块一片黑白:按需加载语法高亮,别让全站多背 1MB | 杨元超的世界

这篇写给「文章里贴了代码、读者却看不清关键字」的人:问题不是内容不够,而是 Markdown 渲染器(把 Markdown 文本转成页面元素的组件)把代码块当普通文本输出了。读完你能带走一段二十多行的代码块组件、按需注册语言(只引入真正用到的语言)的体积账,以及三个不用截图也能验证高亮生效的信号(其中两个可以自动判)。

下面这张表格按角色列出你能带走什么、从哪节开始读。

读者 带走什么 拿它做什么 从哪节开始读
用 Markdown 写技术文章的人 代码块高亮的接入方法 照第 4 节替换渲染器的 code 组件 2 → 4
在意首屏体积的前端 全量与按需的体积对比 用第 3 节的方法量自己的包 3
做验收的人 两个可自动化的判据 + 一个肉眼确认项 抄第 7 节的类名与 span 数检查 7

不适合不使用 Markdown 的内容站。约 11 分钟读完;需要你会一点 React、知道 Markdown 会转成 HTML;没配过语法高亮也能跟。

0 本文讲什么

Markdown 里的代码块,最终会变成一个 <pre><code> 元素。这个元素里有没有被拆开上色的片段,取决于渲染器有没有接语法高亮。这篇按「先看现象 → 再量体积 → 再接组件 → 最后验收」的顺序讲清整条链路。

下面这张表格是全文路线。

小节 讲什么 解决什么问题
1 为什么代码块是黑白的 找到缺的是哪一环
2 环境准备与最小示例 先看到高亮后的 HTML 长什么样
3 全量加载与按需加载 决定注册多少语言、怎么量体积
4 接到渲染器的代码块组件 让页面真的用上高亮
5 别名与未知语言 文章里写 ts、sh 也能对上
6 样式作用域与配色 让颜色只影响文章正文
7 三个验收信号 不用截图判断有没有生效
8 边界与演进 知道现在做不到什么

1 现象:代码块是黑白的

Markdown 渲染器是「把 Markdown 文本转成页面元素」的那层组件,它通常允许你按标签替换默认输出,例如换掉图片、链接、标题的渲染方式。这个站点之前只替换了图片组件(给图片加 referrerPolicy,处理图床防盗链),代码块没替换,于是 <pre><code> 按默认方式输出:类名还在(language-js 之类),但没有程序去读它,没有额外标签,也没有配色。

结构上的差别看下面这段示意。上面是修复前的输出,下面是高亮之后的输出,标签 <span> 是新增的。

修复前:
  <pre><code class="language-js">const n = 42;</code></pre>

修复后:
  <pre><code class="hljs language-javascript">
    <span class="hljs-keyword">const</span> n = <span class="hljs-number">42</span>;
  </code></pre>

所以缺的不是 CSS,而是一个「读类名 → 切词 → 给每段包标签」的步骤。token 指被单独上色的一段,例如关键字、字符串、注释、数字各算一个 token。

2 环境准备与最小示例

这一节先确认「高亮」到底产出什么,避免后面接组件时靠猜。环境是 Node.js 18 以上,装一个语法高亮库:npm i highlight.js@^11.12.0。示例代码如下,它会打印高亮后的 HTML 字符串与 <span> 个数。

const hljs = require('highlight.js/lib/core');
hljs.registerLanguage('javascript', require('highlight.js/lib/languages/javascript'));

const out = hljs.highlight('const n = 42;', { language: 'javascript' }).value;
console.log(out);
console.log('span 数:', (out.match(/<span/g) || []).length);

运行 node hl.js(保存成 .js,这个示例用的是 CommonJS 的 require),会看到 const 被包成 hljs-keyword、42 被包成 hljs-number,span 数为 2。注意入口是 lib/core:它只有框架,不含任何语言,所以每个要用的语言都必须单独引入并注册——漏了注册,高亮函数会找不到这门语言。

3 全量加载与按需加载

这一节解决体积问题。highlight.js 支持两种用法:引入完整包,或从 lib/core 起按需注册。完整包包含近两百种语言,打包后量级约 1MB(是否压缩、压到多少取决于构建配置);按需只加你真正用到的语言,每种通常几 KB。本站注册 11 种后是几十 KB 量级。这两个数都用你的打包产物核对,别照抄——版本和压缩方式一换,数字就不一样。下面这张表格对比两种加载方式。

方式 包含语言 体积量级 适合
完整包 近 200 种 约 1MB 站点语言不固定、不在乎首屏
按需注册 你自己列的清单 每种几 KB 内容语言可枚举的博客、文档站

本站按需注册了 11 种语言。这个数字是数出来的,不是猜的:把所有文章的代码围栏语言收集一遍去重,就是清单。

# 列出文章里出现过的代码块语言(+ 表示至少一个字符,排除闭合围栏)
grep -rho '^```[a-zA-Z0-9-]\+' posts/ | sort -u
# 输出形如 ```js / ```bash

行内代码是单个反引号,不会匹配上面的正则;闭合围栏是单独的三个反引号,也已经用 + 排除。剩下的若有拼写错误,人工核对一遍,就是注册清单。语言种类增加时,按需加载的收益会变小,这时可以改成「每种语言单独拆包,按需下载」。

4 接到渲染器的代码块组件

这一节解决「高亮函数写好了,页面没用上」的问题。渲染器会把块级代码包一层 <pre>,再把 className 传进来(通常形如 language-js);行内代码没有这个 language- 前缀。所以组件只返回 <code>,不要自己再包 <pre>,否则会嵌套出 <pre><pre>,把段落间距打乱。className 是 React 传给组件的类名参数;children 是代码文本。

示例代码如下,它接收类名与内容,返回带高亮标签的代码块。语言名用注册名输出(language-javascript),而不是文章里写的别名(language-js),这样样式和验收只需要认一套名字。

import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';
import bash from 'highlight.js/lib/languages/bash';
import plaintext from 'highlight.js/lib/languages/plaintext';
// 其余语言同样 import 并注册;ALIASES 里出现的都要注册
hljs.registerLanguage('javascript', javascript);
hljs.registerLanguage('bash', bash);
hljs.registerLanguage('plaintext', plaintext);

const ALIASES = {
  ts: 'typescript', js: 'javascript', node: 'javascript',
  sh: 'bash', html: 'xml', yml: 'yaml', text: 'plaintext',
};

export default function CodeBlock({ className = '', children }) {
  const lang = (className.match(/language-([\w-]+)/) || [])[1];
  if (!lang) return <code>{children}</code>;          // 行内代码

  const target = ALIASES[lang] || lang;
  if (!hljs.getLanguage(target)) {
    // 未知语言降级成纯文本;外层的 <pre> 由渲染器提供
    return <code className="hljs language-plaintext">{children}</code>;
  }
  const html = hljs.highlight(String(children).replace(/\n$/, ''), {
    language: target,
  }).value;
  return (
    <code
      className={`hljs language-${target}`}
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

把组件交给渲染器的方式因库而异,但都是「按标签名替换」:

// 在渲染 Markdown 的地方(不同库的字段名可能不同)
<Markdown components={{ code: CodeBlock }}>
  {content}
</Markdown>

两个细节:外层 <pre> 由渲染器提供,组件只返回 <code>,这样行内与块级都不会出现嵌套;dangerouslySetInnerHTML 在这里是必要的,因为高亮库返回的是 HTML 字符串,它只处理你仓库里的 Markdown,不要把它用在用户提交的内容上。

5 别名与未知语言

文章里写代码块时,语言名是人写的:ts、js、sh、yml 都很常见,而高亮库注册的是 typescript、javascript、bash、yaml。这一节把两套名字对上。下面这张表格是常见的别名对应关系。

文章里写的 注册的语言 说明
js / node javascript 同一个语言,不同习惯
ts typescript 需要先 import 并注册
sh bash 注册名是 bash
html xml 标记语言共用一套规则
yml yaml 少一个 a 的常见写法
text plaintext 明确不配色,但仍走同一套类名
拼错的名字 plaintext 降级成纯文本,保留排版

降级这一行很重要:未知语言不能让构建失败,也不能让代码块消失,只保留渲染器的 <pre> 等宽排版。这样作者写错语言名时,文章仍然能读,只是没有颜色。

6 样式作用域与配色

高亮只负责加类名,颜色要靠 CSS。这一节解决「颜色跑到导航栏去」的问题:把所有 token 样式限定在文章正文容器里,而不是全局。

hljs 输出的类名是稳定的(hljs-keyword、hljs-string、hljs-comment 等),下面这张表格是当前主题的四个主要颜色,调主题时用来对照,不是判据。

类名 含义 当前颜色
hljs-comment 注释 rgb(160, 161, 167)
hljs-keyword 关键字 rgb(166, 38, 164)
hljs-string 字符串 rgb(80, 161, 79)
hljs-built_in 内置对象/函数 rgb(193, 132, 1)

选择器统一写成 .markdown-content .hljs-keyword { … } 这种形式,只影响正文;背景色与内边距放在 pre code.hljs 上,避免每个 token 自己撑开间距。

7 三个验收信号

改完之后怎么确认真的生效?不用截图,看三个信号就够,按从易到难排列。下面这张表格是三个信号与各自的取法。

信号 怎么取 期望 强度
外层类名 选中文章里的代码块,看 <code> 的 class 同时有 hljs 和 language-<注册名> 弱:只证明组件被调用
内部标签数 数 <code> 里 <span> 的个数 与语言有关,纯文本块为 0 中:证明切词真的跑了
计算样式 看某个 span 的 color 不是继承的正文颜色 强:证明配色生效

实测数据可以做参照(取法:在浏览器开发者工具里选中 <code>,数其中 <span> 的数量):同一篇 bash 文章里的三个代码块分别是 16、5、14;一个 JavaScript 示例块是 62;标成 text 的块是 0。数量不用和这里一致,同一门语言、内容越长,切出来的 token 越多;要确认的是「不为 0 且随内容变化」。

类名这一项要特别注意:如果组件输出的还是 language-js 而不是 language-javascript,说明你用的是原始别名,样式表和验收脚本会各认一套名字,迟早对不上。

8 边界与演进

当前这套做法的边界很清楚:

下一步可以往三个方向走:把高亮移到构建期,直接产出带标签的 HTML,消除闪烁;语言多了之后,把每种语言拆成独立文件按需下载,避免主包变大;把「语言清单」和「文章里实际出现的围栏语言」做成构建检查,出现未注册的语言时给出警告,而不是静默降级。

你下一步能做什么

打开你文章页的一个代码块,数一下 <code> 里的 <span> 个数。如果是 0,说明高亮没接上;先照第 2 节在 Node 里跑通,再照第 4 节换渲染器的 code 组件。

这些内容来自哪里

这些内容来自一个静态博客渲染层的修改:文章里贴了大量命令与代码,读者反馈「看不出关键字」。排查发现渲染器只替换了图片组件,代码块走了默认输出。随后按站点实际出现的 11 种语言做按需注册,并用类名、标签数、计算样式三层验证。文中的 span 数量来自对已发布文章的实际统计,颜色值来自最终生效的样式表。

相关文章

本站缺少完全同主题的文章,以下是改动范围最接近的几篇。