MathJax实战：Web前端LaTeX公式渲染、配置与性能优化

1. 为什么要在Web前端引入MathJax：一个被低估的渲染痛点

做前端开发这几年，我越来越觉得"在网页里展示数学公式"这件事，是被大量开发者低估的技术点。很多同学遇到的需求场景其实非常普遍：在线教育平台要展示解题步骤、技术文档网站要描述算法推导、博客系统要输出机器学习公式、后台系统要导出学术报告……结果大家的第一反应往往是"直接贴图片不就行了"？图省事确实可以，但很快你就会发现图片方案有一堆问题：公式不可选中复制、放缩后模糊、修改不方便、搜索引擎抓不到内容、夜间模式适配困难。真正做过这个功能的人，都会最终收敛到一个结论——让Web前端原生支持LaTeX数学公式，用MathJax做动态渲染，这才是长久之计。

MathJax本质上是一个开源JavaScript渲染引擎，它能把用LaTeX、TeX或者MathML语法书写的数学公式，在浏览器里实时解析并变成高质量排版的可视化内容。它不依赖任何后端服务，不需要把公式预先转成图片，只要前端引入脚本，公式就是"活的"DOM节点，可以被选择、复制、读屏，甚至可以被CSS完全控制样式。这套能力解决的不只是"能不能显示"的问题，而是把数学内容的展示从"图片时代"推进到了"结构化时代"。

这篇文章我会从实战角度，完整拆解MathJax在Web前端落地过程中的集成方案、配置逻辑、性能优化与踩坑记录。无论你是刚接触前端的小白，还是已经在项目里被公式渲染折磨过的老手，下面这些内容都值得花十分钟认真过一遍。我会告诉你哪些配置必须做、哪些坑能绕开、哪些性能优化最立竿见影。

2. 集成前的核心概念准备：MathJax做对了什么

在动手写代码之前，先把MathJax的工作原理讲清楚，这对接下来的调试至关重要。我见过太多人一上来就复制粘贴官方文档的配置，结果出了问题完全不知道从哪里排查，根源就是没搞懂它内部的工作机制。

2.1 三类数学语言：LaTeX、TeX与MathML到底什么关系

很多人被这三个词搞晕，其实一句话就能捋明白：TeX是底层排版语言，LaTeX是建立在TeX之上的宏集（就是一套更友好的命令封装），MathML则是面向浏览器和语义结构的数学标记语言标准。MathJax三样都支持，但日常使用中最常写的还是LaTeX语法，比如$a^2+b^2=c^2$或者$$\int_0^1 x^2 dx$$。

你可以这样理解：LaTeX语法是给人类写的"数学简谱"，MathJax的任务就是把这个简谱实时翻译成浏览器认识的DOM节点和CSS样式。MathML更像是一种标准化的"数学交换格式"，如果你有结构化数学数据需要做无障碍适配，MathJax也能直接消费MathML输入。

2.2 渲染管线：从输入到输出的完整链条

MathJax的渲染过程大致分为三步：解析（把LaTeX字符串转成内部的数学表达式树）、转换（把表达式树映射为HTML DOM结构与CSS样式）、布局（计算尺寸并完成页面排版）。这套管线全部运行在浏览器端，意味着公式渲染的复杂度被完全前置到了客户端。

其中有个关键概念叫"延迟渲染"。MathJax不会一上来就把整个页面的公式全部渲染完，而是监听DOM变化，把需要处理的公式按块排队处理。这种设计让它在页面内容动态更新时（比如SPA里切换路由、用户输入新公式）也能保持响应性。理解了这条管线，后面讨论性能优化时你就能明白为什么会建议"减少不必要的重复渲染"。

2.3 为什么当前版本的MathJax更值得选

2025年还在被广泛推荐的是MathJax 3.x版本。跟前代相比，它的核心渲染层迁移到了TypeScript，并且引入了组件化架构。最直观的感受是：首屏渲染速度更快、内存占用更低、配置方法更现代，而且它不再依赖HTML的<script>标签注入样式，而是通过CSS变量等方式提供了更干净的样式隔离方案。

