Word公式转LaTeX：CKEditor乱码修复与后端POI转换实战

做内容管理或者在线文档系统的朋友，十有八九都撞上过这个场景：用户从Word里复制一篇带数学公式的文档，粘贴到CKEditor的编辑框里，点击保存后——页面上一片狼藉，公式要么变成一长串<m:oMath>开头的XML标签，要么变成一个黑框，要么干脆连公式带编号一起消失。

搜索记录里“word公式转latex”“CKEditor公式乱码”“poi word公式”这类关键词热度一直没降过，说明这不是个别项目的偶发bug，而是从Word富文本生态跨到Web富文本生态时必然会遇到的一道坎。这篇文章不绕弯子，直接从“乱码怎么修”切入，把Word公式的底层格式、CKEditor的处理边界，以及三套从易到难的修复路径讲清楚。无论你是写轮子的Java后端、被客户电话追着改的前端，还是自己搭博客遇到公式问题的个人开发者，都能找到能落地的方案。

1. 乱码问题拆解：先搞清楚公式到底以什么形式存在

处理任何乱码问题，第一步不是改代码，而是确认你手里到底拿着什么。Word里的公式从来不是只有一种形态，不同形态的公式，粘贴到网页里乱码的方式也完全不一样。把这一点搞错，后续所有修复动作都是白费。

1.1 常见的三种公式形态

Word文档里最常见的公式有三种存在形式：

第一，原生OMML公式。Office 2007之后，Word自带的公式编辑器（现在叫“数学”功能区）生成的公式，底层是一套Office Math Markup Language的XML结构。这类公式在文档里表现为段落级别的<m:oMath>节点，里面嵌套<m:r>、<m:t>这些子节点。当你从Word复制这样的公式到网页剪贴板时，Word会试图把这段XML以HTML格式交给目标程序。浏览器和CKEditor不认识OMML，于是要么把整段XML当作HTML解析，导致页面出现一堆奇怪的标签；要么在解析过程中丢掉了很多结构，只剩碎片文字。

第二，MathType OLE对象公式。很多理工科用户、论文作者习惯用MathType输入公式。这类公式的本质是一个OLE嵌入对象，在Word里看到的是一个可编辑的公式框，但在XML底层是<w:object>和一组二进制数据。复制到浏览器时，CKEditor的安全过滤机制会优先保留文本和常规HTML标签，OLE对象这种带着二进制载荷的东西往往直接被丢弃，表现就是公式区域空白；偶尔有浏览器尝试渲染，显示出来的也只是一个黑框、控件图标或者一串无法理解的对象描述文本。

第三，图片公式。部分文档里公式已经被人为转换成图片，常见的是EMF或PNG格式。图片本身不会“乱码”，但它有自己的麻烦：EMF是微软私有的矢量格式，浏览器默认不支持，粘贴后要么显示成大面积空白，要么显示成破损的图像占位符。PNG相对友好，但同样面临清晰度、缩放失真和不可编辑的问题。

这三种形态的修复路径差异很大。所以遇到用户报“公式乱码”，我习惯先问一句：你那个公式是用Word自带的公式编辑器写的，还是MathType写的？这几乎决定了后面百分之八十的工作。

1.2 CKEditor对公式的“能力边界”在哪

再来说说CKEditor。很多人以为CKEditor能显示公式，只是版本问题。这个理解需要修正一下。

CKEditor本身是一个富文本“编辑容器”，它负责管理HTML内容，但公式的渲染能力并不内置于核心。CKEditor 4要装MathJax插件，CKEditor 5则需要接MathType插件或者自己扩展，底层还是靠MathJax或KaTeX这类数学排版引擎来把LaTeX或MathML渲染成看得懂的公式。换句话说，CKEditor能处理的公式格式是“LaTeX语法”或“MathML节点”，而不是Word的OMML或MathType的OLE对象。

这个边界清楚了，“乱码”的本质也就清楚了：Word公式是中文，CKEditor只认得英文，你直接把中文原文塞给它，它自然只能原样吐出一堆看不懂的XML标签，或者干脆过滤掉。修复乱码，本质上就是要在这个不兼容的中间加一条“翻译管道”，把OMML/OLE格式翻译成LaTeX或MathML。

