MediaWiki 数学公式渲染：SimpleMathJax 轻量部署与配置指南

1. 为什么要在 MediaWiki 里折腾 Math 公式如果你维护过面向理工科团队或教学场景的 Wiki大概率会遇到这个需求有人想写一段带积分、矩阵、希腊字母的推导过程结果发现默认编辑器里只能敲纯文本公式要么用图片贴上去要么用一堆 HTML 实体硬拼改一次就想砸键盘。我最早接手一个内部知识库时物理组的同事直接在讨论页里抱怨“写个麦克斯韦方程组比推导它还累”这就是典型的公式支持缺失。MediaWiki 本身对数学公式是有原生方案的早期靠 Math 扩展调用外部排版引擎渲染成 PNG但部署链路长、依赖多很多轻量环境根本跑不起来。后来社区里出现了基于前端渲染的方案SimpleMathJax 就是其中比较省心的一种它把渲染工作交给浏览器端的 MathJax 库服务端只负责把公式原文包一层容器不需要额外装排版服务也不需要编译二进制。换句话说你只要把扩展目录放进去、改一行配置公式就能在页面上正常显示。这个方案适合谁我总结下来是三类人一是自建 Wiki 的个人或小团队服务器资源有限不想为了公式单独维护一套渲染服务二是内容以教学、笔记、论文草稿为主公式更新频繁需要所见即所得的编辑体验三是运维基础一般希望配置步骤越少越好。它的核心价值就一句话用最小的部署成本让 MediaWiki 具备可编辑、可搜索、可复制的数学公式能力。下面我把自己从零搭起来、踩坑、调优的完整过程拆开讲尽量让第一次接触的人也能照着做下来。2. 方案选型为什么是 SimpleMathJax 而不是别的2.1 原生 Math 扩展的痛点在哪MediaWiki 官方那个 Math 扩展功能确实全支持 LaTeX 语法、能输出 MathML、还能做无障碍朗读。但它的部署门槛劝退了不少人。它依赖一个叫 Mathoid 的服务或者更老的 texvc 二进制前者要跑 Node.js 服务后者要装 LaTeX 发行版。我在一台 2G 内存的小机器上试过光装 TeX Live 就吃掉好几个 G 的磁盘编译一次公式还要等半天页面加载肉眼可见地卡。更麻烦的是版本兼容。MediaWiki 每次大版本升级Math 扩展的接口经常跟着变配置项一改之前调好的参数就失效。对于只想安安静静写公式的人来说这种维护成本完全不划算。所以当需求只是“把 LaTeX 渲染出来”时我倾向于绕开重型方案。2.2 SimpleMathJax 的工作机制SimpleMathJax 的思路很直接它不碰服务端渲染而是通过一个 MediaWiki 的标签扩展tag extension把math标签里的内容原样输出到一个带特定 class 的容器里然后在前端加载 MathJax 的 JavaScript 库由浏览器完成排版。整个链路里服务端只做字符串处理真正的计算发生在用户浏览器里。这样做的好处很明显部署简单不依赖外部服务公式是文本形式存在的搜索引擎和站内搜索都能抓到用户复制公式时拿到的是 LaTeX 源码粘到别处还能用。代价也有就是首次加载页面时要下载 MathJax 的脚本大概几百 KB不过现在浏览器缓存机制成熟第二次访问基本无感。另外它对老旧的 IE 支持不好但 2024 年了这个问题可以忽略。2.3 和其他轻量方案的对比市面上还有几种做法我简单列个表对比一下方便你判断。方案服务端依赖渲染位置部署难度适合场景原生 Math 扩展Mathoid 或 texvc服务端高大型站点、需要 MathMLSimpleMathJax无浏览器低中小站点、教学笔记图片贴公式无无极低公式极少、不介意不可编辑客户端脚本自写无浏览器中有定制需求的技术团队从表里能看出来SimpleMathJax 卡在“够用”和“省事”的平衡点上。图片方案虽然最简单但公式不能改、不能搜、放大还糊长期维护是灾难。自写脚本灵活但你要自己处理标签解析、缓存、版本升级投入产出比不高。所以对绝大多数中小规模 Wiki我推荐先上 SimpleMathJax等真有高性能或无障碍需求了再考虑迁移。3. 部署前的环境确认与准备工作3.1 确认 MediaWiki 版本和目录结构动手之前先做两件事。第一确认你的 MediaWiki 版本进到 Wiki 根目录执行维护脚本或者直接看includes/Defines.php里的版本常量。SimpleMathJax 对版本有一定要求太老的版本比如 1.25 以前可能不兼容新版扩展的注册方式。我一般建议在 1.35 及以上的 LTS 版本上操作稳定性和扩展生态都更好。第二搞清楚目录结构。标准安装下扩展放在extensions/目录配置文件是根目录的LocalSettings.php。你要有这两个路径的写权限。如果是虚拟主机或者容器环境确认一下 PHP 的执行用户对扩展目录有读取权限否则后面加载会报 500。提示改配置前先备份LocalSettings.php这个文件一旦写错整个站点直接白屏恢复起来很麻烦。3.2 获取扩展文件的几种途径获取 SimpleMathJax 一般有三种方式。最省事的是用 Git 克隆到扩展目录命令大概是这样cd /path/to/mediawiki/extensions git clone https://github.com/example/SimpleMathJax.git如果你不方便用 Git也可以下载打包好的压缩包解压后把目录重命名为SimpleMathJax注意大小写要和后面配置里引用的名字一致。还有一种是通过 Composer 管理但对 MediaWiki 扩展来说手动放置更直观出问题也好排查。我个人的习惯是克隆下来之后先看一眼目录里的extension.json或者老的SimpleMathJax.php确认入口文件存在。有些第三方打包的版本目录层级会多套一层导致 MediaWiki 找不到注册文件这是新手最容易踩的坑。3.3 权限与安全的基础检查扩展目录放好之后检查一下文件属主。Web 服务器用户常见的是www-data或apache需要对扩展目录有读权限但不需要写权限。如果你图省事给了 777短期能跑长期是安全隐患。正确做法是把属主设成 Web 用户权限设成 755 目录、644 文件。chown -R www-data:www-data /path/to/mediawiki/extensions/SimpleMathJax chmod -R 755 /path/to/mediawiki/extensions/SimpleMathJax另外确认一下 PHP 的allow_url_fopen之类的配置虽然 SimpleMathJax 本身不依赖远程请求但如果你的 MathJax 脚本打算走 CDN就要保证前端能正常访问外部资源。内网环境的话建议把 MathJax 库下载到本地改成本地引用避免外网不通导致公式一直转圈。4. 核心配置与参数详解4.1 在 LocalSettings.php 中启用扩展配置这一步是整个流程的核心。打开LocalSettings.php在文件末尾或者你习惯的扩展加载区加上这一行wfLoadExtension( SimpleMathJax );这行代码的作用是告诉 MediaWiki 去extensions/SimpleMathJax目录读取注册信息把扩展挂载进来。注意wfLoadExtension是较新版本的标准写法如果你用的是很老的 MediaWiki可能需要用require_once直接引入入口文件。加完之后保存刷新一个页面如果出现白屏或者报错多半是路径或权限问题回去检查目录名拼写。4.2 关键配置项逐个拆解SimpleMathJax 提供了一些可调参数写在wfLoadExtension之后。我把常用的几个列出来并说明每个参数背后的考量。$wgSimpleMathJaxConfig [ useLocalMathJax false, MathJaxUrl https://cdn.example.com/mathjax/tex-mml-chtml.js, config TeX-AMS_HTML, ];useLocalMathJax决定 MathJax 库是从本地加载还是从外部地址加载。内网或者对加载速度敏感的场景建议设为true然后把库文件放到扩展目录下的modules/里。MathJaxUrl是脚本地址走外部的话要保证这个地址稳定可达。config指定 MathJax 的配置预设TeX-AMS_HTML是最通用的支持大部分 LaTeX 数学语法。这里有个细节值得说MathJax 3 和 MathJax 2 的配置方式差别很大。SimpleMathJax 的不同版本可能默认引用不同大版本的库如果你发现公式渲染出来样式怪怪的或者某些命令不识别先确认库版本和配置是否匹配。我遇到过用 MathJax 3 的库却套了 2 的配置结果矩阵环境直接报错换成对应的配置就好了。4.3 缓存与性能相关设置MediaWiki 有页面缓存和解析器缓存扩展改动后有时候不生效是因为缓存没刷新。调试阶段可以在LocalSettings.php里临时关掉缓存$wgEnableParserCache false; $wgCachePages false;确认公式正常显示后再把这两行去掉或者设回 true否则站点性能会受影响。另外 MathJax 本身也有缓存机制浏览器会缓存脚本如果你更新了库版本记得让用户强刷或者改一下脚本地址加个版本号参数强制重新下载。注意生产环境不要长期开着$wgCachePages false高并发下数据库压力会明显上升。5. 实操从写第一个公式到批量迁移5.1 编辑界面里怎么写公式配置生效后在 Wiki 页面里就可以用math标签写公式了。比如写一个二次方程求根公式mathx \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}/math保存后页面上就会渲染成标准的数学排版。行内公式和独立公式的写法略有不同行内一般直接嵌在文字里独立公式可以单独成段。SimpleMathJax 对这两种情况都能处理具体取决于你用的标签属性和 MathJax 的配置。我建议团队里统一一下写法规范比如行内公式用\( ... \)还是math标签独立公式要不要加display属性。规范统一了后期批量处理和维护会轻松很多。我们当时定的是全部用math标签行内加inline属性这样搜索和替换都好操作。5.2 常见 LaTeX 语法的适配情况不是所有 LaTeX 命令都能在 MathJax 里直接用。基础的分数、根号、上下标、希腊字母、求和积分都没问题但一些宏包特有的命令比如\usepackage、\begin{document}这类文档级命令在网页环境里是不支持的。表格、多行对齐这些需要amsmath环境的要确认 MathJax 配置里启用了对应的扩展。我整理了一份常用语法的适配对照方便你快速判断LaTeX 写法是否支持说明\frac{a}{b}支持分数最常用\sqrt[n]{x}支持n 次根\sum_{i1}^{n}支持求和上下标正常\int_{a}^{b}支持积分\begin{matrix}支持需 ams 配置\begin{equation}部分编号行为依赖配置\usepackage不支持网页环境无此概念\includegraphics不支持图片用 Wiki 原生语法遇到不支持的语法通常的替代方案是用 MathJax 支持的等价写法或者拆成多个公式分别渲染。实在搞不定的退回图片方案作为兜底但要在页面上标注清楚方便后来人维护。5.3 批量迁移已有公式内容如果你的 Wiki 里已经积累了大量用图片或者纯文本写的公式迁移是个体力活。我的做法是先用站内搜索把所有包含公式特征的页面列出来比如搜\frac、\sum这些关键词然后逐个替换。替换时注意保留原有的上下文别把公式周围的说明文字弄丢了。对于图片公式如果原始 LaTeX 源码还在有些编辑器会存直接复制过来就行。如果只剩图片那就得靠 OCR 或者手动重打这种情况建议优先处理访问量高的页面长尾页面慢慢来。迁移过程中每改一批就抽查几个页面确认渲染正常别一次性全改完才发现配置有问题回滚都来不及。6. 踩坑实录与问题排查6.1 公式不渲染的几种典型原因公式显示成源码、显示成空白、或者一直转圈是最常见的三类故障。我按排查顺序说一下思路。第一看浏览器控制台有没有报错。如果是脚本加载失败多半是 MathJax 地址不通或者被浏览器的安全策略拦了。内网环境尤其容易出这个问题把库下到本地就能解决。第二看页面源码里math标签有没有被正确输出。如果标签还在但没渲染说明前端脚本没执行如果标签被转义成了 HTML 实体说明扩展没生效回去检查wfLoadExtension那行。第三看缓存。改完配置不清缓存看到的还是旧页面这个坑我踩过不止一次。6.2 渲染样式错乱的调整有时候公式能显示但字体大小、行距、对齐方式不对劲。这通常是 CSS 冲突导致的。你 Wiki 的皮肤可能定义了全局的字体和行高和 MathJax 生成的容器打架。解决办法是在皮肤的 CSS 里针对 MathJax 的容器类加一些覆盖规则比如设置font-size和line-height为inherit或者固定值。还有一种情况是公式和周围文字基线对不齐行内公式特别明显。这个可以通过调整 MathJax 配置里的displayAlign和linebreaks参数来缓解或者干脆把行内公式改成独立显示牺牲一点排版紧凑度换取可读性。6.3 性能与加载速度优化MathJax 脚本体积不小首次加载慢是客观事实。优化手段有几个开启浏览器缓存给脚本地址加长期缓存头用 CDN 加速如果外网可达只加载需要的组件MathJax 3 支持按需打包把用不到的字体和扩展去掉能省不少体积。另外如果页面公式特别多可以考虑延迟渲染等页面主体加载完再处理公式。MathJax 本身有这方面的配置项具体怎么调要看你的库版本。我的经验是一个页面公式超过五十个就要认真考虑性能问题了否则用户滚动时会明显卡顿。6.4 常见问题速查表现象可能原因排查方向公式显示为源码扩展未加载检查 wfLoadExtension公式区域空白脚本加载失败看控制台网络请求一直显示加载中MathJax 地址不通换本地库或检查网络样式错乱CSS 冲突检查皮肤样式覆盖部分命令不识别配置缺扩展调整 MathJax config改动不生效缓存未清关缓存或强刷页面这张表我贴在团队文档里新人遇到问题先对照查一遍能解决八成以上的常见故障。7. 进阶玩法与长期维护建议7.1 自定义宏与常用公式模板写多了会发现有些公式反复出现比如特定领域的符号定义、常用常数。MathJax 支持自定义宏你可以在配置里预定义一批\newcommand这样编辑时直接调用短命令就行既省事又统一。比如定义一个\R代表实数集全站通用改的时候只改一处。MediaWiki 这边还可以配合模板功能把复杂公式封装成模板调用时传参数。这对教学场景特别有用同一类公式换个系数就能复用。不过模板嵌套太深会影响解析性能适度使用就好。7.2 版本升级与兼容性跟踪SimpleMathJax 和 MathJax 库都会更新升级前先在测试环境验证。重点看两件事一是扩展本身和 MediaWiki 新版本的兼容性二是 MathJax 大版本升级带来的语法变化。MathJax 2 到 3 的迁移就有不少破坏性改动配置格式、加载方式都变了直接升可能让现有公式集体失效。我的做法是锁定版本非必要不升级。真要升先备份数据库和文件在副本上跑一遍全站公式的渲染测试确认没问题再切生产。测试用例可以挑几个包含复杂语法的页面覆盖分数、矩阵、积分、多行对齐这些场景。7.3 内容规范与团队协作技术方案搭好只是第一步长期可维护还得靠规范。我们当时定了几条公式一律用math标签不用其他变体复杂公式拆成多行每行不要太长变量命名统一避免同符号不同含义公式旁边尽量加文字说明方便搜索和非专业读者理解。这些规范写进编辑指南新人进来先读一遍。执行一段时间后公式相关的维护成本明显下降搜索命中率也上去了。说到底工具是为人服务的把使用习惯理顺了技术方案的价值才能真正发挥出来。我在多个 Wiki 项目里反复用这套方案从最初的磕磕绊绊到后来的十分钟部署完成最大的体会是别一上来就追求功能最全先跑通最小可用版本再根据实际需求逐步加配置。公式渲染这件事稳定比花哨重要得多。