在具体项目里选择版本时，我建议直接走3.x，不要再碰2.x的老项目。2.x的配置方式（比如MathJax.Hub.Config）在3.x里已经完全不兼容了，如果你是在维护老项目，也建议规划升级迁移，长期收益非常明显。

3. 三种主流集成方式：到底选CDN还是模块化打包

MathJax的集成方式直接决定你后续的维护成本和性能表现。根据项目的技术栈和构建方式，我把它分成三条路线。

3.1 最省事的CDN方式：适合快速验证与静态页面

如果你的页面是传统多页应用、静态博客，或者只是一个需要快速展示数学公式的Demo，用CDN方式最直接。在<head>中引入一行脚本，配合简单的初始化配置就能跑起来。

<head> <script> window.MathJax = { tex: { inlineMath: [['$', '$'], ['\\(', '\\)']], displayMath: [['$$', '$$'], ['\\[', '\\]']] } }; </script> <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"> </script> </head>

这段配置放在脚本引入之前，MathJax在加载完成后会读取window.MathJax中的初始化参数。你只需要在正文里写$x^2$或$$x^2$$，页面打开后公式就会自动渲染。

CDN方式的最大缺点是依赖外部网络，内网部署或离线环境会直接失效。如果只是本地写文档或临时Demo，可以接受；如果是正式产品，请慎重。

3.2 模块化方式：符合现代前端工程化标准

对于使用Webpack、Vite、Rollup等构建工具的项目，强烈推荐直接把MathJax作为npm包安装，通过ES Module方式引入。

npm install mathjax

然后在你需要渲染公式的模块中这样使用：

import { mathjax } from 'mathjax'; import { TeX } from 'mathjax-full/js/input/tex.js'; import { CHTML } from 'mathjax-full/js/output/chtml.js'; import { liteAdaptor } from 'mathjax-full/js/adaptors/liteAdaptor.js'; import { RegisterHTMLHandler } from 'mathjax-full/js/handlers/html.js'; import { AllPackages } from 'mathjax-full/js/input/tex/AllPackages.js'; const adaptor = liteAdaptor(); RegisterHTMLHandler(adaptor); const tex = new TeX({ packages: AllPackages }); const chtml = new CHTML({ fontURL: '/fonts/mathjax/' }); const html = mathjax.document('', { InputJax: tex, OutputJax: chtml }); export function renderMath(content) { const node = html.convert(content, { display: false }); return adaptor.innerHTML(node); }

模块化方式的核心好处是按需组合：你可以只引入TeX输入组件而不要MathML、只选择CHTML输出而不加载SVG输出器，构建后的体积能被压缩到很小。更重要的是，渲染结果不再是全局函数对你的页面做"魔法操作"，而是你主动调用的一个纯函数，这对React、Vue等框架的受控组件模型非常友好。

3.3 框架封装：在React和Vue里的集成模式

在框架项目里，我更推荐自己封装一个轻量组件，而不是引入社区里可能维护不积极的大型封装库。以React为例，一个最小可用的公式组件大概是这样的：

import { useMemo } from 'react'; import { renderMath } from '../utils/mathRenderer'; export default function MathFormula({ children, display = false }) { const html = useMemo( () => renderMath(String(children), { display }), [children, display] ); return <span dangerouslySetInnerHTML={{ __html: html }} />; }

需要注意：React 19里dangerouslySetInnerHTML的使用没有变化，但对HTML字符串的清洗规则更加严格了，公式渲染出来的HTML结构一般是安全的，因为它只是数学排版，不包含可执行脚本。如果你实在不放心，也可以先通过DOMPurify做一遍过滤再注入，代价是额外的性能开销。

Vue侧的逻辑类似，核心就是把MathJax的渲染结果通过v-html绑定到节点上。这里要提醒一个要点：不要在模板里直接对公式文本做插值后再用MathJax全局扫描，那样会导致渲染时序难以控制。用主动调用渲染函数的方式，数据的流转完全由你掌控，不会出现"公式渲染了但绑定的数据还是旧的"这种诡异问题。

