Hexo网站中完美显示LaTeX数学公式

Hexo 网站中完美显示 LaTeX 数学公式

最近在折腾 Hexo 博客，发现默认情况下 Markdown 里的 LaTeX 公式根本渲染不出来。查了一圈资料，踩了不少坑，这里把完整的解决方案记录下来。

1. 初始化一个 Hexo 网站项目

假设你已经装好了 Node.js 和 Git，先全局安装 Hexo：

1
npm install -g hexo-cli

然后初始化项目：

1
2
3
hexo init my-blog
cd my-blog
npm install

这样就有了一个最基本的 Hexo 站点，默认使用 landscape 主题。

2. 写一篇带 LaTeX 公式的文章，看看效果

在 source/_posts/ 目录下新建一个测试文件 latex-test.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
title: LaTeX 公式测试
date: 2026-09-03 10:00:00
tags: [latex, math]
---

行内公式：$E = mc^2$

行间公式：

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

启动本地服务预览：

1
hexo server

打开 http://localhost:4000 进入这篇文章，你会发现公式全部是乱码，$ 符号直接显示出来了，_ 和 \ 都被 Markdown 解析器当成了普通字符处理。

原因很简单：Hexo 默认的 Markdown 渲染器 hexo-renderer-marked 不支持 LaTeX 语法，它只会把 $...$ 当成普通文本。

3. 更换 Markdown 渲染器

要支持 LaTeX，需要把默认渲染器换成 hexo-renderer-pandoc。

先卸载默认的：

1
npm uninstall hexo-renderer-marked --save

再安装 pandoc 渲染器：

1
npm install hexo-renderer-pandoc --save

这个渲染器不是纯 JavaScript 实现的，它内部会调用系统里的 pandoc 命令来完成 Markdown 到 HTML 的转换。所以光装 npm 包还不够，系统里必须装有 Pandoc 才行。

4. 安装 Pandoc

macOS

用 Homebrew 安装：

1
brew install pandoc

装完验证一下：

1
pandoc --version

如果提示找不到命令，检查一下 Homebrew 的 PATH 是否配置正确。

Windows

有两种方式：

方式一：下载安装包

去 Pandoc 官网 https://pandoc.org/installing.html 下载 Windows 安装包（.msi 文件），双击安装，一路下一步即可。装完打开命令行验证：

1
pandoc --version

方式二：用 winget 安装

Windows 10/11 自带 winget 包管理器：

1
winget install --id JohnMacFarlane.Pandoc

装完同样验证一下版本。

5. 修改 Hexo 的 _config.yml

在站点根目录的 _config.yml 文件末尾添加 pandoc 配置：

1
2
3
pandoc:
  args:
    - --mathjax

这个参数告诉 Pandoc 在转换时使用 MathJax 引擎来处理公式。

6. 修改主题的 _config.yml

landscape 主题默认不会加载 MathJax 的 JavaScript 库，需要手动加上。

打开 themes/landscape/_config.yml，在文件末尾添加：

1
2
3
# MathJax
mathjax:
  enable: true

但这还不够，landscape 主题的模板里没有引入 MathJax 脚本的代码。需要手动修改主题的布局文件。

编辑 themes/landscape/layout/_partial/head.ejs，在 <head> 标签内添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<% if (config.mathjax && config.mathjax.enable) { %>
<script>
  MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']]
    },
    svg: {
      fontCache: 'global'
    }
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js" async></script>
<% } %>

这里用的是 MathJax 3 的 CDN，配置了行内公式 $...$ 和行间公式 $$...$$ 的识别规则。

7. 清理并重启

改完配置后，一定要清理缓存再重新生成，否则可能还是旧状态：

1
2
3
hexo clean
hexo generate
hexo server

打开刚才的测试文章，公式应该能正常显示了。行内公式 $E = mc^2$ 会变成斜体带上下标的漂亮排版，行间公式会居中显示并自动编号。

行内显示公式为： \(E = mc^2\)

而如果换行显示，则为： \[ E = mc^2 \]

8. GitHub Pages 部署脚本的升级

