KaTeX 在 Node.js 环境中的安装、构建与模块化使用指南

KaTeX 在 Node.js 环境中的安装、构建与模块化使用指南

【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeX

本篇技术指南以官方文档 docs/node.md 为核心骨架，系统讲解如何在 Node.js 环境中安装 KaTeX、从源码构建定制产物、以 CommonJS / ESM 方式导入模块，以及在网页中正确引入 CSS、字体与 HTML5 doctype，并演示 mhchem 化学公式扩展的接入方式。读完本文，你将掌握从「安装依赖」到「源码级定制构建」再到「服务端渲染输出 HTML」的完整链路，可直接用于静态站点生成、服务端预渲染与构建流程集成等实战场景。

一、安装 KaTeX：npm / Yarn / pnpm 三种方式

KaTeX 是一个无运行依赖的 JavaScript 数学排版库，官方发布到 npm 生态。在 Node.js 项目中使用时，最直接的方式是通过包管理器安装。当前仓库 package.json 中的版本为0.18.2。

1. npm 安装

# 安装到当前项目的 dependencies npm install katex # 全局安装（便于命令行使用） npm install -g katex

2. Yarn 安装

yarn add katex # 或全局安装 yarn global add katex

3. pnpm 安装

pnpm add katex # 或全局安装 pnpm add -g katex

安装完成后，node_modules/katex/dist/目录下会包含完整的发布产物：katex.js（未压缩 UMD 构建）、katex.min.js（生产推荐）、katex.mjs（ES 模块构建）、katex.css/katex.min.css样式表、contrib/扩展目录以及fonts/字体目录。

说明：package.json中"main": "dist/katex.js"指向 CommonJS 入口，"types": "types/katex.d.ts"提供 TypeScript 类型声明，因此 KaTeX 开箱即支持 TypeScript 项目中的类型提示。

二、从源码构建 KaTeX

当需要定制转译目标或裁剪字体资源时，可以从当前仓库源码自行构建。构建需要三个前置条件：

• Git：用于克隆仓库；
• Node.js 22.13 或更高版本：构建脚本依赖较新的运行时能力；
• corepack：Node.js 官方随附的包管理器工具，需启用后才可运行pnpm。

1. 克隆源码并安装依赖

git clone https://gitcode.com/GitHub_Trending/ka/KaTeX cd KaTeX

接着启用 corepack、安装依赖并执行构建脚本：

corepack enable pnpm install pnpm build

pnpm build的完整流程定义在 package.json 的scripts.build字段中：先清空并重建dist/目录，再依次执行rollup -c（生成.mjsES 模块产物，见 rollup.config.js）与webpack（生成 UMD 的.js/.min.js产物及 CSS，见 webpack.common.js），最后运行 update-sri.js 写入 SRI 哈希。

2. 通过 BROWSERSLIST 控制转译与字体

构建过程会自动转译代码（transpile），并仅包含目标环境所需的字体文件，目标环境由 Browserslist 配置决定（可通过BROWSERSLIST环境变量覆盖）。例如，如果你正在为运行 Chrome 68 的 kiosk 终端开发 Web 应用：

BROWSERSLIST="Chrome 68" pnpm build

由于 Chrome 68 完整支持 ES6，此次构建不会产生任何转译代码；同时该浏览器原生支持 WOFF2 字体格式，构建产物将只包含 WOFF2 字体，大幅缩减体积。

从源码层面看，字体筛选逻辑位于 webpack.common.js：构建按「从最不支持到最支持」的顺序遍历字体数组['woff2', 'woff', 'ttf']，逐项查询caniuse-lite数据库判断 Browserslist 目标是否完整支持当前格式；一旦某格式被完整支持（isCovered置为true），后续更低效的格式便不再打包，从而实现「只保留目标浏览器可用的最小字体集合」。

3. 通过 USE_ 前缀环境变量强制包含 / 排除字体

你还可以用USE_(字体名)环境变量精确控制每种字体的去留：设为"true"强制包含，设为"false"强制排除。结合源码中的命名规则（字体数组元素woff2/woff/ttf经toUpperCase()转换），可用的变量名为：

# 强制只保留 WOFF2，排除 WOFF 与 TTF USE_WOFF2="true" USE_WOFF="false" USE_TTF="false" pnpm build # 强制包含所有格式（不依赖 browserslist 推断） USE_WOFF2="true" USE_WOFF="true" USE_TTF="true" pnpm build

在 webpack.common.js 中，覆盖逻辑为：override === "true"时强制使用；否则仅当override !== "false"且当前格式是「首个被目标浏览器覆盖的格式」时才使用。这一机制让开发者可以针对 CDN 策略、离线 kiosk 或特殊字体许可场景做精细的体积裁剪。

4. 在其它项目中使用本地构建产物

若希望把刚构建好的 KaTeX 安装到其他项目中使用，直接指定源码路径即可：

# 使用 pnpm pnpm add /path/to/KaTeX # 或使用 npm npm install /path/to/KaTeX

这样其他项目会通过路径协议引用本地构建产物，适合在 Monorepo 或离线环境中复用定制构建。此外，也可以从官方 Releases 页面手动下载打包好的katex.tar.gz/katex.zip归档文件（dist子命令会自动生成压缩包，见package.json中的dist:zip脚本）。

三、在 Node.js 中导入 KaTeX 模块

1. CommonJS 导入

KaTeX 以 CommonJS 模块形式导出，可使用require导入：

const katex = require('katex');

