企业官网建设流程全解析

1. 为什么要在自建知识库里折腾数学公式

如果你正在维护一个内部技术文档站、课程讲义库或者科研协作平台，用的又是 MediaWiki，那你大概率会遇到一个很具体的需求：页面上要能写数学公式。不是那种用图片贴上去的假公式，而是能编辑、能修改、能搜索、能随页面缩放而不糊的真公式。

MediaWiki 本身对数学公式的支持，历史上依赖一个叫 Math 的扩展，它背后要跑 TeX 渲染，还得配一堆字体和二进制工具。对于只是想安安静静写点带公式的文档的人来说，这套东西的部署成本偏高，尤其是在一些受限的运行环境里，装完一堆依赖之后还可能因为权限或者路径问题跑不起来。SimpleMathJax 这个扩展就是冲着这个痛点来的：它把渲染工作交给前端，用 MathJax 在浏览器里完成公式排版，服务端只需要把公式原文原样吐出来就行。

这个思路的好处很直接。服务端不用装 TeX 发行版，不用配字体，不用管渲染进程的权限，扩展本身也轻。代价是公式渲染依赖访问者的浏览器执行 JavaScript，首屏会有一个短暂的渲染延迟。对于绝大多数内部知识库、教学平台来说，这个取舍是划算的。

这篇文章面向的是需要自己动手把公式功能跑起来的人：可能是运维、可能是开发、也可能是负责搭建团队文档站的技术负责人。我会从扩展的获取、配置、公式写法、常见渲染故障排查，一直讲到怎么让公式在编辑体验和页面性能之间取得平衡。中间会穿插一些我在实际部署里踩过的坑，这些内容在官方说明里通常不会写，但恰恰是最容易卡住人的地方。

2. SimpleMathJax 到底替你做了什么，又没做什么

2.1 服务端只负责搬运，渲染全在浏览器

理解 SimpleMathJax 的工作方式，是后面所有配置和排错的基础。传统的服务端渲染方案里，流程是这样的：用户保存页面，MediaWiki 解析到公式标记，调用后端渲染器把公式转成图片或者 SVG，存起来，页面加载时直接输出成品。SimpleMathJax 把这条链路砍掉了一大半。

它做的事情是：在页面输出阶段，把公式的原始文本用特定的 HTML 结构包起来，同时往页面里注入 MathJax 的加载脚本。浏览器拿到页面后，MathJax 扫描这些结构，在本地把公式排版成漂亮的数学符号。整个过程服务端没有参与任何数学排版计算。

这个差异带来的直接后果是：你的服务器不需要任何 TeX 环境，但你的访问者需要能加载 MathJax 的脚本文件。如果站点部署在完全隔离的内网，就得把 MathJax 的脚本文件下载到本地，改成本地引用，否则公式会一直停留在原始文本状态。

2.2 它不解决公式的存储和检索问题

有一点必须提前说清楚，避免后面产生误解。SimpleMathJax 只负责“显示”，不负责“存储格式”和“检索”。公式在数据库里存的就是你写的原始文本，比如$E=mc^2$这样的字符串。这意味着两件事。

第一，公式的搜索是文本层面的。你搜mc^2可能能命中，但搜渲染后的视觉效果是搜不到的。如果你的知识库对公式检索有强需求，得另外想办法，比如在公式旁边补一段文字描述，或者用 MediaWiki 的搜索扩展做二次处理。

第二，公式的编辑是纯文本编辑。这其实是好事，因为纯文本可 diff、可版本对比、可复制粘贴。但前提是写公式的人得懂一点 LaTeX 语法。对于完全不懂 LaTeX 的编辑者，这确实是个门槛，后面我会讲怎么降低这个门槛。

2.3 和 Math 扩展的取舍对比

为了让你更清楚该不该选 SimpleMathJax，我把两条路线放在一起对比一下。

从这张表能看出来，选择的关键在于你的站点环境和对首屏的要求。如果你的站点面向公网、访问者网络正常，SimpleMathJax 的延迟几乎感知不到。如果是严格隔离的内网，那就得提前把脚本本地化这一步规划进去。

3. 把扩展装上去：从获取文件到配置生效

3.1 获取扩展文件的几种途径

