博客支持数学公式：静态博客加一段脚本的通用做法
更新于
让静态博客支持数学公式，通用做法只有三步：在页面头部引入一个渲染库的脚本和样式，告诉它认哪几种定界符，然后在文章里写第一条公式验证。Hexo、Hugo、Jekyll 的区别只在「这段脚本放进哪个模板文件」，渲染库本身的写法三者完全一样。下面先给三个生成器的位置对照，再按三步讲，最后列一张常用命令表和几个常见问题。
三个生成器放脚本的位置对照
| 生成器 | 放脚本的位置 | 说明 |
|---|---|---|
| Hexo | 站点根目录 scripts/ 下新建一个 js 文件，用注入器写进 head |
不改主题文件，换主题不丢 |
| Hexo（另一种） | 主题的布局模板里 head 那一段 | 文件名随主题不同，换主题要重加 |
| Hugo | layouts/_partials/math.html，再在 baseof.html 的 head 里引用 |
旧版本目录名是 partials |
| Jekyll | 站点根目录的 _includes/head.html |
用主题默认的 head 时，先把它复制出来再改 |
Hexo 的注入器写法如下，文件放在站点根目录的 scripts/math.js，生成时自动加载：
hexo.extend.injector.register("head_end", `
<link rel="stylesheet" href="/katex/katex.min.css">
<script defer src="/katex/katex.min.js"></script>
<script defer src="/katex/contrib/auto-render.min.js"
onload="renderMathInElement(document.body)"></script>
`);
Hexo 的主题各不相同，注入器绕开了主题文件，是换主题最省事的一种。
Hugo 的做法依据其文档「Mathematics in Markdown」一页（页面更新于 2026 年 8 月，核实日期 2026-09-27）：先在配置里打开 Goldmark 的 passthrough 扩展，让公式原样穿过 Markdown 转换，再用 math 参数决定哪些页面加载脚本。
[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)']]
[params]
math = true
三步接入
- 引入脚本：把 KaTeX 或 MathJax 的发布文件放进博客的静态目录，在上表的位置写 link 与 script 标签。静态目录在 Hexo 是
source/，Hugo 是static/，Jekyll 是站点根目录。 - 设定界符：默认配置两个库都不认单个美元符号。想用它，在配置里显式加上；不想和金额冲突，就只用
\(与\)。 - 写首条公式：新建一篇文章，写一行行内公式和一段独立公式，本地预览一遍。能看到排好的公式，说明前两步都对了。
首条公式建议选一条带分式和上下标的，比如等比数列前 n 项和，一眼就能看出分式有没有排出来：
S_n=\frac{a_1\left(1-q^{n}\right)}{1-q}\quad(q\neq 1)
常用命令速查
下面这些写法在 KaTeX 与 MathJax 里都能用，适合写博客时对照：
| 写法 | 输入方式 | 效果 |
|---|---|---|
a_1 |
行内 | 下标 a₁ |
q^{n} |
行内 | 上标 qⁿ |
\frac{a}{b} |
行内或独立 | 分式 |
\sqrt{x} |
行内 | √x |
\neq |
行内 | ≠ |
\le、\ge |
行内 | ≤、≥ |
\sum_{k=1}^{n} |
独立更清楚 | 带上下限的 ∑ |
\lim_{n\to\infty} |
独立 | 极限，n→∞ 写在下方 |
\left( … \right) |
行内或独立 | 随内容变高的括号 |
\quad |
行内或独立 | 一个字宽的空白 |
\text{当} |
公式里夹中文 | 直立的中文 |
\begin{cases} |
独立 | 分段函数的大括号 |
等比数列在 |q| < 1 时的求和极限，正好把表里的极限、分式、绝对值三种写法串在一起：
\lim_{n\to\infty}S_n=\frac{a_1}{1-q}\quad(|q|<1)
接入后常见的四种异常
- 下划线变成斜体：Markdown 把两个下划线之间的文字当成强调，
a_1和b_2之间的内容变斜、下划线消失。Hugo 用上面的 passthrough 能避开；Hexo、Jekyll 里可以在公式的下划线前加反斜杠写成a\_1，转换后页面上留下的正好是渲染库要的下划线。 - Jekyll 里单行也要写双美元符号：Jekyll 默认的 kramdown 用两个美元符号表示公式，放在段落中间就是行内公式，单独成段就是独立公式。
- 样式文件漏了：用 KaTeX 时没引入 katex.min.css，公式会重复显示一遍或错位。
- 只有首页不渲染：摘要是截取的，公式被截成半条就排不出来，给摘要设好分隔位置。
一套生成器配好之后，建议把等比数列那条式子留作测试文章，以后换主题、升级生成器时先看它还在不在。
延伸阅读
- 网页显示数学公式：MathJax 与 KaTeX 两种接入的选型与代码对照
- KaTeX语法：常用命令与渲染效果速查
常见问题
- 评论区里的公式会渲染吗？
- 多数情况下不会。评论系统一般在页面加载之后才把评论插进来，有的还放在独立的内嵌框里，正文那一次渲染已经结束，照不到这些内容。要让评论里的公式也显示，得在评论加载完成后再对评论区域调用一次渲染函数，能不能做取决于评论系统有没有提供加载完成的回调。