这里有个生活化的类比：你想把一段中文语音发给一个只懂英文的同事，与其反复调音量、换麦克风，不如先转成文字、翻译成英文再发。公式转换也是同理，硬在CKEditor里解析OMML往往事倍功半，先把格式翻译成目标端认识的语言，后面就顺了。

2. 主流修复方案：绕道Markdown/LaTeX中转

先说我自己最推荐、也是实操里最稳定的一条路径：让Word文档先脱离“在线编辑器粘贴”这个场景，用离线工具转成带LaTeX公式的Markdown或HTML，再导进CKEditor。这条路径对格式复杂、公式数量大的文档尤其适用。

2.1 为什么“中转”比“硬转换”更靠谱

我见过不少团队想在前端直接拦截Word的粘贴数据，把OMML解析成LaTeX。这个思路不是不行，但复杂度很高：OMML的结构非常灵活，矩阵、分段函数、带编号的公式组，每种结构在XML里的嵌套方式都不一样。想用一段正则或者几个遍历函数把所有情况吃透，维护成本会迅速失控。

中转方案的优势在于，把“OMML转LaTeX”这个难题抛给了成熟工具。Pandoc内置了docx解析器，对Word原生公式的转换准确率很高，说白了就是社区已经帮你踩平了这条路。你要做的只是：Word → Pandoc → Markdown/HTML（内嵌LaTeX） → CKEditor + MathJax。链路清晰，每一环都有成熟的轮子。

2.2 Pandoc转换完整操作

如果你的机器装了Pandoc，转换一条命令就搞定：

bash复制# 把 docx 转成带 LaTeX 数学语法的 Markdown
pandoc input.docx -t markdown --mathjax --extract-media=media -o output.md

# 把 docx 转成带 MathML 的 HTML
pandoc input.docx -t html --mathml -o output.html

几个关键参数拆开讲一下：

• -t markdown是指定输出格式为Markdown。
• --mathjax很关键，它告诉Pandoc把公式输出成LaTeX语法（行内用$...$，独立公式用$$...$$），这是为了让后续CKEditor配合MathJax插件能渲染。
• --mathml则是输出MathML节点，适合某些前端只认MathML的场景。
• --extract-media=media会把文档里的图片抽取到media文件夹，否则Markdown里引用不到图片资源。

转换完成后，打开output.md，公式大概长这样：

plaintext复制质能方程可以写成 $E = mc^2$，而质能关系的推导过程如下：

$$
\frac{\partial E}{\partial t} = \nabla \cdot \mathbf{S}
$$

这段内容再粘贴到CKEditor时，只要CKEditor里开启了MathJax渲染，公式就能正常显示。实测下来，上下标、分数、根号、求和符号这些常见结构都能正确保留，工程上完全够用。

需要注意的坑：Pandoc对Word原生公式支持极好，但对MathType老公式基本无解。如果你的文档里有MathType公式，需要先在Word里用MathType自带的“转换公式”功能，把MathType公式批量转成Word原生公式，再交给Pandoc处理。这一步别省。

2.3 不装Pandoc的替代方案

很多办公环境不方便装命令行工具，这时候也有替代方案。

办法一：Word另存HTML + XSLT转换。Word里把文档另存为“筛选过的网页”，得到一个HTML文件。这个HTML里，公式区域会是完整的<m:oMath>XML。然后找到Office安装目录下的OMML2MML.XSL文件（通常在C:\Program Files\Microsoft Office\root\Office16\下），用一个XSLT处理器把OMML转成MathML。有Java环境的话，甚至可以直接用javax.xml.transform来跑转换。这条路径不需要额外安装软件，适合内网环境。

办法二：MathType导出LaTeX。MathType本身有把选中公式复制为LaTeX的能力，设置好之后，从MathType里复制出来的就是\[ ... \]格式的LaTeX代码，直接粘贴进CKEditor的LaTeX环境即可。适合公式量少、逐个处理的情况。

还有一个建议：不要因为图省事，就把带有敏感内容的文档丢到公共在线转换网站上做OMML转LaTeX。我自己处理过含未公开研究成果的文档，有一次为了省几分钟用了在线工具，事后总觉得心里不踏实。文档安全这条红线，做技术的人应该比谁都敏感。

3. 编辑器内复制粘贴修复：从剪贴板层面拦截