安装的第一步是把扩展文件放到 MediaWiki 的extensions目录下。常见的做法是从代码托管平台获取，或者直接下载打包好的压缩包。这里我不写具体地址，因为版本更新频繁，你按扩展名去搜官方仓库即可。

拿到文件后，目录结构应该是这样的：extensions/SimpleMathJax/下面有extension.json、SimpleMathJax.php以及相关的资源文件。确认extension.json存在很关键，因为现代 MediaWiki 扩展都靠这个文件向系统注册自己。

注意：放文件的时候留意一下目录权限。Web 服务进程需要对扩展目录有读取权限，否则加载时会直接报错，而且报错信息往往只提示“扩展加载失败”，不会告诉你具体是权限问题，容易绕弯路。

3.2 在配置文件中启用扩展

文件到位之后，打开 MediaWiki 根目录下的LocalSettings.php，在文件末尾附近加上加载语句。位置有讲究：应该放在所有require_once类加载语句的区域内，不要插到中间某个配置块里面，否则可能出现依赖顺序问题。

wfLoadExtension( 'SimpleMathJax' );

保存之后刷新页面，如果一切正常，扩展就已经生效了。验证方法很简单：随便找一个页面，在编辑框里输入一段行内公式，比如$a^2+b^2=c^2$，保存后看是否渲染成带上下标的数学形式。如果显示的还是原始文本，说明渲染环节没走通，先别急着改配置，去浏览器的开发者工具里看控制台有没有脚本加载错误。

3.3 几个值得提前设置的配置项

SimpleMathJax 提供了一些配置参数，可以在LocalSettings.php里覆盖默认值。下面这几个是我在实际使用中觉得最值得调整的。

第一个是公式的定界符。默认情况下它识别$...$作为行内公式，$$...$$或者\[...\]作为独立公式。如果你的文档里本身就有大量美元符号（比如涉及价格、变量命名），就会和公式定界符冲突。这时候可以改成用\(...\)这种更不容易误伤的写法。

第二个是 MathJax 脚本的来源。默认从公共资源加载，内网环境必须改成本地路径。配置方式通常是设置一个指向本地脚本目录的变量，具体变量名以你所用版本的extension.json里的定义为准。

第三个是是否启用行内公式的自动识别。有些版本支持把整段文本里符合模式的片段自动当公式处理，这个功能方便但容易误判，我一般建议关掉，让编辑者显式地用定界符标注。

// 示例：调整公式定界符与脚本来源，具体键名请以实际版本为准 $wgSimpleMathJaxInlineDelimiters = [ '\\(', '\\)' ]; $wgSimpleMathJaxUseLocalScript = true;

配置改完记得清一下缓存。MediaWiki 有页面缓存和解析器缓存，配置变更后如果看不到效果，先执行一次缓存清理再判断。

4. 公式怎么写：编辑者需要知道的语法与习惯

4.1 行内公式与独立公式的使用边界

公式分两种呈现方式，用对了页面才好看。行内公式嵌在文字中间，适合表达一个符号、一个短表达式，比如“当 $x>0$ 时函数单调递增”。独立公式单独占一行，居中显示，适合表达完整的推导步骤或者较长的式子。

判断标准其实很简单：如果这个公式是句子的一部分，读的时候要连着上下文念，就用行内；如果它是一个需要单独审视的对象，就用独立。我见过不少文档把所有公式都写成独立的，结果页面被切得七零八落，阅读节奏很差。

4.2 常用 LaTeX 结构的速查

写公式本质上是写 LaTeX 的数学模式。下面这张表覆盖了日常文档里最高频的结构，编辑者记住这些基本就能应付大部分场景。

这些结构组合起来能表达相当复杂的数学内容。建议在文档站里放一个“公式语法速查”页面，把这张表放上去，编辑者遇到不会写的结构可以随时查。

4.3 多行公式的对齐技巧

推导过程往往需要多行公式对齐，这时候要用到对齐环境。常见写法是用\begin{aligned}和\end{aligned}包起来，用&标记对齐位置，用\\换行。

$$ \begin{aligned} f(x) &= (x+1)^2 \\ &= x^2 + 2x + 1 \end{aligned} $$