文章写完了，本地 hexo g 和 hexo s 都能正常渲染公式。但我的博客是放在 GitHub Pages 上自动编译的，推上去才发现 CI 直接报错：

1
FATAL spawnSync pandoc ENOENT

原因很简单：GitHub Actions 的 ubuntu-latest 运行器是干净环境，里面没有装 Pandoc。hexo-renderer-pandoc 在编译时找不到系统命令，整个构建就挂了。

修改 workflow

我的部署文件在 .github/workflows/pages.yml，原本长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
name: Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install
      - run: npx hexo clean && npx hexo generate

在 npm install 之前加一步安装 Pandoc：

1
2
3
4
5
- name: Install Pandoc
  run: |
    sudo apt-get update
    sudo apt-get install -y pandoc
    pandoc --version

完整 build 部分变成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: "20"

    - name: Install Pandoc
      run: |
        sudo apt-get update
        sudo apt-get install -y pandoc
        pandoc --version

    - name: Install Dependencies
      run: npm install

    - name: Build
      run: |
        npx hexo clean
        npx hexo generate

关于 pandoc_path 的坑

我本地是 Windows，之前在 _config.yml 里写过：

1
2
3
4
pandoc:
  pandoc_path: "C:/Program Files/Pandoc/pandoc.exe"
  args:
    - --mathjax

这个配置在本地没问题，但推到 CI 上反而会报错——因为 Ubuntu 上 pandoc 装在 /usr/bin/pandoc，写死的 Windows 路径根本不存在。

后来我把 pandoc_path 删掉了，本地靠系统 PATH 找到 pandoc（Windows 安装时勾选 Add to PATH 即可），_config.yml 里只留：

1
2
3
pandoc:
  args:
    - --mathjax

这样本地和 CI 用同一份配置，两边都能跑。

验证

推一次代码，进 Actions 页面看日志：

  1. Install Pandoc 步骤能看到 pandoc 3.x.x 的输出
  2. Build 步骤不再报 ENOENT
  3. 打开部署后的文章，公式正常渲染

如果之前部署过旧版本，建议在 GitHub Pages 设置里清一次缓存，或者直接重新触发一次 workflow。

小结

GitHub Pages 自动编译这件事，核心就一句话：CI 环境里缺什么系统依赖，就要在 workflow 里显式装什么。Pandoc 不是 Node 模块，npm install 不会帮你装，必须手动加一步 apt-get install pandoc。

踩坑记录

  1. pandoc 命令找不到：hexo-renderer-pandoc 在渲染时会调用系统命令 pandoc，如果没装或者不在 PATH 里，会直接报 spawnSync pandoc ENOENT。确保 pandoc --version 能正常输出。

  2. 公式里的下划线被吃掉：这是 hexo-renderer-marked 的经典问题，a_b 会被解析成斜体。换用 pandoc 渲染器后这个问题就没了。

  3. MathJax 加载顺序：MathJax 脚本必须放在页面底部或者用 async 加载，否则可能等不到 DOM 渲染完成就执行了，导致公式不显示。

  4. hexo clean 很重要：改渲染器或配置后，不清理缓存可能会出现各种奇怪的问题，比如公式还是乱码、样式没更新等。

总结

整个流程就是：换渲染器 → 装 Pandoc → 配 MathJax → 清缓存重启。核心是 hexo-renderer-pandoc 这个渲染器，它把 LaTeX 语法正确解析成 HTML，再由 MathJax 渲染成漂亮的数学公式。

如果你不想装 Pandoc，也可以考虑 hexo-renderer-markdown-it + KaTeX 的方案，纯 JavaScript 实现，不用装系统依赖，但公式语法兼容性略差一些。对于学术类博客，还是 Pandoc + MathJax 更靠谱。

软件开发 > 网站建设
#Markdown #Hexo #LaTeX #数学公式 #Pandoc #MathJax #GitHub Pages #CI/CD #静态网站 #博客搭建
Hexo网站中完美显示LaTeX数学公式
https://jycpp.github.io/2026/26-08-30-Hexo网站中完美显示LaTeX数学公式.html
作者
Jet Yan
发布于
2026年8月30日
许可协议