中转方案虽然稳，但用户体验多了一步：用户要手动把转换后的内容再粘贴进编辑器。如果是自用系统还好，对外交付的系统这么搞，产品经理多半会来找你“聊一聊”。所以还得准备第二套方案：让用户在CKEditor里直接粘贴Word内容，编辑器内部自动完成公式格式转换。这就要从剪贴板层面动手了。

3.1 CKEditor 4：让粘贴的 OMML 自动变 LaTeX

CKEditor 4本身有MathJax插件，安装之后能渲染LaTeX。我们要做的是在粘贴事件里拦截数据，检测到OMML片段时，把这段XML转成LaTeX字符串，再交给编辑器插入。

核心代码大致是这样：

javascript复制var editor = CKEDITOR.replace('content', {
    extraAllowedContent: 'span[data-*];math;m[namespace];*[xmlns];',
    mathJaxLib: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js',
    on: {
        paste: function (evt) {
            var html = evt.data.dataValue;
            if (html.indexOf('<m:oMath') !== -1) {
                // 这里把 OMML 片段转成 LaTeX 字符串
                // 真实场景下可以调后端接口转换，也可以引入前端转换库
                var latex = convertOmmlToLatex(html);
                evt.data.dataValue = latex;
            }
        }
    }
});

这段代码有几个细节必须注意：

extraAllowedContent配置非常重要。CKEditor有一套内容过滤器，粘贴进来的内容如果包含不在白名单里的标签，会被提前删掉。你要允许<m:oMath>、<m:r>这类带命名空间的节点存活，否则粘贴事件还没走到，OMML已经被过滤得七零八落了。

实际转换OMML到LaTeX的那一步，我不建议在前端用正则手写。除非你的公式种类极其有限，否则正则解析OMML会让你陷入“修了一个公式，坏了两个公式”的泥潭。更好的做法是把这个转换请求发到后端，请后端用XSLT或现成库转换完再返回。如果前端确实要给力，可以调研一下omml2latex这类现成的JavaScript库，至少比从头写强得多。

3.2 CKEditor 5：用自定义粘贴处理器接管

CKEditor 5的架构和4完全不一样，不能复用那套on('paste')的写法。CKEditor 5有官方的“Paste From Office”插件，能处理Word复制的文本、表格和基础格式，但对公式的兼容性依旧有限。

可以自己写一个插件，挂到剪贴板处理管道上。大致思路：

javascript复制import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
import { ClipboardPipeline } from '@ckeditor/ckeditor5-clipboard';

class FormulaFixer extends Plugin {
    static get pluginName() {
        return 'FormulaFixer';
    }

    init() {
        const editor = this.editor;

        editor.plugins.get('ClipboardPipeline').on('inputTransformation', (evt, data) => {
            // data.content 是一个 ViewDocumentFragment
            // 先序列化成 HTML 字符串检测
            const html = data.content.getCustomData('html');
            if (html && html.includes('<m:oMath')) {
                const latex = convertOmmlToLatex(html);
                // 把转换后的 LaTeX 作为新的内容交给编辑器
                data.content = editor.data.processor.toView(latex);
            }
        });
    }
}

这里注意，CKEditor 5的剪贴板数据处理流程比较绕，inputTransformation只是众多事件中的一个。我在实际调试中发现，光挂这一个事件还不够，有时候还要处理contentInsertion事件，否则转换结果会被二次格式化。调试的时候用F12打断点，把data.content每一步的形态都打出来看，比盲猜靠谱。

3.3 应急手段：纯文本粘贴+手动校正

如果系统上线时间紧，公式数量又不多，还有一个应急手段：让用户从Word复制后，在CKEditor里用快捷键“纯文本粘贴”（通常是Ctrl+Shift+V）。这样可以绕过大部分HTML解析，让公式变成一段纯文本。这时候你会看到类似<m:oMath><m:r><m:t>E=mc^2</m:t></m:r></m:oMath>的内容，你可以手动把有用部分抠出来改写成LaTeX，或者交给后端接口批量清洗。

这个方法很粗糙，但能救命。我甚至见过一个内部系统，最终就是用这种“先纯文本粘贴、后端再清洗”的方式撑过了第一版上线，后续才迭代成自动转换。生产系统永远先保证“能用”，再去追求“好用”。

4. 后端转换兜底：用 POI 解析 Word 并转写公式

前面几套方案解决的是“用户复制粘贴”场景。但很多知识管理系统、在线课程平台的正文内容，并不是靠用户手动粘贴进来的，而是需要自动解析上传的Word文档，抽取正文和公式，再入库展示。这时候就该后端出场了。