4. 手把手配置解析：一份可以抄作业的完整配置

光会引入还不够，MathJax的配置项非常多，80%的坑都出自配置。我整理了一份经过多轮实战验证的完整配置，每个配置项我都会解释它的作用和适用场景。

4.1 核心的定界符配置：决定哪些文本会被解析为公式

前面提到inlineMath和displayMath，这两个配置看似简单，实际暗藏很多细节。

window.MathJax = { tex: { inlineMath: [['$', '$']], displayMath: [['$$', '$$']], processEscapes: true, processEnvironments: true } };

processEscapes这个配置特别关键。如果不开启它，你在正文里写"价格是$100和$50"这样包含货币符号的句子，MathJax会穷追不舍地把100和当成公式头尾，导致排版错乱。开启后，\$会被转义为纯文本的美元符号，MathJax会跳过它。

processEnvironments控制是否解析\begin{...} \end{...}这类环境语法。如果你用LaTeX写过论文，应该对align、matrix、cases这些环境非常熟悉。默认开启即可，但要注意环境内的语法错误会导致整个渲染块失败，后面会细讲排查方法。

4.2 宏定义与扩展包：公式功能增强的关键

MathJax默认支持的LaTeX命令并不是完整的TeX全集，很多常用命令需要通过macros配置手动定义，或者依赖扩展包。

tex: { macros: { RR: '\\mathbb{R}', dd: '\\mathrm{d}', argmax: '\\operatorname*{argmax}' }, packages: { '[+]': ['boldsymbol', 'ams', 'newcommand', 'enclose'] } }

举个例子，很多数学写作者喜欢用\boldsymbol{x}来表示向量，但MathJax基础包里不包含这个命令，你需要显式加入boldsymbol包。ams包对应美国数学会的常用宏集，基本是数学公式写作的必需品。newcommand包让你能在配置里自定义宏，类似LaTeX的\newcommand，这个能力在需要统一符号风格时非常好用。

4.3 输出处理器的选择：HTML还是SVG

MathJax 3.X提供两种主要输出方式：CHTML（基于CSS + HTML）和SVG。CHTML是默认推荐，排版效果更接近原生字体，放大缩小不失真，而且支持浏览器的文本选择。SVG的优势在于不依赖浏览器对CSS的某些支持，兼容性更好，且生成的DOM更简单，对页面性能有一定帮助。

实际项目里怎么选？我的经验是：

4.4 渲染模式：自动扫描还是手动触发

MathJax 3.x默认是通过startup模块在页面加载后扫描整个DOM，把所有匹配定界符的文本都处理成公式。这个"自动渲染"模式在大多数场景下是方便的，但也带来一个问题：每次页面内容变化，你都得手动通知MathJax重新扫描。

