我这两年有好几个项目都被数学公式渲染卡过脖子——文档站点、在线题库、课程笔记系统全都要跟公式打交道。最早图省事直接上 MathJax结果首屏加载时间稳定多出两秒以上页面一多连编辑器的输入都开始发飘。后来换成 KaTeX同样的文档站脚本体积直接降了一个数量级滚动和输入的手感完全不一样了。这篇文章就从头到尾聊聊我实际用 KaTeX 渲染数学公式的完整经历包括为什么选它、各种接入姿势、服务端渲染玩法、以及我踩过的那些坑。如果你正在做需要展示数学公式的网页或者被公式渲染的性能问题折腾过这篇文章应该能帮你少走不少弯路。从基础接入到高阶优化我都会讲确保不管是新手还是已经踩过坑的人都能找到自己需要的部分。1. 为什么最终选择了 KaTeX 而不是 MathJax1.1 一次页面性能优化的真实对比先说我自己做的一个模拟项目 X是一个在线习题系统题库里有大量包含数学公式的题目。第一版是后端直接渲染 HTML 片段前端引了 MathJax 来做公式渲染。刚开始题目数量少的时候没觉得有什么问题后来题库涨到几千道题问题就出来了。最直观的感受是页面加载。打开一个包含公式的页面MathJax 需要额外请求一大堆字体和配置资源首屏时间被明显拉长。而且它的渲染方式是扫描整个 DOM找到数学标记后逐段处理页面公式一多就会出现明显的延迟用户输入答案的时候输入框也跟着卡。后来换成了 KaTeX情况改善非常明显。KaTeX 的核心库加 CSS 加起来体量比 MathJax 小很多而且它不需要额外加载字体文件包默认使用 Web Font 或者本地系统字体渲染是同步完成的公式以 HTML 和 CSS 形式直接输出到页面上——本质上它就是纯字符串处理不涉及二次扫描和异步排版所以即使一页里有几十个公式渲染也是一瞬间完成的。1.2 性能之外KaTeX 的实际优势在哪里很多人光听更快可能没概念我用数据说话。我这边的模拟项目 X 实测过同样一段包含二十个复杂公式的页面MathJax 从页面开始解析到所有公式完成渲染大约需要 2-3 秒视浏览器而定。KaTeX 在同样的页面上的渲染基本在几十毫秒到一两百毫秒内完成差距是数量级的。除了性能KaTeX 还有一个对开发者特别友好的点它是纯同步渲染。MathJax 渲染完成后需要触发 reflow 和 re-layout如果你需要在公式渲染后精确测量元素尺寸或者做动画会非常痛苦。KaTeX 输出的是干净的 HTML 和 CSS渲染完成那一刻 DOM 就是最终形态后续做任何操作都不必担心布局被二次改变。KaTeX 的生态也很干净它支持大多数 LaTeX 数学命令和符号。虽然极少数高级命令不支持比如某些复杂的排版环境但对于日常的数学公式、物理公式、统计学公式覆盖率已经足够了。语法上跟 LaTeX 保持一致写过 LaTeX 的人基本零学习成本。2. 基础接入几种引入 KaTeX 的方式与适用场景2.1 CDN 直接引入适合原型和轻量项目最开始图省事我用的是 CDN 引入三分钟就能跑起来link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/katex0.16.9/dist/katex.min.css script defer srchttps://cdn.jsdelivr.net/npm/katex0.16.9/dist/katex.min.js/script这里有几个细节要注意。defer属性一定要加因为 KaTeX 的 JS 文件需要等待 DOM 解析完成后再执行加了defer能保证脚本不会阻塞 HTML 解析。另外 CDN 上的 CSS 和 JS 版本号要对应好版本不一致可能会出现样式错乱比如公式里的字母显示成异常的字形。CDN 方式适合的场景是快速原型、内部工具、小流量页面。它的优点是零配置、不需要构建工具缺点是首屏依赖外网 CDN 的可用性和稳定性而且没法做细粒度的按需加载。我自己的生产项目不建议一上来就用裸 CDN原因后面在性能优化部分会详细说。2.2 用 npm 包管理适合需要构建的项目正规一点的做法是用 npm 安装npm install katex然后在代码里按需引入。以我常用的 Vite 项目为例import katex from katex; import katex/dist/katex.min.css;这种方式的好处是 KaTeX 跟你的项目代码一起打包版本可控、资源本地化还能利用构建工具的 Tree Shaking只打包用到的函数。KaTeX 本身是 CommonJS 模块在 Vite 里可以正常引入不过要注意一点它默认会引用一些 Node.js 内置模块吗不会但有些构建配置可能需要处理 CSS 里的字体文件路径。在 Vite 里一般不需要额外配置就能跑起来但在某些老旧的 Webpack 配置里可能需要处理字体文件的 file-loader 规则。2.3 服务端渲染SSR接入首屏最快的方式KaTeX 官方提供了renderToString方法可以直接在服务端把 LaTeX 字符串渲染成 HTML 字符串然后随页面一起返回给浏览器。这样浏览器根本不需要等待任何 JS 执行只要是包含公式的 HTML 就已经是最终形态了。以 Node.js 环境为例const katex require(katex); const html katex.renderToString(c \\pm\\sqrt{a^2 b^2}, { throwOnError: false });我目前在模拟项目 X 的习题详情页里就是这么干的。后端处理习题数据时把题面里的 LaTeX 公式全部预先渲染成 HTML 字符串发布后页面直接输出公式部分零延迟。而且因为是纯字符串输出甚至连前端框架都不需要参与公式渲染那一层。2.4 浏览器端自动渲染模式适合动态内容如果你的内容是纯前端动态生成的比如用户输入了一段含公式的文本就需要用 KaTeX 提供的自动渲染扩展renderMathInElement。这个函数不在核心包里需要单独从 CDN 引或者 npm 引入import katex/dist/contrib/auto-render.min.js; // 或者在浏览器里直接引 CDN 版本然后调用const elements document.querySelectorAll(.math-content); document.addEventListener(DOMContentLoaded, function() { renderMathInElement(document.body, { delimiters: [ {left: $$, right: $$, display: true}, {left: \\[, right: \\], display: true}, {left: $, right: $, display: false}, {left: \\(, right: \\), display: false} ], throwOnError: false }); });注意delimiters配置的顺序很重要$$和$这类包含关系要放前面否则像$x$这种短定界符会被长定界符截断。我吃过这个亏当时配置里把$放在$$前面结果所有$$...$$内容都被$...$给提前截断了公式全部分裂成碎片排查了半天才找到原因。其实自动渲染模式的核心原理很简单它扫描给定的容器内的文本节点找出匹配的定界符把内部的 LaTeX 源码用katex.render()替换成渲染后的 HTML。但它有个性能上的坑——如果页面里的文本节点特别多比如整个 body 有几百个节点扫描一遍也会有可感知的耗时。所以尽量把renderMathInElement的容器范围缩小只扫包含公式的那一部分 DOM别动不动就传document.body。3. 进阶配置和实用玩法3.1 自定义宏定义省掉重复代码写数学内容多的人都会遇到这种情况文档里反复出现同一个复杂表达式比如某个物理符号组合\boldsymbol{F}_{\text{net}}。每次都写完整表达式代码就特别啰嗦。KaTeX 支持自定义宏在调用时传macros参数katex.renderToString(\\Fnet, { macros: { \\Fnet: \\boldsymbol{F}_{\\text{net}} } });我用得比较多的场景是给一系列自定义算子做简写比如偏微分、期望值、常见向量积之类的。这个功能不只是方便还能让整个文档结构更清爽——改一个宏定义所有用到的地方同步更新不用全局替换。有一点要注意宏定义里单参数形式比如\\dfrac{#1}{#2}KaTeX 是支持的但多参数宏可能在某些 ESLint 或 TS 类型检查下报错需要类型断言绕一下。还有宏定义重复了也没关系后定义的会覆盖先定义的这个行为跟 LaTeX 的\renewcommand有点像。3.2 strict 模式和 throwOnError 的合理配置KaTeX 默认遇到不认识的命令或者语法错误会直接 throw 一个异常并且渲染出醒目的红色错误文本。这在开发阶段是好事便于发现问题但到了生产环境就有点粗暴了——用户看到一条红色错误提示体验很差。推荐的生产配置katex.renderToString(latexSource, { throwOnError: false, strict: false, errorColor: #cc0000 });throwOnError: false表示出错时不抛异常只是把错误信息以普通文本形式输出出来strict: false是为了容忍一些 KaTeX 能处理但不完全符合 LaTeX 规范的写法。比如某些非标准命令在 LaTeX 里会警告KaTeX 默认也会警告但strict: false之后就直接当作普通文本处理不报警告。不过我建议开发环境里把throwOnError设成true。调试时让错误彻底暴露出来等上生产了再关掉。这个习惯帮我抓出过不少前端拼写错误比如\fraq少写了一个c正确是\frac开发环境直接红字显示一眼就看到。3.3 在 Markdown 渲染链路里无缝集成 KaTeX如果你在用 Markdown 写技术文档公式一般是这样的形式行内公式$f(x) x^2$ 块级公式 $$ \int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2} $$KaTeX 本身不解析 Markdown需要在 Markdown 渲染之后做一步公式转换。我用过的方案是先用 Markdown 解析库比如 marked 或 markdown-it把 Markdown 转成 HTML。对 HTML 字符串做正则匹配找到$...$和$$...$$块。调用katex.renderToString把匹配到的内容替换成渲染后的 HTML。其实这一步有个现成的轮子比如 markdown-it-texmath 插件原理就是这样。我早期自己写正则踩了几个坑比如公式里的$是用作货币符号的场景再比如行内公式里本身就包含$概率论里的条件概率P(A|B)倒是没事但真的遇到过 LaTeX 里本应转义的\$。后来我还是老老实实用现成的插件正则边界太容易出问题了。如果你用 remark / rehype 这套生态也有现成的插件可以接。思路都是一样的Markdown 先转 AST公式节点单独抽取出来渲染最后再放回 AST 里。4. 实操过程中踩过的坑与排查经验4.1 公式渲染后 CSS 样式被污染这是我最常遇到的坑——KaTeX 的 CSS 是带作用域类名的比如.katex和.katex-html。但如果你在全局样式里写了比较宽的 reset 规则比如对* { margin: 0; padding: 0; }或者对span统一设置了字体、颜色KaTeX 输出出来的一些布局元素就会被全局样式干扰。典型症状是公式里的字母间隙变宽、间距错乱、上下标位置偏移。排查思路是先打开 DevTools 看 Computed Style看是哪个样式覆盖了 KaTeX 的默认值。KaTeX 的 CSS 优先级设计得还行但如果你的全局样式用了!important那就会直接穿透。我的经验是给 KaTeX 渲染出来的容器加一层隔离.math-block { all: initial; }或者稍微稳妥一点在引入全局样式时显式排除 KaTeX 类名比如body :not(.katex) { /* 全局样式 */ }当然这个排除写法也有性能代价最优解还是规范自己的全局 reset 规则别写那种杀伤力太大的* {}选择器。至少我在做了 CSS reset 清理后这类问题基本绝迹了。4.2 字体加载的 FOUT 闪烁问题KaTeX 默认会用自己的字体KaTeX_Main、KaTeX_Math 等这些字体文件在首次加载时需要从 CDN 请求。如果你的页面在字体加载完成之前就渲染出了公式那公式会先显示成系统字体随后突然跳动成 KaTeX 字体视觉上就是一阵闪烁FOUT。解决思路使用fonts.googleapis.com还是本地化KaTeX 的字体文件可以跟着 npm 包走传到自己的 CDN 或静态资源服务器这样加载速度和稳定性都更好。使用display: none兜底我没这么干因为闪一下也可以用 CSSfont-display属性控制。我在生产环境实际采用的做法是把 KaTeX 的字体用 CSSfont-face定义font-display: swap保留这个属性控制字体加载过程中是否显示备用字体同时给公式容器设置一个最小高度减少字体加载完成前后的布局位移。4.3 公式内中文显示异常这是很多写中文技术文档的人会遇到的问题。KaTeX 默认字体不包含中文字形如果你在公式里写了中文比如\text{平均数}渲染结果往往非常难看甚至直接显示成方框。解决办法是给 KaTeX 的字形做 fallback.katex { font-family: KaTeX_Main, PingFang SC, Microsoft YaHei, sans-serif; }但要注意这个 fallback 是全局的会影响所有字母。我建议更精细地控制只给.katex .katex-mathml或.katex .katex-html里的文字设置 fallback避免英文数学符号的显示被中文字体干扰。实测下来配合\text{}命令的时候中文 fallback 比较可靠直接写裸中文不包\text{}则非常容易出现排版错乱所以我还是要求内容作者把中文统一包在\text{}里面。4.4 动态内容渲染时的标签闭合问题KaTeX 输出的 HTML 是嵌套结构如果你在一个切好的字符串片段上直接调renderToString有可能因为标签闭合不完整导致页面结构错乱。我就遇到过 v-html 方式绑定数据时公式 HTML 没被正确转义导致 Vue 的模板解析报错的情况。实际场景里我是在某次给某跨平台系统做移动端适配时接口返回的公式源码里带了未转义的和字符KaTeX 解析时按普通文本处理了但外层框架把它当 HTML 标签解析了整个页面的结构直接错乱。排查半天才定位到是待渲染的 LaTeX 字符串里包含不安全的 HTML 标签。解决办法是在渲染前对输入做 HTML 转义或者要求内容后台对公式里的特殊字符做转义。前端输出时使用textContent的方式或框架的{{ }}插值而不是v-html/dangerouslySetInnerHTML直接塞。但公式本身需要输出 HTML所以这不是个完全通用的解法。更靠谱的方式是渲染前先对公式字符串做一个校验过滤掉明显的 HTML 标签闭合尝试比如把script这类内容直接掐掉。KaTeX 有output: html和output: mathml两个模式默认情况下它自己会做一定程度的清理但不能完全依赖它处理所有边界情况。4.5 异步组件加载时公式未渲染在 Vue 或 React 项目里组件是异步加载的DOM 插入时机跟自动渲染的触发时机对不上会导致一部分公式没被渲染就永远停留在$...$源码状态。这个问题的本质是renderMathInElement扫描的是当前 DOM 里已存在的元素如果组件是在扫描之后才挂载的那它里面的公式自然不会被处理。解决方案也比较直接在异步组件挂载完成的生命周期钩子里对组件根元素单独执行一次renderMathInElement。如果组件内部又有二次异步加载的内容就要在内容加载完成后再次调用。我这边实现上封装了一个简单的工具函数每次数据到达后触发一次局部渲染效果稳定。5. 性能优化让公式渲染不拖慢页面5.1 从资源加载层面做减法公式渲染的性能不只是渲染本身还包括资源的加载和解析。前面提到 CDN 直接引入最简单但生产项目里我更推荐把 KaTeX 的资源放到自己的静态资源服务器上并配合构建工具做版本哈希。以 Vite 为例npm install katex在入口文件引入import katex from katex; import katex/dist/katex.min.css;Vite 打包时会自动把字体文件也拷贝到构建产物目录并给资源文件加上哈希。这个细节很关键——哈希化的文件名可以配合 CDN 做长期缓存用户第二次访问时直接命中缓存公式渲染几乎是瞬时完成。另外 KaTeX 本体压缩后大约 280KB含全部字体如果只是渲染少量公式可以考虑只引入核心的 JS不引入全量 CSS 和字体用系统字体兜底。但实测下来省不了太多因为 KaTeX 的公式结构依赖自己的 CSS 类名体系裁掉 CSS 容易引发排版问题收益有限。所以我一般还是全量引入 CSS但通过构建工具按需拆分字体子集来减小体积——不过这个操作比较复杂我在模拟项目 X 里也没做太深有兴趣的可以研究font-face的unicode-range切分。5.2 页面间跳转时的预渲染策略如果你做的是文档站每个页面都有公式那用户从页面 A 跳到页面 B 时如果页面 B 才去渲染公式还是会有可感知的等待。我的优化思路是在页面 A 加载完成后用浏览器空闲时间预取页面 B 的 HTML。拿到 HTML 后在后端就直接把公式渲染好服务端渲染前端只负责展示。这个方案的关键是服务端要跟前端保持同一个 KaTeX 版本和配置不然可能出现两端渲染结果不一致的情况。我现在的做法是统一封装一个渲染函数服务端和客户端都从同一个模块导入保证配置一致。5.3 渲染性能瓶颈的定位方法有时候页面慢不一定是公式的问题可能是懒加载、图片、字体等资源耦合在一起。我调试时用 Chrome DevTools 的 Performance 面板记录从页面开始加载到完全可交互的过程重点看 KaTeX 相关的脚本执行时间。KaTeX 的执行时间分布大致是解析 LaTeX 语法tokenizer parser占据 50% 左右。生成 HTML 结构占 30%。CSS 计算和布局占 20%。如果你的公式量特别大解析阶段的耗时是没法通过调整 CSS 优化的唯一有效的办法就是做缓存。KaTeX 没有官方缓存机制但你可以自己做一个简单的 Map 缓存const formulaCache new Map(); function renderFormula(latex, options) { const key latex JSON.stringify(options); if (formulaCache.has(key)) return formulaCache.get(key); const html katex.renderToString(latex, options); formulaCache.set(key, html); return html; }像模拟项目 X 的题库里不少公式是重复出现的缓存命中率还挺高的。这一招对海量公式的页面效果显著。提示缓存一定要把选项参数拼进 key 里否则换了一种显示模式取到的还是旧结果。5.4 异步渲染和优先渲染顺序的技巧如果你一个页面上有几十个公式全量同步渲染也不是不能接受但为了更好的体验我做过一个优化首屏只渲染视口内的公式滚到哪渲染到哪。实现思路也不复杂——用 IntersectionObserver 监听公式容器是否进入视口进入后再触发渲染。const observer new IntersectionObserver(entries { entries.forEach(entry { if (entry.isIntersecting) { const element entry.target; // 如果还没渲染过执行渲染 if (!element.dataset.rendered) { renderMathInElement(element, options); element.dataset.rendered true; } observer.unobserve(element); } }); });这个做法的收益在长文章页面里特别明显。比如一篇包含一百个公式的长文如果都在首屏渲染初始 JS 执行时间会明显拉高而 IntersectionObserver 方案可以把公式渲染压力平摊到滚动过程中用户几乎感知不到。6. 兼容性与扩展KaTeX 和其他工具的协作6.1 与 React、Vue 框架的配合KaTeX 本身是框架无关的核心 API 就是renderToString和render。在 React 里我一般封装成一个组件function Latex({ formula, displayMode false }) { const html useMemo(() { return katex.renderToString(formula, { displayMode, throwOnError: false }); }, [formula, displayMode]); return span dangerouslySetInnerHTML{{ __html: html }} /; }这里用useMemo缓存计算结果避免组件每次渲染都重新解析公式。在 Vue 里就写个计算属性或者用computed返回渲染后的 HTML。要注意的一点是这类组件输出的是 HTML 字符串直接dangerouslySetInnerHTML或v-html会有 XSS 风险所以一定要确保输入的公式是可信的。如果公式来源是用户输入前端得先做一层安全过滤至少把script、iframe这类标签剔掉最好用专门的 HTML 净化库处理。6.2 与 Markdown 编辑器的深度集成很多在线编辑器是基于 Contenteditable 或 ProseMirror 做的公式一般以占位符形式存展示时实时渲染。我做过的一个简易版思路是编辑器里公式源码以特殊标记存储比如[[katex]]...[[/katex]]展示时通过 DOM 事件触发局部替换。回到监测渲染——编辑器里常见的 bug 是光标位置错乱原因就是渲染后的 HTML 结构改变了 DOM 树结构。解决方案是给每个公式单独包一个容器用contentEditablefalse阻止光标进入公式内部只在容器外面做光标定位。这个小细节在写富文本编辑器的人那边几乎是必须的但我第一次实现时完全没意识到光标一靠近公式就直接跳走体验极其割裂。6.3 KaTeX 与文档生成管线的整合如果你用静态站点生成器比如某个基于 Markdown 的文档工具来发布技术文档公式渲染可以完全放到构建阶段完成Markdown 解析 - 提取公式块 - KaTeX 渲染成 HTML - 组装最终页面。这样浏览器加载到的就是纯静态 HTML公式零运行时开销。我在某个技术手册站上就是这么做的构建时调用 KaTeX产物是纯静态文件部署到任何地方都能直接访问公式显示跟文档服务端渲染效果完全一致不需要维护任何前端 JS 状态。这一个链路做下来其实也解决了前面提到的 CDN 不稳定问题——构建后所有资源都变成了本地静态文件用户访问时没有任何第三方依赖。这个方案对文档类站点来说是最推荐的做法。7. 只讲干货的总结与经验说实话用了 KaTeX 这么久我最直观的体会有三条第一性能差距是真实的而且是碾压级的。如果你的产品对首屏加载时间敏感或者页面公式数量很多KaTeX 基本是唯一的合理选择。第二KaTeX 的 API 设计非常凝练核心就两个函数。上手很容易但它的配置项像macros、strict、throwOnError这些要在实际项目里踩坑才能真正理解怎么设置。我的建议是开发环境保持严格模式生产环境放宽限制用户体验优先。第三别把渲染公式当成一个孤立问题。它跟构建流程、框架通信、XSS 防护、样式隔离全都缠在一起。我这边最后的经验是凡是内容可控、静态优先的场景能服务端渲染就服务端渲染能构建期渲染就构建期渲染。最后分享一个我自己一直在用的小工具思路——做一个统一的公式渲染封装层。我现在的做法是封装了 renderFormula、renderFormulaToElement、batchRenderFormulas 这几个 API内部统一处理缓存、错误兜底、配置合并。团队里任何人要渲染公式都走这一层接口不直接调 KaTeX 原生方法。这样后续升级 KaTeX 版本或者切换渲染引擎改动面都能控制在一个文件里不用满项目搜索替换。如果你正在搭新的文档站点、题库系统或者笔记应用我建议第一版就把 KaTeX 接上别等性能问题暴露了再换。换渲染引擎虽然是小事但你把已经渲染好的一堆 HTML 存量内容再迁移一次还是挺折腾的。提前用对工具后面省下来的时间拿来写内容多好。