MathJax 公式不渲染的主因是加载时机不当或 HTML 结构干扰，需确保 DOM 完成后加载、避免隐藏容器、动态内容须调用 typesetPromise() 重排，并注意光标恢复与性能节流。
MathJax 加载失败或公式不渲染的常见原因
多数情况下不是 MathJax 本身有问题，而是加载时机或 HTML 结构干扰了它的自动处理。MathJax 默认只扫描 document.body 中已存在的元素，如果公式是后续动态插入（比如用户在编辑器里实时输入），它不会自动重排；另外，若编辑器内容区域被包裹在 contenteditable="true" 的 div 或 textarea 里，而该容器未设 role="application" 或被某些 CSS 隐藏（如 display: none），MathJax 也可能跳过解析。
- 确保 MathJax 脚本在 DOM 渲染完成后加载，推荐用
defer属性或放在</body>前 - 避免把公式区域放在
display: none或visibility: hidden容器内——MathJax 会跳过不可见节点 - 若编辑器使用 iframe 沙箱模式（如 TinyMCE、CKEditor 5 的 classic 模式），MathJax 必须注入到 iframe 内部文档，而非父页面
在富文本编辑器中触发 MathJax 重新渲染的正确方式
编辑器内容变化后不能靠刷新页面，得调用 MathJax API 主动处理新增或修改的数学片段。核心是用 MathJax.typeset() 或更精准的 MathJax.typesetPromise()，后者返回 Promise，适合配合输入防抖或光标停留检测。
- 监听编辑器的
input或change事件（如 Quill 的text-change、TinyMCE 的NodeChange） - 每次触发前先清空旧的 MathJax 输出：MathJax 会在公式旁插入
<span class="mjx-chtml">，重复渲染会导致嵌套，建议先移除已有.mjx-chtml和.mjx-annotation - 调用
MathJax.typesetPromise([element])，传入具体包含公式的 DOM 节点（如editor.root.querySelector('.math-inline')），比全页重排更快更安全
区分行内公式与独立公式，避免解析冲突
MathJax 默认识别 $...$ 和 $$...$$，但很多编辑器（如 ProseMirror、TipTap）会把美元符转义或当作普通文本。更稳妥的做法是统一用自定义标记，比如用 ( ... ) 行内、[ ... ] 块级，并在 MathJax 配置中显式启用：
MathJax = {
tex: {
inlineMath: [['\(', '\)']],
displayMath: [['\[', '\]']],
processEscapes: true
}
};
- 禁用
processEnvironments: false（默认为 true），否则egin{equation}...end{equation}类环境可能被忽略 - 若编辑器支持语法高亮，提前把
\(和\[标记为 math token，防止用户输入时被错误格式化 - 注意反斜杠转义：用户输入
rac{a}{b}是对的，但若编辑器自动把替换为\，就会变成\frac，MathJax 将无法识别
性能敏感场景下的渲染节流与降级策略
实时渲染每敲一个字符就调用 typesetPromise() 会导致卡顿，尤其含多行公式时。实际可用「输入停顿 + 公式标记检测」双条件触发：
立即学习“前端免费学习笔记（深入）”；
- 用
setTimeout实现 300ms 防抖，仅当输入暂停且内容含\(、\[、$等特征时才启动渲染 - 对长文档，限制每次最多处理 5 个公式块，用
Array.from(elements).slice(0, 5)控制范围 - 提供手动刷新按钮（图标可设为
∑），并允许用户关闭自动渲染——有些移动端 WebView 对 MathJax 支持不稳定，降级为纯 LaTeX 文本显示更可靠
最易被忽略的是编辑器光标位置维护：MathJax 重排 DOM 后，原生光标常丢失。务必在 typesetPromise().then() 里调用 editor.restoreSelection() 类方法（各编辑器 API 不同），否则用户会频繁失焦。