后端方案更大的优势在于：可以批量处理、可以统一日志、可以针对不同公式类型分流。我用Java技术栈做过完整实现，下面把关键链路拆开讲。

4.1 为什么需要后端兜底

用户手动粘贴的不确定性太大：粘贴的源版本不同、Word版本不同、公式编辑器不同，同样的转换代码可能在A机器上正常、B机器上翻车。而文档导入是程序化路径，输入是固定的docx文件，输出是可预期的HTML内容，这条路一旦打通，能覆盖大量真实业务场景。

对于后端兜底，我们真正要解决的问题只有两个：一是从docx里把公式抽出来，二是把公式格式转成浏览器能渲染的MathML或LaTeX。

4.2 用 Apache POI 抽取 OMML

Java生态里解析docx最常用的就是Apache POI。先加依赖，然后读取段落，拿到每个段落的底层XML对象，从中提取<m:oMath>节点。

核心代码：

java复制import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP;

try (XWPFDocument doc = new XWPFDocument(new FileInputStream("input.docx"))) {
    for (XWPFParagraph para : doc.getParagraphs()) {
        CTP ctP = para.getCTP();
        // 获取该段落下的所有 OMath 节点
        List<CTOMath> mathList = ctP.getOMathList();
        for (CTOMath math : mathList) {
            String ommlXml = math.xmlText();
            // 把 OMML XML 转成 MathML 或 LaTeX
            String converted = ommlToMathMl(ommlXml);
            System.out.println(converted);
        }
    }
}

这里有个容易踩的地方：公式不一定挂在XWPFParagraph.getRuns()上，而是段落级别的<m:oMath>兄弟节点，所以直接从CTP（w:p元素的Java Binding）里取最稳妥。如果只遍历run，你会发现公式根本取不到。

另外，我遇到过docx里公式嵌在表格单元格中的情况。那种场景要递归遍历表格，逻辑会复杂一截。建议先做一个“只处理段落公式”的版本，跑通后再扩展表格场景。

4.3 OMML转MathML与LaTeX的实操

取到OMML XML之后，下一个动作是转换。两条路我都走过，分别说说效果。

路线一：OMML2MML.XSL转MathML。

Office安装目录里自带一个OMML2MML.XSL，作用就是把OMML翻译成MathML。虽然它是给Office用的，但我们也能拿来用。Java里直接用XSLT跑一遍：

java复制import javax.xml.transform.*;
import javax.xml.transform.stream.StreamSource;
import javax.xml.transform.stream.StreamResult;
import java.io.StringReader;
import java.io.StringWriter;

public String ommlToMathMl(String ommlXml) throws Exception {
    TransformerFactory factory = TransformerFactory.newInstance();
    Transformer transformer = factory.newTransformer(
        new StreamSource(new FileInputStream("OMML2MML.XSL"))
    );
    StringWriter writer = new StringWriter();
    transformer.transform(
        new StreamSource(new StringReader(ommlXml)),
        new StreamResult(writer)
    );
    return writer.toString();
}

转换出来的MathML可以直接嵌进HTML，前端用MathJax渲染。这条路线零成本、离线可用，对大多数公式效果都很准确，是我在生产环境的首选。

路线二：OMML转LaTeX。

OMML直接转LaTeX不像转MathML那么标准化。有开源库能处理一部分，但遇到复杂公式容易输出一堆没法渲染的LaTeX垃圾。如果确实需要LaTeX格式，常见做法是先转成MathML，再用MathML转LaTeX库二次转换。转换精度取决于中间格式的信息保留程度，我实测下来，常规的上下标、分数、根号没问题，矩阵和cases环境偶尔会丢结构，需要人工校正。

还有一个更高精度的选项：接MathPix这类在线数学识别API。它能直接从OMML或者图片输出高质量的LaTeX。但要注意两点：一是API按调用量收费，二是文档内容要经过第三方服务器，敏感场景要评估风险。生产环境用不用，看你的业务数据敏感度。

4.4 别把 MathType 老公式漏掉

前面讲的POI抽取，前提是文档里是Word原生OMML公式。如果文档里的公式是MathType生成的，POI能拿到的不是<m:oMath>，而是<w:object>节点，里面是一大段Base64编码的OLE二进制数据。这个数据直接转换很麻烦，相当于要在Java里识别一个私有格式。