2. ECMAScript 模块导入

KaTeX 同时按条件导出 ECMAScript 模块：

import katex from 'katex';

两种导入方式的解析规则由 package.json 的exports字段定义：require条件指向./dist/katex.js，import条件指向./dist/katex.mjs，两者均附带./types/katex.d.ts类型声明。该exports字段同时声明了./contrib/auto-render、./contrib/mhchem、./contrib/copy-tex、./contrib/mathtex-script-type、./contrib/render-a11y-string五个扩展子路径，每个都有对应的.js与.mjs构建。

注意：ES 模块构建中包含 ES6 语法与特性，在较老的环境中可能需要自行转译后才能使用。

导入后即可调用模块中暴露的 API。以 katex.ts 的实现为证，核心渲染函数renderToString接收 TeX 表达式与选项对象，内部经过解析（parse）与构建（build）后返回 HTML 字符串：

const html = katex.renderToString('c = \\pm\\sqrt{a^2 + b^2}', { throwOnError: false, }); // '<span class="katex">...</span>'

若需在服务端把结果直接写入 DOM，可使用katex.render(expression, element, options)，它会将渲染节点作为子节点追加到指定元素。模块同时导出了ParseError（用于区分表达式错误与脚本错误）、version以及一系列以双下划线前缀的内部 API（如__parse、__renderToDomTree、__defineMacro等，详见 katex.ts 的导出列表）。全部可用函数与选项请参考 API 文档 与 选项文档。

3. 通过 CLI 命令行渲染（可选）

package.json的"bin": "cli.js"字段表明 KaTeX 还附带了命令行工具 cli.js：从标准输入读取 TeX、向标准输出打印 HTML。它内部直接调用katex.renderToString，并支持--input、--output、--macro-file等参数，适合在 Shell 脚本或 CI 流水线中做批量渲染。完整参数说明可参考 CLI 文档模板。

四、在网页中使用服务端渲染的 HTML

服务端（Node.js）渲染出的 HTML 字符串要正确显示在浏览器中，仍需满足三个配套条件：

1. 引入 CSS 样式表：链接katex.min.css，它定义了公式的布局、字体与颜色样式；
2. 提供字体文件：使 KaTeX 字体对客户端可用——样式表通过相对 URL 引用fonts/目录下的字体文件（如url("fonts/KaTeX_AMS-Regular.woff2")），因此fonts/必须与 CSS 放在同一层级；
3. 使用 HTML5 doctype：页面须以<!DOCTYPE html>开头。从 katex.ts 可以看到，当检测到浏览器处于 quirks 模式（document.compatMode !== "CSS1Compat"）时，渲染会被禁用并抛出ParseError。

关键要点：在纯服务端渲染方案下，无需在客户端引入katex.js——HTML 字符串已在服务端生成，浏览器只负责按 CSS 排版。完整的浏览器端集成细节（CDN 引入、defer/async加载、字体加载策略、Webpack 打包等）可参考 浏览器端使用指南。

五、在 Node.js 中使用 mhchem 化学扩展

mhchem 扩展 通过修改katex模块本身来追加功能：其核心实现 contrib/mhchem/mhchem.js 调用katex.__defineMacro("\\ce", ...)与katex.__defineMacro("\\pu", ...)，把 mhchem 3.3.0 的\ce（化学方程式）与\pu（物理量）命令注册进 KaTeX 的宏系统，并内置一套完整的化学语法状态机（ce/a/o/text/pq等，见文件后半部分的stateMachines定义）。

正因如此，在 Node.js 中启用 mhchem 只需先加载扩展模块，再照常调用渲染函数：

const katex = require('katex'); require('katex/contrib/mhchem'); // 修改 katex 模块，注册 \ce 与 \pu 宏 const html = katex.renderToString('\\ce{CO2 + C -> 2 C0}');

若项目使用 ES 模块，可通过条件导出路径katex/contrib/mhchem的import条目加载对应.mjs构建（见 package.json 的exports配置）。浏览器端加载 mhchem 时则需在katex.min.js之后、auto-render.min.js之前单独引入contrib/mhchem.min.js，且引入顺序不可颠倒。

六、常见问题与补充说明

• ES 模块需要转译吗？需要视目标环境而定。katex.mjs保留 ES6 语法，@babel/preset-env在 ESM 构建中按esmodules: true目标处理（见 babel.config.js），老旧浏览器/运行时需要额外转译。
• 如何缩小构建体积？组合使用BROWSERSLIST（控制转译范围与首种字体格式）与USE_WOFF2/USE_WOFF/USE_TTF（强制字体取舍），可以让产物只包含目标环境真正需要的代码与字体。
• throwOnError: false是什么？该选项让非法 TeX 输入以红色原样渲染而非抛错，错误信息作为悬停提示展示，详见 错误处理文档。
• 只做服务端渲染时客户端要放什么？只需 CSS 与fonts/目录，无需katex.js；若所有渲染都发生在服务端，客户端连 JavaScript 都可以省去。

上述安装、导入与渲染流程覆盖了 KaTeX 在 Node.js 生态中的主流用法。无论是用 npm / Yarn / pnpm 快速引入，还是借助BROWSERSLIST与USE_环境变量做源码级定制构建，抑或通过require('katex/contrib/mhchem')扩展化学公式能力，均可在 docs/node.md、浏览器端指南、API 文档 与 mhchem 扩展说明 中找到对应依据，并可直接结合本文的源码路径深入研读实现细节。

【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeX