KaTeX/KaTeX · 上手攻略

仓库：KaTeX/KaTeX
链接：https://github.com/KaTeX/KaTeX
分类：academic-writing
作者：Tom
更新：2026-07-14

这是什么

KaTeX 是一个 JavaScript 库，用于在网页上高速渲染 TeX 数学公式。与传统方案（最典型的是 MathJax）不同，KaTeX 采用同步渲染策略，无需等待页面重排，在浏览器端几乎瞬间输出印刷级数学排版效果。

它的数学排版内核基于 Donald Knuth 的 TeX——这意味着输出质量有保障，是学术写作场景下的「黄金标准」。

核心特性： - 速度快：同步渲染，不需要页面 reflow，保守估计比 MathJax 快 2–5 倍 - 无依赖：零第三方依赖，可直接打包进任何 Web 资源 - 服务端渲染：Node.js 下可预渲染 HTML 字符串，输出结果跨浏览器一致 - 支持主流浏览器：Chrome、Safari、Firefox、Opera、Edge 全兼容 - 部分 LaTeX 支持：覆盖大部分常用数学命令和宏，但不是 100% 完整（这点需注意）

解决什么问题

在网页中嵌入数学公式，传统方案要么慢（MathJax 需要加载大量 JS 并异步渲染），要么依赖后端服务（Codecogs 等外部 API 有延迟和可用性风险）。

KaTeX 解决的是「学术博客、文档、在线笔记、论文网站」中既要好速度，又要好质量的根本矛盾。

典型场景： - 静态网站博客（Hexo、Jekyll、Next.js 文档站） - 在线教育平台（数学、物理、机器学习课程） - 论文预印本网站（arXiv 类平台） - API 文档中嵌入数学说明

快速安装

CDN 引入（最快，无需构建）

<!-- HTML5 doctype 必须，否则可能渲染异常 -->
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/katex.min.css"
    integrity="sha384-AtrdNsnxl/75rvBneBVH7DtOvCxSVahR2zWqle1coBKd8DEmLoviqNeJSx64gNAs"
    crossorigin="anonymous">
</head>
<body>
  <!-- 加载 KaTeX 主库（延迟加载以加速页面渲染） -->
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/katex.min.js"
    integrity="sha384-AtrdNsnxl/75rvBneBVH7DtOvCxSVahR2zWqle1coBKd8DEmLoviqNeJSx64gNAs"
    crossorigin="anonymous"></script>

  <!-- 如需自动渲染页面内所有 math 元素，引入 auto-render 扩展 -->
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/contrib/auto-render.min.js"
    integrity="sha384-bjyGPfbij8/NDKJhSGZNP/khQVgtHUE5exjm4Ydllo42FwIgYsdLO2lXGmRBf5Mz"
    crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>
</body>
</html>

⚠️ 版本说明：当前 CDN 可见版本为 0.17.0（jsDelivr 记录），建议通过 npm 安装以获取最新版本。

npm 安装

npm install katex
# 或
yarn add katex

Python 端预渲染（服务端）

npm install -g katex  # Node.js 环境

核心用法

1. 直接渲染到 DOM 元素

import katex from 'katex';

// 渲染到指定 DOM 元素
const element = document.getElementById('math-target');
katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, {
  throwOnError: false  // 渲染失败时显示源码而非抛出异常
});

2. 生成 HTML 字符串（服务端渲染）

import katex from 'katex';

// 生成字符串，可直接嵌入 HTML
const html = katex.renderToString("E = mc^2", {
  throwOnError: false
});
// 输出: '<span class="katex">...</span>'

3. 行内公式与行间公式

// 行内公式（display: false）
katex.render("\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}",
  element, { displayMode: false });

// 行间公式（display: true，居中显示）
katex.render("\\sum_{n=1}^{\\infty} \\frac{1}{n^2} = \\frac{\\pi^2}{6}",
  element, { displayMode: true });

4. 自动渲染页面内所有 LaTeX 表达式

// 页面加载完成后执行
document.addEventListener("DOMContentLoaded", function() {
  renderMathInElement(document.body, {
    delimiters: [
      { left: "$$", right: "$$", display: true },   // 行间公式
      { left: "$",  right: "$",  display: false },   // 行内公式
      { left: "\\[", right: "\\]", display: true },
      { left: "\\(", right: "\\)", display: false }
    ],
    throwOnError: false
  });
});

5. 常用配置项

katex.render(expr, element, {
  displayMode: true,          // true=行间公式，false=行内公式
  throwOnError: true,          // 错误时抛出异常；设为 false 显示源码
  errorColor: '#cc0000',       // 错误时显示的文本颜色
  macros: {                    // 自定义宏
    "\\RR": "\\mathbb{R}",
    "\\f": "#1f(#2)"          // \\f{a}{b} 展开为 #1f(#2)
  },
  output: 'html',              // 或 'mathml'、'htmlAndMathml'
  strict: false               // 处理未知 LaTeX 命令的严格程度
});

典型适用场景

场景一：静态博客快速嵌入数学

在 Hugo/Next.js 文档站等静态站点中，直接引入 CDN 版本最省事。配合 auto-render 扩展，页面内所有 $...$ 和 $$...$$ 自动渲染，无需额外构建步骤。

场景二：学术论文预印本网站

自托管时，用 Node.js 预渲染公式为静态 HTML，绕过浏览器端 JS 加载慢的问题。预渲染结果天然 SEO 友好。

场景三：在线 Jupyter 风格笔记（悬停查看源码）

利用 throwOnError: false 在公式错误时显示源码，配合自定义 tooltip 实现「悬停查看原始 LaTeX」的教学效果。

坑与注意

坑点	说明
HTML5 doctype 必须	否则 KaTeX 布局可能错乱，页面顶部必须加 `<!DOCTYPE html>`
不是 100% LaTeX 兼容	某些高级宏包（如 `tikz`）不支持；复杂自定义命令需参考 Supported Functions 列表
字体需单独引入	CSS 和字体文件（woff2）必须与 JS 同目录引入，离线使用时注意打包
版本差异	不同版本支持的 LaTeX 命令集有差异，生产环境建议锁定版本（通过 hash）
auto-render 分隔符冲突	`$` 在正文中出现频率高，容易误触发，建议优先使用 `$$` 或 `\$` `\$` 分隔符
长公式换行	KaTeX 目前对公式换行支持有限，长公式建议在设计阶段就拆成多行

与同类对比

特性	KaTeX	MathJax 3	MathJax 2
渲染速度	⚡ 极快（同步）	较慢（异步）	最慢
输出质量	TeX 标准	TeX 标准	TeX 标准
包大小	~200KB（精简）	~500KB+	~500KB+
LaTeX 覆盖率	~90%	~95%	~95%
服务端渲染	✅ 支持	✅ 支持	✅ 支持
无依赖	✅	❌ 需要	❌ 需要
活跃维护	✅ 活跃	✅ 活跃	⚠️ 维护减少
许可	MIT	Apache 2.0	Apache 2.0

结论：对学术写作/文档类站点，优先选 KaTeX（速度快、无依赖）；如果遇到 KaTeX 不支持的 LaTeX 特性，退到 MathJax 3。

一句话推荐结论

需要在网页中快速、高质量渲染数学公式？选 KaTeX——速度快、包体积小、服务端渲染零门槛，是目前学术写作类站点的最优解。