katex正确配置需严格遵循四点：一是css必须在js前引入以防字体加载失败；二是三文件cdn版本号须完全一致；三是rendermathinelement须显式配置delimiters以支持$...$等写法；四是必须设置throwonerror: false并按需加载js以避免空载和错误中断。

katex.min.css必须在katex.min.js之前引入

字体加载失败会导致所有符号显示为方块，这是最常见却最容易被忽略的顺序错误。浏览器解析CSS时会预加载KaTeX所需字体，如果JS先执行而字体未就绪，渲染就会降级为占位符。

正确顺序只有这一种：

• katex.min.css 放在 最顶部（或至少在任何 <script></script> 之前）
• katex.min.js 紧跟其后，且必须带 defer
• auto-render.min.js 在 katex.min.js 之后，同样加 defer

三者CDN链接的版本号必须完全一致（如 @0.16.10），混用 @0.16.8 和 @0.16.10 会导致 egin{aligned} 等环境静默不渲染——没有报错，但公式直接消失。

renderMathInElement必须显式配置delimiters

默认情况下，renderMathInElement 只识别 $$...$$ 和 [...]，但绝大多数Markdown生成器输出的是单个 $...$ 行内公式。不手动声明，这些公式就原样当纯文本显示。

推荐配置项（覆盖主流写法）：

• {left: "$", right: "$", display: false} —— 对应 $E=mc^2$
• {left: "$$", right: "$$", display: true} —— 对应 $$int_0^1 x^2 dx$$
• {left: "\[", right: "\]", display: true} —— 注意双反斜杠，对应 [a+b=c]
• {left: "\(", right: "\)", display: false} —— 同样要双反斜杠，对应 (f(x)=x^2)

漏掉 display: false 会导致行内公式强行独占一行，破坏段落流；漏掉转义反斜杠会让 ( 被HTML解析器截断，直接报错。

HTML Extract

使用 MinerU 从 HTML 页面和文件中提取内容，将 HTML 转换为保持标题、列表、表格及文本层次结构的干净、结构化 Markdown。F...

下载

throwOnError: false 是线上必选项

一个拼错的 cfrac（KaTeX 不支持，应为 dfrac）就会让整页公式停止渲染——不是局部出错，是后续所有公式全跳过。这不是bug，是默认行为。

必须传入 throwOnError: false，否则：

• 用户看到的是空白区域，而非红色错误提示
• 开发者无法从控制台定位问题（因为没抛异常）
• SEO内容丢失：搜索引擎抓取到的是原始LaTeX字符串

这个选项不影响渲染质量，只改变错误处理策略，对性能也无额外开销。

按需加载能省掉75KB空载资源

博客首页没公式却加载了 katex.min.js（约75KB），是典型浪费。真实场景中，90%页面根本不需要它。

轻量检测 + 动态加载更合理：

• 在 中只引入 katex.min.css（约20KB，不影响首屏）
• 用正则 /$$|$[^$]|\[|\(/ 扫描 document.body.innerHTML（比 .includes("$") 更准）
• 命中后再动态 appendChild 加载两个JS文件，再调用 renderMathInElement

注意：Vue/React等框架里不能等组件挂载完再插入 <script></script> 标签——得在首次渲染前就判断并注入，否则会错过SSR或hydration时机。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！