我踩过这个坑：当时以为摆平了OMML就万事大吉，结果客户丢进来一批MathType论文，整个导入流程直接翻车。后面想了个实用方案：通知客户先执行一次MathType的“转换公式”，把文档里的MathType公式批量转成Word原生公式，再走我们的导入流程。这不算推卸责任，而是两种格式的技术复杂度根本不在一个量级，与其开发一个高成本的MathType解析器，不如在流程入口处做一次格式归一化。如果这个需求真的很多，可以考虑让用户在Word里手动转换后再上传，这也是Word/数学公式处理场景里的通用做法。

5. 那些年我们踩过的坑：问题排查与避坑指南

讲完了三套方案，最后沉淀一份经验清单。这部分内容不是教科书上的，是我在不同项目里踩坑踩出来的，希望对你有实际帮助。

5.1 乱码现象对照速查表

同样叫“乱码”，背后的原因可能完全不同。先用表格做个快速定位：

5.2 排查五步法

碰上公式乱码时，我习惯按下面五步走，能在几分钟内确定问题归属。

第一步：另存源码看形态。把Word源文档另存为“筛选过的网页”，用编辑器打开HTML源码，搜一下“oMath”和“OLEObject”。看到<m:oMath>是原生公式，看到<o:OLEObject>是MathType，看到<img>就是图片。这一步直接决定后面走哪条技术路线。

第二步：最小化复现。在CKEditor里粘贴一段纯文本，如果纯文本也乱码，先查页面编码和服务器接收编码；如果纯文本正常、只公式乱，才是公式转换链路的问题。

第三步：看DOM验证过滤。在浏览器开发者工具里查看粘贴完成后的DOM结构，检查<m:oMath>节点是不是被CKEditor的allowedContent配置提前删了。很多时候，你写的粘贴处理代码根本没执行机会，因为内容在事件触发前就已经被过滤机制毁掉了。

第四步：对比服务端收数。分别用“直接提交HTML”和“通过编辑器保存”两种方式发请求，在后端日志里对比收到的内容。如果直接提交有公式、编辑器提交没公式，问题在编辑器配置；反之，问题在后端存储或输出时的标签过滤。

第五步：日志留痕。在粘贴处理事件里，把原始的HTML字符串打印到控制台。乱码问题往往需要反复对比“粘贴前长什么样”“处理后又长什么样”，没有日志全靠肉眼猜，效率极低。

5.3 几个值得记住的避坑经验

第一，别把图片公式和文本公式混为一谈。图片公式虽然不产生XML乱码，但用户后续没法编辑、没法检索，等于把数据做死了。你的系统如果面向正式生产环境，最终还是要支持公式文本化，哪怕前期用图片过渡，也要在架构里预留升级路径。

第二，不要试图用一个大正则解析所有OMML结构。OMML是XML树，不是字符串，正则只能处理非常简单的模式。我见过有同事贴了上百行正则去匹配分数结构，最后遇到嵌套分数就崩。XML解析就该用XML解析器，转换交给Pandoc或XSLT，别重复造轮子。

第三，extraAllowedContent配置宁严勿松。释放太多标签权限等于给XSS开大门。只在公式处理场景里允许必要的命名空间节点就够了，不要为了省事直接把所有标签放行。

第四，MathJax的性能问题。公式多的页面渲染很吃浏览器性能，尤其是老电脑打开包含几十个公式的文章，可能明显卡顿。生产环境尽量自托管MathJax脚本，并开启异步加载和本地缓存，不要把页面性能都押在CDN上。KaTeX的渲染速度比MathJax快不少，如果公式以LaTeX为主，可以优先考虑。

我个人在实际项目里最终沉淀下来的组合是：文档导入走后端POI + OMML2MML.XSL转MathML，前端用KaTeX渲染；用户在编辑器里临时贴公式，页面引导他直接粘贴LaTeX代码；遇到MathType老文档，先让内容人员在Word里统一转成原生公式再上传。这套链路不算高大上，但胜在每一环都可控、可维护、可排查。

如果你正在被Word公式和CKEditor的兼容问题折磨，我最大的建议是：先定位公式来源，再选方案，不要一上来就全局搜代码改配置。公式有三种形态、CKEditor有版本差异、前后端有各自的分工，只有把这些变量摸清楚，乱码问题才不是靠运气修复的。