这段代码渲染出来，两个等号会上下对齐，看起来非常规整。这里有个细节：&放在等号前面，表示以等号为对齐基准。如果你想让多行在某个符号处对齐，就把&放在那个符号前面。这个技巧在写推导类内容时特别有用，能让页面专业感提升一个档次。

提示：多行公式里换行符\\后面不要有多余空格再跟内容，某些版本的解析器会把空格也当成公式内容处理，导致对齐出现细微偏移。

5. 渲染不出来？按这条链路逐段排查

公式不渲染是最常见的问题，而且表现形态有好几种，排查思路也不一样。我把它拆成一条从浏览器到服务端的排查链路，你按顺序走一遍，基本都能定位到原因。

5.1 先看浏览器控制台有没有脚本错误

第一步永远是打开浏览器的开发者工具，切到控制台面板，刷新页面。如果看到 MathJax 相关的脚本加载失败，比如 404 或者跨域被拦截，那问题就在脚本来源上。

公网站点出现这种情况，通常是网络环境问题，或者你配置的脚本地址失效了。内网站点出现这种情况，基本可以确定是没有把脚本本地化，或者本地路径配错了。这时候去检查你配置的脚本路径，确认文件真实存在，并且 Web 服务进程有读取权限。

5.2 再看页面源码里公式有没有被正确包裹

如果控制台没有脚本错误，但公式还是原始文本，那就要看服务端有没有把公式标记正确输出。在页面上右键查看源代码，搜索你写的公式原文。如果搜不到，说明公式在解析阶段就被处理掉了，可能是定界符配置和实际写法不匹配。

比如你配置的定界符是\(...\)，但编辑者写的是$...$，那这段内容就不会被识别为公式，自然也不会被包裹。这种情况在多人协作的站点里特别常见，因为不同人习惯不同。解决办法要么统一培训，要么在配置里同时支持多种定界符。

5.3 最后确认扩展加载顺序和缓存状态

前面两步都没问题，公式标记也正确包裹了，但就是不渲染，这时候要考虑扩展加载顺序和缓存。MediaWiki 的扩展加载是有顺序的，如果 SimpleMathJax 依赖的某些钩子在它之前没注册好，它的输出处理就可能不执行。

排查方法是临时把 SimpleMathJax 的加载语句挪到LocalSettings.php里其他扩展加载语句的前面，看是否恢复。如果恢复了，说明存在顺序依赖，需要调整加载位置。另外别忘了清缓存，解析器缓存有时候会记住旧的解析结果，配置改了但缓存没清，看到的还是旧行为。

5.4 公式语法错误引发的连锁反应

有一种情况值得单独说：某个公式的 LaTeX 语法写错了，导致 MathJax 在渲染时抛异常。这个异常有时候会中断后续公式的渲染，表现为“前面几个公式正常，从某个位置开始全部变成原始文本”。

遇到这种部分渲染的情况，定位方法是二分法：把页面内容从中间切开，看问题出在哪一半，然后继续切，直到找到那个出错的公式。找到之后检查它的括号是否配对、环境是否闭合、有没有用到不支持的宏。MathJax 支持的 LaTeX 子集和完整 LaTeX 有差异，某些冷门宏它是不认的。

6. 让公式功能真正好用的几个进阶处理

6.1 内网环境下的脚本本地化

内网部署是 SimpleMathJax 最需要提前规划的场景。因为渲染依赖前端脚本，脚本加载不到，公式功能就是摆设。本地化的做法是把 MathJax 的发行文件下载下来，放到 MediaWiki 能访问到的静态资源目录里，然后把扩展配置里的脚本地址指向这个本地路径。

这里有个容易忽略的点：MathJax 的发行包里有多个文件，包括主脚本、字体文件、配置脚本。只放主脚本是不够的，字体文件缺失会导致公式渲染出来缺字或者符号错位。建议整个发行目录一起放，保持相对路径结构不变。

另外，本地化之后要测试不同浏览器。有些老版本浏览器对某些 JavaScript 特性支持不好，可能导致 MathJax 初始化失败。如果站点需要兼容较老的浏览器，得选一个兼容性更好的 MathJax 版本。

6.2 首屏渲染延迟的缓解思路

