KaTeX 数学渲染实战：3 分钟跑通 5 个官方扩展-平芜编程栈

KaTeX 数学渲染实战：3 分钟跑通 5 个官方扩展

【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeX

📄 网页上写不出来的那个公式

你一定遇到过这种情况：技术博客要加一个分数，搜出来的方案第一个是 MathJax（老牌公式引擎）。它功能多，但首屏加载慢，页面排版还会跳。你真正需要的是 KaTeX 数学渲染——一个面向网页的轻量排版库。传进去 LaTeX 记号（用纯文本写公式的方式），拿回来渲染好的 HTML，快到无感。核心只负责"一条一条地渲染"，整页自动渲染、化学方程式这类常见需求，官方仓库里有一套扩展帮你接上。

⚡ 三分钟跑通第一个公式

head 里放两行引用，正文一行渲染，公式就出来了。脚本来自 CDN（放在网络上由浏览器直接取用，本地不用装任何东西）：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.18.2/dist/katex.min.css"> <script src="https://cdn.jsdelivr.net/npm/katex@0.18.2/dist/katex.min.js"></script> <script> // 把一条公式渲染进指定 div katex.render("x^2 + y^2 = z^2", document.getElementById("math")); </script> <div id="math"></div>

存成 index.html 用浏览器打开，不需要构建工具。跑通之后你会看到：指定位置出现数学字体的 x² + y² = z²，上标 2 稳稳悬在右上方，不再是干巴巴的一行文字。

🧩 4 个官方扩展：各管一段事

扩展都放在 contrib/ 目录里，按需取用，不需要的别引。下面 4 个是实际项目里最常用的。

引入 Auto-render：告别手动逐条渲染

核心 render() 只渲染你指定的那一条公式，页面里有几十条时，手写循环很痛苦。Auto-render（自动渲染扩展）按分隔符扫描页面文本，把公式原地渲染出来。

分隔符可配置，默认认 $…$ 和 $$…$$
可限定渲染范围，跳过无关区域
能忽略特定标签和类名

<script src="https://cdn.jsdelivr.net/npm/katex@0.18.2/dist/contrib/auto-render.min.js"></script> <script> renderMathInElement(document.body); </script>

渲染效果参考仓库测试用例的截图：

加载 MHChem：化学方程式带下标渲染

Auto-render 解决的是"多"，可公式一旦涉及化学这种特殊领域，核心语法就不够用了。MHChem 扩展实现了 \ce 和 \pu 两个命令，语法兼容 LaTeX 的 mhchem 宏包。

支持化学方程式与同位素写法
\pu 表示物理单位
兼容 mhchem 宏包语法

<script defer src="https://cdn.jsdelivr.net/npm/katex@0.18.2/dist/contrib/mhchem.min.js"></script>

输入 \ce{2H2 + O2 -> 2H2O}，得到下标和反应箭头都正确的标准方程式。

接入 Copy-tex：复制即得 LaTeX 源码

公式能显示了，可你想把它带走呢？直接复制渲染结果，剪贴板里是一堆乱码般的字符。Copy-tex 接管复制事件：复制公式后，剪贴板的文本内容变成带分隔符的 LaTeX 源码，HTML 内容不受影响。

内联与块级公式默认用不同分隔符
只选中部分公式也会复制整条
分隔符可在源码 copyDelimiters 里改

<script src="https://cdn.jsdelivr.net/npm/katex@0.18.2/dist/contrib/copy-tex.min.js"></script>

复制一条公式粘进笔记或聊天框，得到的是能直接再编辑的 LaTeX 代码。

加载 Mathtex-script-type：MathJax 老页面不改内容

前面三个都是新接入的场景。如果你要迁移老页面，还得处理 MathJax 的惯例：把公式写进 script 标签并声明 type="math/tex"。这个扩展就是识别这种标签并用 KaTeX 渲染，老内容一行不用改。

只需追加一行扩展脚本
标签里写公式，页面照常渲染
存量内容零改动

<script defer src="https://cdn.jsdelivr.net/npm/katex@0.18.2/dist/contrib/mathtex-script-type.min.js"></script> <script type="math/tex">x+\sqrt{1-x^2}</script>

加上扩展后，这些标签里的内容自动变成带根号和上标的公式。

另外还有一个 render-a11y-string 扩展，把公式转成屏幕阅读器（读屏软件）能念出来的文本，做无障碍时很有用。

⚠️ 我踩过的坑和解法

\ce 加载了却报未定义问题：mhchem 引入后，\ce 依然提示命令未定义。原因：脚本顺序错了。扩展必须在核心之后、auto-render 之前执行，defer 属性写法不一致会让执行顺序失控。解法：保持核心 → mhchem → auto-render 的顺序，三者的 defer 属性保持一致。

公式出来了，字体却是默认衬线体问题：公式显示正常，但看起来像系统默认字体。原因：katex.min.css 没引，或页面缓存了旧版 CSS 和新版 JS 不配套。解法：CSS 和 JS 锁定同一个版本号，硬刷新一次清掉缓存。

长页面公式多，Auto-render 卡一下问题：打开长文档，自动渲染时页面会顿一顿。原因：默认递归扫描整个元素的所有文本节点，代码块、评论区都在扫描范围内。解法：传入具体容器限定范围，用 ignoredTags 和 ignoredClasses 排除不需要渲染的标签。