window.MathJax = { startup: { typeset: false // 关闭自动渲染 } };

如果你在SPA里工作，强烈建议关闭自动扫描，改为完全手动渲染。这样做的理由很简单：自动扫描的机制是观察者模式的批量回调，在复杂应用中容易和你自己的渲染逻辑产生竞争条件，比如组件还没挂载完MathJax就开始扫描、扫描到的节点又被框架替换掉了等问题。手动模式虽然多写了几行代码，但数据流完全可控，排查问题时会省去大量时间。

5. 真实项目中的性能瓶颈与优化方案

公式渲染的性能问题，是区别"Demo能跑"和"生产环境稳定"的一道分水岭。我实测过很多方案，下面这几条优化建议是对收益影响最大的。

5.1 前置渲染还是即时渲染：两种策略的权衡

如果你的页面包含大量公式（比如一篇有50个公式的数学题解析文章），全部依赖浏览器端即时渲染会占用大量主线程时间，体感上就是页面卡顿、滚动不流畅。

对策之一是在构建阶段做预渲染。如果你用的是静态站点生成器，可以提前调用MathJax的Node.js版本，把Markdown或HTML中的公式全部转成最终HTML，这样浏览器端直接拿到渲染结果，完全不需要再跑MathJax。

npm install mathjax-full

然后写一个Node脚本，把所有需要渲染的HTML文件输入输出一遍。构建出来的页面天然拥有极佳的首屏性能。缺点也很明显：如果要支持"动态修改公式文本再重新渲染"，预渲染就帮不上忙了，只能用即时渲染。

真实项目中我见过的最佳实践是混合模式：首屏能预渲染的全部预渲染，后续用户交互产生的动态公式走即时渲染。用一个配置开关控制MathJax是否扫描特定容器，两块逻辑互不干扰，性能体验都兼顾到了。

5.2 减少重复渲染与节流处理

MathJax的每次完整渲染都是"解析+转换+布局"全过程，频繁触发会导致性能雪崩。比如用户在一个可编辑公式的输入框里连续打字，每敲一个字符就触发一次全量重新渲染，那体验会非常糟糕。

有效的做法是分层节流：把"用户输入原始LaTeX文本"和"触发MathJax渲染"这两件事彻底解耦。可以用lodash.debounce或者自定义定时器，确保在用户停止输入200~400毫秒后，才真正执行渲染。渲染完成后检查公式结果，如果和上一次相同则不更新DOM。

另一个容易被忽略的细节是：只渲染受影响的部分。不要每次让MathJax扫描整个文档，而是明确告诉它"这个区块内的公式需要（重新）渲染"。MathJax的手动渲染API支持这个范围控制，把粒度控制到"一个公式或一个段落"，比全局扫描快太多。

5.3 字体预加载与资源拆分

CHTML输出方式依赖MathJax内置的Web字体来获得完美排版。但字体文件如果不做预加载，页面首次渲染公式时会出现"字体闪烁"——公式先以普通字体显示，等字体加载完后才切换成数学字体，这个过程中的布局抖动非常影响观感。

解决办法是在页面<head>中加入preload与preconnect：

<link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin> <link rel="preload" href="/fonts/mathjax/woff-v2/TeX/MathJax_Main-Regular.woff" as="font" type="font/woff" crossorigin>

如果你使用自托管字体，这点尤其重要。对于模块化打包方式，还要注意按需引入字体文件，用到的字符集才加载，避免为了一个希腊字母引入整个字体包。

5.4 自定义CSS隔离与主题适配

MathJax生成的HTML结构有自己的命名空间（比如mjx-container），它内部的样式用的是em和百分比单位，理论上会自适应继承父级字体大小。但实际开发中你会发现，全局CSS里的* { box-sizing: border-box }或img { max-width: 100% }这类规则经常会给MathJax的容器带来意外影响。

我的建议是给所有公式容器加一个固定的隔离作用域：

.math-formula { font-size: 1.05em; line-height: 1.4; overflow-x: auto; overflow-y: hidden; padding: 0.2em 0; }

这里设置overflow-x: auto特别有用，因为极长的公式在窄屏幕上会被截断，加上横向滚动后至少保证内容可访问。如果你追求更好的响应式效果，可以在窄屏下整体缩小公式字号：

@media (max-width: 600px) { .math-formula { font-size: 0.9em; } }

6. 动态公式渲染的完整实现链路：从输入到展示

现在进入实战环节。这一节我完整展示一个支持动态公式渲染的最小前端模块，覆盖"用户输入LaTeX -> 校验 -> 渲染 -> 回显"的完整链路。

6.1 一个支持错误反馈的渲染模块实现

先设计一个渲染工具的API，让它既能渲染公式，又能在语法错误时返回可读的错误信息。

import { mathjax } from 'mathjax'; import { TeX } from 'mathjax-full/js/input/tex.js'; import { CHTML } from 'mathjax-full/js/output/chtml.js'; import { liteAdaptor } from 'mathjax-full/js/adaptors/liteAdaptor.js'; import { RegisterHTMLHandler } from 'mathjax-full/js/handlers/html.js'; import { AllPackages } from 'mathjax-full/js/input/tex/AllPackages.js'; import { STATE } from 'mathjax-full/js/core/MathItem.js'; const adaptor = liteAdaptor(); RegisterHTMLHandler(adaptor); const tex = new TeX({ packages: AllPackages }); const chtml = new CHTML({ fontURL: '/fonts/mathjax/' }); const doc = mathjax.document('', { InputJax: tex, OutputJax: chtml, options: { skipHtmlTags: ['noscript', 'style', 'textarea', 'pre', 'code'], includeHtmlTags: { br: '\n', wbr: '', '#text': '' } } }); export const renderMathToHtml = (latex, display = false) => { const math = doc.convert(latex, { display, endOfLine: '\\n', em: 16, ex: 8, containerWidth: 800, lineWidth: 1000000, scale: 1 }); return adaptor.innerHTML(math); };

关键在最后几步：doc.convert会解析传入的LaTeX字符串并生成渲染后的节点，adaptor.innerHTML则把内部DOM结构序列化成HTML字符串。如果公式有语法错误，MathJax默认会把错误信息以红色文本渲染进结果里，而不是直接抛异常，这其实是个特性：你可以在返回的结果中检测是否包含merror类节点来识别错误。

6.2 一个带校验机制的编辑器组件

接下来把这个渲染模块嵌到编辑组件里。这里的关键是"渲染结果预览"与"编辑器输入"分离，预览区实时展示转换后的HTML，输入区的原始文本保持用户书写自由。

import { useState, useRef, useEffect } from 'react'; import { renderMathToHtml } from '../utils/mathRenderer'; export default function LatexEditor() { const [latex, setLatex] = useState('x^2 + y^2 = z^2'); const [preview, setPreview] = useState(''); const timerRef = useRef(null); useEffect(() => { // 防抖处理，避免每敲一个字符就渲染一次 clearTimeout(timerRef.current); timerRef.current = setTimeout(() => { try { const html = renderMathToHtml(latex, false); setPreview(html); } catch (err) { setPreview(`<span style="color:red">公式解析失败: ${err.message}</span>`); } }, 250); return () => clearTimeout(timerRef.current); }, [latex]); return ( <div className="latex-editor"> <textarea value={latex} onChange={(e) => setLatex(e.target.value)} rows={3} className="latex-input" placeholder="输入LaTeX公式，例如: \frac{a}{b} + \sqrt{x}" /> <div className="math-formula math-preview" dangerouslySetInnerHTML={{ __html: preview }} /> </div> ); }

这个组件看起来简单，但包含了我反复踩坑后总结出来的三个关键设计：第一，useEffect只依赖latex字符串，MathJax每次只处理最新输入，不会出现时序错乱；第二，try...catch包裹渲染调用，即使MathJax内部抛错，也不会让整个React组件崩溃；第三，预览区挂在math-formula容器里，后面的CSS隔离规则直接生效。

6.3 公式与普通文本混排的实战细节

在实际的文章编辑器里，公式不会单独存在，而是和文字混在一起。处理这个场景的正确姿势是：不要自己写正则去切割文本里的$...$段，直接让MathJax处理完整段落文本，你只需要给MathJax传一整段混合文本就行。

const mixedText = '根据公式 $a^2+b^2=c^2$，可以推导出...'; const html = renderMathToHtml(mixedText, false);

MathJax会自己识别$定界符，把中间的内容当公式处理，其余部分保留原始文本。这个能力在处理"段落级渲染"时非常省心，也避免了自己实现正则带来的各种边界问题。

有一个特别容易踩的坑：当你传入的混合文本里包含HTML标签（比如你拿到的内容是富文本编辑器输出的带<span>标签的HTML），直接传给MathJax会导致标签被当作文本内容渲染出来。正确做法是先把纯文本从HTML中剥离，或者传入前先用实体编码转义掉HTML标签。

7. 不可回避的兼容性与无障碍细节

公式渲染做出来很容易，做"好"却需要考虑很多边缘场景。这里我挑几个最值得关注的点。

7.1 与Markdown解析器共用$符号的冲突

在技术博客场景里，公式标记和Markdown语法会打架。最典型的冲突是Markdown把$当作普通文本保留，MathJax又把它当作公式定界符，结果两者互相干扰。比如一段引用里包含美元价格，解析完后公式边界完全混乱。

我的经验是：在Markdown解析前，用占位符临时保护所有\$转义符；等Markdown转换完HTML后，再把占位符还原成$，最后把完整HTML交给MathJax做公式渲染。这样两条解析管线互不干扰，只要注意占位符的随机性（避免与正文内容冲突）就不会出问题。

7.2 无障碍支持：让公式被读屏软件正确朗读

MathJax在无障碍方面其实做得相当好，它会为每个渲染出的公式生成对应的ARIA标签。默认的HTML结构大致是：

<mjx-container class="MathJax" role="math" aria-label="a的平方加b的平方等于c的平方"> <mjx-assistive-mml> <math xmlns="http://www.w3.org/1998/Math/MathML"> ... </math> </mjx-assistive-mml> ... </mjx-container>

这个aria-label就是读屏软件朗读的内容。默认情况下MathJax会根据LaTeX语义生成英文朗读文本，比如把\sqrt{x}念成"square root of x"。如果你需要中文朗读支持，可以开启Speech插件并配置中文语言包，或者在aria-label上自行覆盖。

实际接入时注意：读屏场景不需要让用户逐个字符选择公式内部的结构，所以建议用CSS把公式自身设置为aria-hidden="true"并保留role="math"，避免读屏读出两遍内容。

7.3 CSP（内容安全策略）下的兼容配置

很多大型项目的生产环境都启用了CSP，MathJax的CDN版本因为依赖远程脚本和动态创建样式，常常会被CSP拦截。比较稳妥的方案是自托管所有MathJax资源，并在CSP规则中加入对应域名：

script-src 'self' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; font-src 'self' https://cdn.jsdelivr.net data:;

注意style-src中必须包含unsafe-inline，因为MathJax生成的公式样式以内联样式为主。如果你所在域名的安全策略不允许这样放宽，那么唯一的选择就是放弃CDN，使用模块化打包方式在构建期把样式和脚本一并处理。

8. 踩坑实录：这些年我调过的MathJax疑难杂症

再完整的配置说明，也不如真实踩坑记录里有价值的信息。这一节我把项目中高频出现的问题整理成一份排查指南，每一条都有对应的解决思路。

8.1 公式被"吃了"或者显示成乱码，通常不是MathJax的锅

新手最容易遇到的现象是：$x$写进页面后，整个$x$文本不见了，或者被渲染成了奇怪的符号。排查时要先分清是"解析阶段失败"还是"渲染阶段异常"。

• 如果公式文本原封不动出现在页面上，说明MathJax没有识别到定界符。请检查inlineMath配置是否生效、CDN是否成功加载、初始化配置是否放在引入脚本之前。
• 如果公式文本消失，说明MathJax识别了它但解析出错。打开浏览器控制台，通常能看到红色错误信息，提示具体哪个命令无法识别。比如常见的\begin{align}报错，多半是ams包没加载。
• 如果公式渲染出来了但样式异常（字体乱飞、位置偏移），那基本是CSS冲突或者字体加载失败。用开发者工具检查mjx-container的font-family是否指向了正确的MathJax字体。

8.2 动态渲染后新插入的公式一直没有显示

这个问题在SPA里出现率极高。核心原因是你用MathJax的自动扫描模式，而自动扫描只在初始加载时执行，后续动态加入的内容不会被重新扫描。

解决方式只有一个：改用手动渲染API。在你插入DOM之后，明确调用渲染方法：

const content = '<p>这是动态公式 $x^2$</p>'; document.querySelector('#target').innerHTML = content; MathJax.typesetPromise('#target');

注意typesetPromise返回的是一个Promise，如果你在React的useEffect里调用它，务必用try...catch包裹，否则异步错误会变成unhandled rejection。

8.3 配置了宏定义却不生效

我经常收到类似的反馈："我在配置里加了macros，但公式里用的自定义宏还是报错。"排查这类问题有几个容易忽略的点：

第一，宏定义必须在MathJax初始化配置时传入，如果你在页面加载后再修改window.MathJax对象里的tex.macros，是不会生效的。第二，宏的写法要准确：RR作为宏名会被当作控制序列\RR使用，不要在宏名中多加反斜杠。第三，包加载顺序有影响：如果你在macros里用了\mathbb，必须确保对应的ams包已在packages列表里，否则宏展开后依然会报错。

tex: { macros: { RR: '\\mathbb{R}' }, packages: ['base', 'ams', 'boldsymbol'] }

8.4 公式里的反斜杠被JavaScript字符串"消化"了

这个坑太经典了，几乎每个从string拼接公式的人都会遇到。JavaScript字符串里\b是退格符、\n是换行符、\t是制表符，所以当你写"\\frac{a}{b}"时，前面两个反斜杠在字符串解析后会变成一个\frac，这时候传给MathJax的文本其实是\frac{a}{b}，这没问题。但如果你写的是"\frac{a}{b}"，JavaScript会把\f解释成换页符，MathJax拿到的是一个完全损坏的字符串。

正确做法是统一使用模板字符串：

const formula = `\\frac{a}{b} + \\sqrt{x}`;

或者使用String.raw标签，让它不做转义处理：

const formula = String.raw`\frac{a}{b} + \sqrt{x}`;

这个差异在排查时非常隐蔽，因为控制台打印出来的字符串看起来"差不多"，但实际字符已经完全变了。处理用户输入时尤其要小心，用户从编辑器里复制过来的LaTeX文本通常带着原始反斜杠，如果你把它塞进JS字符串拼接里，很可能就被悄悄吃掉了一层。

8.5 字体文件加载失败导致渲染成方块

自托管部署时，一定要把MathJax的字体路径配置正确。CHTML输出的字体URL默认相对于你引入MathJax脚本的路径，如果你做了CDN转发或者静态资源目录迁移，字体路径会很容错。

排查方法很简单：打开开发者工具，找到渲染出来公式的网络请求，看一下字体文件的请求路径。404了就说明路径不对，调整包的fontURL选项，指向存放字体文件的真实地址。

9. 从能用到好用：进阶探索与最后的一些经验

到了这个阶段，MathJax的基本集成与调试对你不应再构成障碍。接下来你可以往更精细的方向挖掘：比如把公式渲染的能力封装成一套设计系统级的组件，让产品各处的公式风格高度统一；比如在Docs站点里做"复制为LaTeX"的按钮，点击公式就能把LaTeX源码复制到剪贴板——这非常受数学内容编辑者的欢迎；比如结合浏览器原生Intl能力做本地化的公式朗读，让无障碍体验更上一层楼。

我最近在做的一个方向是把MathJax渲染完全搬到Service Worker里，页面主线程只接收渲染完的HTML字符串，这样即使用户的机器再老旧，渲染100个公式也几乎不会阻塞UI。这个方案相比构建期预渲染，多了一个"动态请求也可以后台渲染"的好处，代价是要自己维护一套SW缓存和消息通信逻辑。

最后分享一个实践经验：任何涉及到MathJax的改动，不管是配置微调还是版本升级，都务必准备一个包含典型公式的回归页面。我自己的测试页固定包含以下几类公式：

• 一个行内公式：$a^2 + b^2 = c^2$
• 一个独立展示的分式：$$\frac{1}{x} + \frac{1}{y} = \frac{x+y}{xy}$$
• 一个多行环境：\begin{cases} x + y = 1 \\ x - y = 2 \end{cases}
• 一个带希腊字母和算子的公式：$\sum_{i=1}^{n} \alpha_i \hat{\beta}_i$
• 一个故意故障的公式：$\frac{1}{}$（用于验证错误处理）

任何一次升级后跑一遍这个页面，只要这几个公式显示正常、样式统一、错误提示友好，我基本就放心了。

MathJax的价值在于它让Web真正成为数学内容的优秀载体，而这个价值需要开发者扎扎实实把每一个配置、每一项优化、每一处兼容性都处理好，才能完整地释放给最终读者。希望这篇文章能帮你在这个领域少走几步弯路，让公式在浏览器里漂漂亮亮地立起来。