前端渲染绕不开的一个问题是首屏延迟。页面加载时，公式先是原始文本，然后突然变成排版好的样子，这个跳变在公式多的页面上会比较明显。

缓解思路有几个。一是把 MathJax 脚本的加载方式调整为异步，避免阻塞页面其他内容的呈现。二是给公式容器加一个占位样式，让它在渲染前保持一个合理的高度，减少布局跳动。三是对于公式特别密集的页面，考虑预渲染成静态图片作为降级方案，这个需要额外的工具链支持，适合对首屏要求极高的场景。

我在实际项目里的做法是：普通文档页接受这个延迟，因为访问者通常会在页面上停留阅读，跳变只发生在加载瞬间；而首页或者仪表盘这类需要快速呈现的页面，就避免放大量公式，或者用图片替代。

6.3 给不熟悉 LaTeX 的编辑者降低门槛

团队协作里，不是每个人都会写 LaTeX。如果公式功能只有少数人能用，那它的价值就打了折扣。降低门槛有几个实用做法。

第一个是在编辑页面旁边放一个公式语法速查面板，把最常用的十几种结构列出来，编辑者照着抄就行。第二个是准备一批公式模板，比如常见的求和、积分、矩阵模板，编辑者复制过去改参数即可。第三个是引入可视化公式编辑器，让编辑者通过点击按钮生成 LaTeX 代码，再粘贴到编辑框里。这类工具市面上有现成的，也有可以自建的。

提示：无论用哪种方式降低门槛，都要保留 LaTeX 源码的可编辑性。如果编辑者只能通过可视化工具生成公式，后期想微调一个符号都得重新走一遍工具，反而更麻烦。

6.4 公式与页面样式的协调

公式渲染出来之后，字号、行高、颜色这些视觉属性和页面正文的协调也值得调一调。默认情况下 MathJax 渲染的公式字号和正文可能不完全一致，在行内公式里会显得突兀。

调整方式是通过 CSS 覆盖。可以给公式容器设置和正文一致的字号，调整行内公式的垂直对齐，让它在文字行里看起来更自然。独立公式的上下间距也可以调，避免和前后段落挤在一起。

/* 示例：让行内公式与正文视觉更协调 */ .mwe-math-element { font-size: 1em; vertical-align: middle; }

这些样式调整不需要改扩展本身，通过站点的公共 CSS 页面就能生效，维护起来也方便。

7. 我在实际部署中攒下的几条经验

先说一个关于版本匹配的教训。MediaWiki 的扩展和核心版本之间有兼容性要求，SimpleMathJax 也不例外。我有一次在升级 MediaWiki 核心之后忘了同步更新扩展，结果公式功能时好时坏，排查了很久才发现是版本不匹配导致的钩子行为变化。所以升级核心之前，先确认扩展有没有对应版本，升级之后第一时间验证公式功能。

再说一个关于备份的提醒。公式内容是以纯文本存在数据库里的，这本来是好事，但前提是你得保证数据库备份覆盖到这些内容。有些团队的备份策略只备份文件不备份数据库，或者数据库备份频率很低，一旦出问题，公式源码就丢了。公式源码丢了比图片丢了更麻烦，因为图片还能从缓存里找，源码没了就得重新写。

还有一个关于性能的观察。公式特别多的页面，前端渲染的耗时是线性增长的。我测过一个页面放了两百多个公式，在普通办公电脑上渲染完成要好几秒。这种页面如果访问频繁，体验会很差。应对办法是把长文档拆成多个子页面，每个页面的公式数量控制在合理范围，或者对超长页面做分页加载。

最后说一个协作习惯上的建议。公式的定界符和写法最好在团队内形成约定，写进文档规范里。我见过一个站点因为不同人用不同的定界符，导致同一篇文档里有的公式渲染有的不渲染，后来统一规范之后这类问题就再没出现过。规范不用复杂，把行内和独立公式的定界符、常用结构的写法、多行对齐的模板定下来就够了。

这套方案跑下来，一个支持公式编辑的 MediaWiki 站点就成型了。它不追求极致的首屏性能，但胜在部署简单、维护省心、编辑体验纯粹。对于内部知识库和教学平台这类场景，这个平衡点找得挺准。