Hexo + MathJax 矩阵公式渲染修复完整方法

发表于 2026-05-24 分类于开发

目标

解决 Hexo 博客中 LaTeX 矩阵公式（如 bmatrix）被渲染成单行的问题，使多行矩阵正确显示为多行结构。

前置条件

Node.js 环境
已有的 Hexo 博客项目
使用 NexT 主题

环境安装

安装依赖

1	npm install hexo-filter-mathjax@0.3.1 mathjax@3.2.2 --save

站点配置

在 _config.yml 中添加：

mathjax:
  enable: true
  per_page: false
  tags: none

注意：tags 不要写成 mathjax，否则 hexo generate 时会报 ReferenceError: mathjax is not defined。

关闭 NexT 主题前端 MathJax

NexT 主题会在前端加载自己的 MathJax CDN，与服务端渲染冲突。在主题 _config.yml 中关闭：

math:
  mathjax:
    enable: false
  katex:
    enable: false

核心：矩阵行尾反斜杠数量

这是最容易踩的坑。hexo-renderer-marked 在处理 Markdown 时，会将行末的反斜杠数量减半：

源码写入	marked 处理后	MathJax 收到	结果
`\\`（2个 `\`）	`\`（1个 `\`）	触发 HTML `<br>`	❌ 矩阵单行
`\\\\`（4个 `\`）	`\\`（2个 `\`）	识别为 LaTeX 换行	✅ 多行正确

结论：非最后一行矩阵数据行尾必须写 4 个反斜杠 \\\\

正确写法示例

$$
X=
\begin{bmatrix}
1 & 2 & 3 & 4 \\\\    ← 非最后行：4个反斜杠
2 & 1 & 4 & 3         ← 最后行：无反斜杠
\end{bmatrix}
$$

$$
W_Q=
\begin{bmatrix}
0.1 & 0 & 0 & 0 \\\\
0 & 0.2 & 0 & 0 \\\\
0 & 0 & 0.3 & 0 \\\\
0 & 0 & 0 & 0.4
\end{bmatrix}
$$

下划线处理：operatorname

\text{FFN_State} 中的下划线在 MathJax 的 text 模式下不合法，会导致错误并 fallback 为纯文本。用 operatorname 替代：

场景	正确写法	错误写法
无下划线	`\text{LayerNorm}`	—
有下划线	`\operatorname{FFN_State}`	`\text{FFN_State}`

验证方法

本地预览

1	npx hexo server -p 4000

检查 mtr 数量

mtr 是 MathJax 的矩阵行元素，有几个 mtr 就有几行：

1	grep -o 'data-mml-node="mtr"' public/文章路径/index.html \| wc -l

多行矩阵应该 mtr ≥ 2。单行公式 mtr = 0 是正常的。

浏览器控制台验证

1 2	document.querySelectorAll('mjx-container').length // 总容器数 document.querySelectorAll('[data-mjx-error]').length // 错误数，应为 0

常见问题

矩阵还是单行显示怎么办？

检查矩阵数据行尾的反斜杠数量：

with open('source/_posts/文章.md') as f:
    for i, line in enumerate(f, 1):
        if '&' in line and line.rstrip().endswith('\\'):
            bs = line.rstrip().count('\\')
            print(f"line {i}: {bs} backslashes {'✓' if bs == 4 else '✗ NEEDS FIX'}")

输出应有 4 backslashes ✓，否则需要修复。

配置报错 `ReferenceError: mathjax is not defined`

检查 _config.yml 的 mathjax.tags 是否写成了 mathjax，应改为 none。

浏览器控制台有 `'_' allowed only in math mode` 错误

使用了 \text{FFN_State}，下划线不合法。改用 \operatorname{FFN_State}。

总结

修复 Hexo 矩阵渲染只需记住两件事：

4个反斜杠：非最后行行尾写 \\\\
operatorname：含下划线的标识符用 \operatorname 代替 \text

其他配置（hexo-filter-mathjax、关闭 NexT MathJax）只需设置一次，后续写矩阵公式时遵循上述格式即可。

目标