“百度UE”这个叫法我一听就知道说的是百度开源的 UEditor——也就是那个在很多老后台管理系统里用了十多年的富文本编辑器。最近接了个国产化适配的活儿客户给的验收清单里白纸黑字写着“支持在信创环境下导入 Word 文档”第一反应就是拿 UEditor 的 wordimport 插件去试结果折腾了好几天踩了一堆坑。这篇文章就把整个适配过程、技术选型思路还有踩坑记录整理出来给同行省点时间。很明确地说UEditor 在很多主流的国产操作体统和国产浏览器组合下确实有兼容性问题但“能不能兼容”取决于你用什么方案去实现 Word 导入而不是死守着老插件。我调通了核心做法是用现代前端解析方案绕过 UEditor 自带的老旧插件再通过编辑器 API 把解析结果回填进去。你不一定非得换掉整个编辑器关键在于理解 UEditor 的接口设计然后给它接一条新路子。1. 项目背景与兼容性挑战1.1 信创平台的“变”与“不变”先把这个环节说清楚。信创平台并不是某一个单一操作系统而是一整套国产软硬件生态常见的有统信 UOS、银河麒麟这几个系统CPU 架构可能是飞腾、鲲鹏、海光、龙芯或者兆芯处理器架构不同会导致操作系统底层能力有差异浏览器的表现也会跟着变化。做了几个项目之后我对“兼容性”这三个字的体会是真正要面对的并不是操作系统本身而是运行在系统之上的浏览器。大多数信创环境都用的是国产浏览器这些浏览器多半是基于 Chromium 内核二次开发的比如奇安信浏览器、360 安全浏览器信创版、红莲花浏览器等等。既然是 Chromium 内核那么对 HTML5、ES6 这些新标准的支持其实没有太大问题。那 UEditor 在信创环境里到底卡在哪答案在于 UEditor 的版本普遍太老。很多项目还在用 1.4.3.3 这个 2016 年左右的版本当时的实现思路比如基于 ActiveX 的 Word 导入插件、Flash 上传组件放到今天的浏览器里基本属于“一启动就死”的状态。所以我把整个问题拆成了三层编辑器本身能不能跑、Word 导入插件能不能用、导入进来的内容能不能看。中间那层是最核心的瓶颈而第一层和第三层只要做对几个小调整就能解决。这个分层思考很重要千万不要一上来就把整个 UEditor 换掉成本太高风险也大后面我会讲为什么。1.2 UEditor 的 Word 导入到底是怎么实现的UEditor 关于 Word 文档导入这件事老版本里面有两条技术路径。第一条是官方自带的 wordimport 插件老早的版本只能在 IE 浏览器下面跑还依赖一个叫做“Word 文档导入控件”的本地 ActiveX 组件需要用户手动安装。第二条路径是支持粘贴 Word 内容时自动过滤格式也就是你从 Word 里 CtrlC 复制然后到 UEditor 的编辑区里 CtrlV 粘贴它能把 Word 的冗余标签清洗一遍。ActiveX 这条路在信创环境下直接废弃没有商量的余地。国产浏览器哪怕加载兼容模式内核也是 ChromiumActiveX 只在 Windows 内核里存在信创系统默认环境下不会支持。至于粘贴过滤这条路Word 客户端在 Linux 和国产系统上的覆盖率也不高很多用户用的是 WPS 办公软件而 WPS 复制出来的 HTML 剪贴板数据跟微软 Word 的格式结构差别很大UEditor 的默认过滤规则并不会完全适配。还有一个看似不起眼、实际很要命的点老版 wordimport 插件内部用了 window.getSelection() 和 document.execCommand() 这一套旧 API就算浏览器不拦截体验也非常差。在信创环境里遇到报错“out of memory at line xxx”那更是家常便饭因为插件和 Chromium 的进程模型不兼容。所以我最后确定的思路是换掉 wordimport 插件本身而不是花时间去修它。1.3 原生方案有三座大山插件、协议、表单我最初尝试直接用现成方案去解决遇到的三座大山值得单独讲一讲。第一座是插件生态刚才说的 ActiveX 下载、npapi 插件都已经退出了历史舞台国产浏览器即便开放了扩展能力也不会有厂商专门去兼容一个 2016 年的 UEditor 插件。第二座是协议兼容。正常来说富文本编辑器上传 Word 有一个约定俗称的流程把文档传到服务端由服务端转换出 HTML再回调编辑器。老的 UEditor 用表单上传到服务器然后由服务端扩展程序去解析而信创环境里服务端很可能是国产处理器和国产中间件组成的你原来部署在 Windows Server 上的转换程序比如基于 Office COM 组件的代码根本没法直接迁移。第三座是前端页面编码差异。IEC 时代的 Word 文档导入默认认为页面编码是 gb2312 或者 gbk而信创浏览器和新版前端框架生成的页面默认编码基本都是 UTF-8两者一错位就乱码。很多开发者遇到的所谓“导入后全是乱码”十有八九不是文件坏了而是编码协议的问题。好在这三座大山并不是无解的因为现在的浏览器功能比以前强太多了我们用纯前端加轻量后端就能绕过去。接下来这一章说说我最终选定的方案是怎么设计的。2. 技术方案选型与设计思路2.1 为什么前端解析是当前的最优选择要做 Word 文档导入首先得明确“导入”的产物是什么。UEditor 最终需要的不是 Word 文件本身而是一段 HTML。所以谁都能做这个转换可以在服务端用 LibreOffice、可以在前端用 JavaScript 解析、甚至可以调第三方在线预览服务但前提是结果要成为一段 UEditor 能识别的 HTML。我最终选择了以前端解析为主、后端转换为辅的混合方案。前端解析用 mammoth.js 这个库后端备用 LibreOffice 转 HTML。为什么不是纯前端或者纯后端原因有三点。第一纯前端方案在小型文档上优势明显不需要额外部署服务、不需要考虑服务器处理器架构、也不会引入国产中间件兼容问题。用户选中本地 Word 文件浏览器用 FileReader 读取二进制内容mammoth.js 在内存里转换成 HTML整个过程非常干净。第二超大文档或者复杂排版比如几十页带页眉页脚、多级编号的文档纯前端解析的内存占用会很高还需要应对样式丢失的问题这种时候后端转换就更稳。第三对信创环境来说后端转换是一个必须做兜底的选项因为你不知道用户会传什么怪异的文档进来前端解析总有覆盖不到的边缘情况。两头都准备前端正常走后端兜底。这个思想贯穿了后面所有的开发工作。2.2 主流转换库横向对比mammoth.js、docx-preview、LibreOffice顺着方案选型继续说几个具体的技术组件。先说 mammoth.js这是目前 .docx 转 HTML 用得最多的前端库。它的定位是“把 Word 文档转换为干净的网页”针对正文、标题、列表、表格、图片都有处理机制。要说明的是mammoth.js 对 .docx 的解析能力强但对老式 .doc 文件无能为力所以前端只能处理 Word 2007 以上格式。docx-preview 则是另一个方向它主要做的是在浏览器里预览文档效果输出的是 canvas 或者渲染后的页面节点并不是用来转 HTML 的。虽然也很有用但它的产出不契合 UEditor 的接入方式如果直接拿它做 Word 导入填进编辑器的是各种 div 和 style后续编辑体验会很差。后端方案里LibreOffice 是信创环境下最可靠的转换工具它对 .doc、.docx 都支持转换命令也简单但它的缺点是系统资源占用高、样式有差异、还需要在服务器上安装依赖。所以只有在文档特别复杂或者用户上传 .doc 老格式的时候才走这个通道。我做的取舍是这样的文件后缀是 .docx 且大小在 5MB 以内走前端 mammoth.js文件后缀是 .doc 或者大小超过 5MB走服务端 LibreOffice 方案。这样既保证体验又保证兜底能力。这个判断逻辑下面直接放伪代码。// 方案选择策略示例 function wordImportStrategy(file) { if (file.size 5 * 1024 * 1024) { return server-convert; // 大文件走服务端转换 } const ext file.name.split(.).pop().toLowerCase(); if (ext doc) { return server-convert; // 老格式 .doc 走服务端转换 } return client-convert; // 新版 .docx 走 mammoth.js }2.3 还是要聊一下能不能直接换一个编辑器这个问题几乎每个做适配的人最后都会问一遍。既然 UEditor 这么老、坑这么多为什么不干脆换成一个现代化的编辑器有道理但真实项目里不能只看技术爽不爽还要看迁移成本。老系统里可能已经存了大量 UEditor 生成的 HTML 内容这些内容的样式依赖 UEditor 的 CSS 规则结构也带着 UEditor 特有的自定义标签属性比如 classue_t、data-xxx 之类的换编辑器意味着历史内容展示全要回归工作量可能比做 Word 导入适配还要大。所以我的建议是分三种情况去看。系统在初始建设阶段、历史数据少、团队也有精力做页面改版那确实可以直接用信创适配更好的现代编辑器比如 wangEditor 5.x、TinyMCE 7、或者 CKEditor 5。但如果系统是老系统、历史数据量大、或者本次改造只要求解决 Word 导入这一个需求那老老实实给 UEditor 接一个新通道是性价比最高的选择。别忘了UEditor 提供了一套还算稳定的 API新增一个按钮来触发自定义上传逻辑然后把解析结果塞进去这并不难。编辑器的内核不用动动的只是边缘模块风险完全可控。2.4 整体架构长什么样为了直观地表达我把整体数据流描述一下。用户在前端页面上点击“导入 Word”弹窗中选择文件前端根据 2.2 里的策略决定是前端解析还是调后端接口。前端解析成功后生成 HTML 字符串经过一个样式白名单过滤函数清洗干净再调用 editor.setContent() 或者 editor.execCommand(insertHTML, html) 插入到编辑区域。后端转换的成功结果同样是 HTML 字符串走同样的回填流程。整个过程有四个关键点。一是文件读取不经过 UEditor 自带的上传通道全部由我们自己的控件控制。二是图片要单独处理Word 里的图片转出来是 Base64 数据需要决定是直接塞进 HTML 还是上传到服务器换 URL。三是样式过滤要用白名单防止 Word 自带的一堆垃圾样式把编辑器撑爆。四是错误提示要到位用户传了一个完全不支持的加密文档也得有个清晰的中文提示而不是“TypeError: Cannot read properties of undefined”。3. 实操过程与核心环节实现3.1 环境准备在国产系统上把开发环境跑起来实操第一步永远是环境准备。我在银河麒麟 V10 的桌面环境上做了开发处理器是海光 x86 架构浏览器用奇安信浏览器和 Chrome 各测了一轮。开发用的 Node.js 环境直接在系统自带终端里安装这里有几个要注意的点。第一国产系统默认的源有时候包不是最新版安装 Node.js 建议直接用官方 tar.xz 包解压避免源里版本和前端构建工具不兼容。第二项目如果是老式 jQuery 后台系统没有 npm 工作流那 mammoth.js 就不要用 Node 语法去引直接用浏览器标签引入 dist 目录下的 mammoth.min.js挂在全局变量 window.mammoth 下面简单实惠。第三线上部署时如果还是纯静态服务器没有构建步骤那需要把需要的依赖全部下载到本地 vendor 目录手工引入千万别想在生产环境临时联网装依赖。我实际用的开发环境是银河麒麟 V10 SP1、飞腾/海光两套机器、奇安信浏览器Chromium 86 内核版本和统信 UOS 上的 360 浏览器前端构建用 Vite但最后产物兼容性都验证过。这里要提醒一下老后台系统如果还停留在 jQuery RequireJS 时代就别引现代 ESM 的依赖了用 UMD 或者 IIFE 格式的构建产物反而省心。3.2 后端转换接口的落地实现先讲服务端方案因为它是兜底。我在服务端写了一个简单的接口用 Java Spring Boot 实现核心是调用系统命令执行 LibreOffice 转换。LibreOffice 的安装不用多表直接 apt 装或者 yum 装都行。安装完成后转换命令有固定的套路先把文档放到临时目录然后命令行执行 soffice --headless --convert-to html --outdir /tmp/output /tmp/input.docx成功之后会在输出目录生成一个同名 HTML 文件和一堆图片文件。这里容易踩一个大坑LibreOffice 生成的 HTML 是带大段 CSS 的而且会把所有图片以独立文件形式放在同目录下。如果你直接拿这个 HTML 去塞 UEditor图片路径全部失效。所以服务端要做两步处理一是把 HTML 里的图片读取出来转成 Base64二是把 HTML 里多余的外链样式、脚本标签全部剥掉只留下 body 内部的 DOM 结构。Java 端的实现我给个精简版方便理解// 服务端 LibreOffice 转换核心逻辑简化版 public String convertDocxToHtml(File docFile) throws Exception { File outDir new File(/tmp/lo-convert); if (!outDir.exists()) outDir.mkdirs(); Process process Runtime.getRuntime().exec( new String[]{soffice, --headless, --convert-to, html, --outdir, outDir.getAbsolutePath(), docFile.getAbsolutePath()} ); process.waitFor(); String htmlFileName docFile.getName().replaceAll((?i)\\.(doc|docx)$, .html); File htmlFile new File(outDir, htmlFileName); // 此处继续解析 HTML、把 img src 转 Base64、移除多余样式 return cleanHtml(htmlFile); }这个接口上线之后每天晚上跑转换任务稳定性还可以唯一的问题就是首次调用的时候 LibreOffice 启动比较慢大概要 2 到 4 秒。所以实际生产环境里我们做了个保活机制进程常驻通过 unix socket 或者端口去请求转换服务而不是每次转换都启动一个新进程。如果你们转换量不大用上面的示例代码完全够用真正高并发和大批量场景再去优化也不迟。3.3 前端实现mammoth.js 解析 Word 并回填编辑器前端解析是整个方案的亮点。我直接把完整思路和关键代码放出来你照着接就能用。页面引入 mammoth.min.js 之后我需要一个文件选择框通常做成独立按钮监听 change 事件。选中文件后读取为 ArrayBuffer然后调用 mammoth.convertToHtml({arrayBuffer: buffer})它返回一个 Promiseresolve 的是一个 result 对象result.value 就是转换出来的 HTML 字符串result.messages 里可能有警告信息。转换完成后用 editor.setContent(html) 回填。这里我要特别提醒不要用 editor.execCommand(insertHTML) 直接插入因为 UEditor 的过滤机制会对 HTML 做二次清洗如果清洗规则里没有放行某些标签转换出来的内容会被删掉一部分。setContent 是整体替换能保留得更完整。关键实现如下// 基于 mammoth.js 的 Word 导入前端实现 function handleWordImport(file) { const reader new FileReader(); reader.onload async function (e) { const arrayBuffer e.target.result; try { const result await mammoth.convertToHtml( { arrayBuffer: arrayBuffer }, { styleMap: [ p[style-name标题 1] h1:fresh, p[style-name标题 2] h2:fresh, p[style-name正文] p:fresh ]} ); const html cleanWordHtml(result.value); if (window.ue ue.ready) { // 整体替换内容保留更完整 ue.setContent(html); } } catch (err) { console.error(解析失败, err); alert(文档解析失败请确认文件未加密且格式正确); } }; reader.readAsArrayBuffer(file); }这个函数有几个细节值得展开讲讲。第一个细节是 styleMap 参数mammoth.js 默认把 Word 的段落映射到 p标题映射到 h1 到 h6但很多国产 WPS 文档里标题样式名称不标准映射会失效所以通过 styleMap 自己指定名称映射保底效果更好。第二个细节是 cleanWordHtml 这个函数它做的是白名单清洗我放下面。3.4 图片处理解决 Base64 图片的存储问题Word 文档里一插入图片mammoth.js 默认会用 Base64 的方式把图片数据直接写进 HTML 的 img 标签 src 属性里面。这种方式对小型文档没毛病但图片一多整个 HTML 体积翻几倍是常事。UEditor 编辑区要处理长文档浏览器渲染和用户编辑都会卡。所以我的处理原则是图片超过一定大小或数量超过一定阈值就把 Base64 图片提取出来使用 UEditor 的上传接口把图片传到服务器、拿到 URL 地址然后替换 img 的 src。如果图片不多且用户只要求预览就保留 Base64 也还行但生产环境建议用 URL 方案。代码实现可以考虑在 cleanWordHtml 里面做正则替换async function handleBase64Images(html) { const imgRegex /img[^]*src\data:image\/(png|jpeg|jpg|gif);base64,([^\])\[^]*/gi; let match; const tasks []; while ((match imgRegex.exec(html)) ! null) { tasks.push(uploadBase64Image(match[2], match[1])); } if (tasks.length 0) return html; const urls await Promise.all(tasks); let index 0; return html.replace(imgRegex, (m) { return m.replace(/data:image\/(png|jpeg|jpg|gif);base64,[^\]/, urls[index]); }); }这里至少要留两个坑提醒大家。一是 UEditor 自带的上传图片接口是请求 /ueditor/upload/image 之类的路径你的后端必须兼容否则图片会出现 404。二是大量图片并发上传会不会把服务器打挂如果一次导入几十张图片建议限流同一时间只允许 3 个请求并发其余排队。3.5 样式清洗与 UEditor 的适配Word 导出的 HTML 最大的问题不是内容而是样式。一堆 font-family、一堆 span style、一堆 class 属性UEditor 的配置里如果开启了 xssFilter 白名单很多样式会被剥掉如果不开启又会把乱七八糟的样式全部注入。所以我在插入编辑器前会做一个轻量级清洗。清洗规则只有一个核心思路只保留基础布局标签和行内文字样式过滤掉所有自定义 class 和大部分内联样式尤其是 font-family因为 Word 里带的字体信创环境不一定有强行保留会显示为乱码的替代字体。一个简单的正则清洗示例function cleanWordHtml(html) { return html .replace(/span[^]*/gi, span) // 去掉 span 上的内联样式 .replace(/p[^]*/gi, p) // 去掉 p 标签的样式 .replace(/ class\[^\]*\/gi, ) // 移除 class .replace(/ style\[^\]*\/gi, ) // 移除 style .replace(/font[^]*/gi, font); // 清理字体标签 }想强调一下上面的清洗不能完全替代 UEditor 自带的 XSS 过滤功能生产环境还是要保留 UEditor 的最初配置。我的建议是UEditor 的 xssFilterRules 里确保放行了 table、td、th、tr、ul、ol、li、h1-h6、p、img、a 这些标签同时把 style 属性过滤改成白名单字段监听机制比如只允许 text-align、font-weight、font-style、color 这样几个样式字段其余一律清空。这样 Word 表格、列表、标题等常见结构能保留下来细节样式又不会失控。4. 常见问题与排查技巧实录4.1 导入后全是乱码问题可能不在文件而在路径这个现象在信创环境里特别常见说严重也严重说好解决也好解决。有一次用户在统信 UOS 上用 WPS 编辑的一个 .docx 文件导入后所有中文都变成了“锟斤拷”这样的乱码符号英文和数字反而正常。排查下来发现乱码的根源不是 mammoth.js 解析的问题而是文件读取环节。有些国产浏览器的旧版本fileInput.files[0] 返回的文件对象在读取 arrayBuffer 时未按 UTF-8 处理导致二进制流被错误搬迁。解决方式是读完 ArrayBuffer 之后先检测字节序标记对带 BOM 的 UTF-8 文件做特殊处理。第二个常见原因是 WPS 另存的 .docx 文件中 XML 声明的编码格式与正文实际编码不一致这种情况 run 节点里的中文内容不是 UTF-8 编码。mammoth.js 偶尔会解析出 字符。对策是服务端转换方案兜底在 LibreOffice 转换时显式指定编码比如用 --filter-options 把输入输出编码强制成 UTF-8。排查路径别乱猜打开浏览器开发者工具在读取到文件后用 TextDecoder 手动打印前 200 个字符一眼就能判断是否正确编码。这个技巧比不停地换库、加插件都管用。4.2 表格样式太差导入后表格边框消失Word 里的表格通常默认不显示边框WPS 表格里是“表格样式”的蓝色边框风格但转换成 HTML 之后mammoth.js 会把表格转为 table 标签默认不带 border 属性也不带任何 CSS 边界样式。结果就是用户看到的表格像一团乱码结构没有任何分隔线。我的处理方式是清洗 HTML 后通过正则给所有 table 标签默认加上 border1 和 cellspacing0 cellpadding4同时给 td 加上最小宽度。还可以进一步利用 UEditor 的样式规则写一段统一的后置处理代码把样式类统一映射到编辑器自带的表格样式上这样渲染出来就是整洁美观的实线表格。这里提醒一下如果你在 css 里动了 table 的 border-collapse 属性千万别忘了全局重置否则只对导入的文档生效会破坏原有页面的其他表格样式。4.3 图片上传失败或 404这种情况很多时候不是程序逻辑错误而是部署路径问题。调用 UEditor 自带上传接口时如果项目有 context-path 或者做了一层反向代理上传地址会拼接错误。尤其是在信创环境里服务器加了各种安全策略上传接口的路径必须和前端的 baseUrl 保持一致。另一个坑是图片扩展名判定。WPS 编辑的文档里图片可能是 EMF、WMF 这种矢量格式mammoth.js 会把它转成 PNG 吗并不会。它转出来的 img 标签 src 里可能还是 image/x-emf 的 Base64 数据后端的图片上传接口如果只接受 jpg/png就会直接 400 或者 415。我的建议是在 Base64 提取阶段把 image/x-emf、image/wmf 这类格式先用 canvas 转成 PNG 再上传或者干脆丢弃避免界面出现坏图。实测下来WPS 里插入的“屏幕截图”功能产出的图片经常是 EMF 格式这些人踩过的坑能绕就绕。4.4 性能瓶颈与分片转换策略大型 Word 文档比如 20 页、几十张图片的标书前端解析时 mammoth.js 会明显卡住浏览器主线程这时候页面像是假死了一样。处理这个问题有两个方向。第一个方向是 Web Worker。把 mammoth.js 放到一个 Worker 里解析解析完成后把结果 postMessage 回主线程避免阻塞 UI。这个方法很推荐代码改动也不大唯一要注意的是 mammoth.js 本身兼容浏览器 Worker 环境需要打包时单独处理。第二个方向是服务端转换。对于 5MB 以上文件直接走后端接口不在前端折腾。这样还能顺带解决超大文档在编辑器中编辑的性能问题因为服务端转换结果通常是优化后的 HTML体积更小。对于那种文件不大但内容特别复杂的比如用了大量艺术字、文本框、邮件合并域无论前端还是后端都会出问题。我的经验是给这种文档单独设一个“导入失败请复制粘贴正文内容”的兜底提示别让用户卡死在那里。4.5 常见问题速查表我把这段时间实际遇到的问题整理成一个速查表方便大家排查现象可能原因快速解决导入后中文乱码文件编码与解析器不一致检测 BOM、强制 UTF-8、或走服务端转换导入后表格无边框mammoth.js 不生成表格边框样式清洗后统一给 table 添加默认边框图片导入后是空图EMF/WMF 格式不支持用 canvas 转 PNG 或丢弃该类图片编辑器里样式乱套Word 内联样式与编辑器 CSS 冲突清洗 style 和 class用白名单过滤导入 20MB 文档卡死前端主线程阻塞改用 Web Worker 或服务端转换图片上传 404部署路径/接口路径不一致检查 baseUrl 与代理配置二次打开文档样式丢失setContent 后 UEditor 过滤了标签调整 xssFilterRules 白名单配置文档导入按钮不显示UEditor 按钮配置未包含自定义插件检查 toolbars 数组和插件注册这些问题的排查路径基本都遵循同一个原则先看网络请求、再看转换结果、最后看编辑器过滤别一上来就猜是编辑器坏了。5. 一点适配心得绕了这么一大圈真正让我觉得值得记录的其实是方法论上的东西。兼容性适配不是一个“能不能”的是非题而是“在哪个环节做适配”的方案题。UEditor 本身的容器很小一旦理解了它的输入输出接口它可以接上任何现代前端解析方案。我个人的建议是每次遇到这类老组件适配问题先别急着重写先画一条数据流文件从哪来、解析在哪做、结果给到谁、中间经过几次过滤。这条链路走通之后再决定替换哪个环节。替换一个输入处理模块的成本永远低于替换整个编辑器。最后再分享一个小技巧在做信创环境适配的开发过程中最好在至少两台不同架构的机器上做交叉验证。X86 的麒麟、ARM 的统信跑出来的浏览器行为经常有细节差异。在一些 x86 上完全正常的功能可能在 ARM 上就有奇怪字体渲染问题。把这些差异记录下来做成一个自身项目的兼容性备注表后面再做二期三期能省很多回头排查的功夫。
“百度UE”这个叫法我一听就知道说的是百度开源的 UEditor——也就是那个在很多老后台管理系统里用了十多年的富文本编辑器。最近接了个国产化适配的活儿客户给的验收清单里白纸黑字写着“支持在信创环境下导入 Word 文档”第一反应就是拿 UEditor 的 wordimport 插件去试结果折腾了好几天踩了一堆坑。这篇文章就把整个适配过程、技术选型思路还有踩坑记录整理出来给同行省点时间。很明确地说UEditor 在很多主流的国产操作体统和国产浏览器组合下确实有兼容性问题但“能不能兼容”取决于你用什么方案去实现 Word 导入而不是死守着老插件。我调通了核心做法是用现代前端解析方案绕过 UEditor 自带的老旧插件再通过编辑器 API 把解析结果回填进去。你不一定非得换掉整个编辑器关键在于理解 UEditor 的接口设计然后给它接一条新路子。1. 项目背景与兼容性挑战1.1 信创平台的“变”与“不变”先把这个环节说清楚。信创平台并不是某一个单一操作系统而是一整套国产软硬件生态常见的有统信 UOS、银河麒麟这几个系统CPU 架构可能是飞腾、鲲鹏、海光、龙芯或者兆芯处理器架构不同会导致操作系统底层能力有差异浏览器的表现也会跟着变化。做了几个项目之后我对“兼容性”这三个字的体会是真正要面对的并不是操作系统本身而是运行在系统之上的浏览器。大多数信创环境都用的是国产浏览器这些浏览器多半是基于 Chromium 内核二次开发的比如奇安信浏览器、360 安全浏览器信创版、红莲花浏览器等等。既然是 Chromium 内核那么对 HTML5、ES6 这些新标准的支持其实没有太大问题。那 UEditor 在信创环境里到底卡在哪答案在于 UEditor 的版本普遍太老。很多项目还在用 1.4.3.3 这个 2016 年左右的版本当时的实现思路比如基于 ActiveX 的 Word 导入插件、Flash 上传组件放到今天的浏览器里基本属于“一启动就死”的状态。所以我把整个问题拆成了三层编辑器本身能不能跑、Word 导入插件能不能用、导入进来的内容能不能看。中间那层是最核心的瓶颈而第一层和第三层只要做对几个小调整就能解决。这个分层思考很重要千万不要一上来就把整个 UEditor 换掉成本太高风险也大后面我会讲为什么。1.2 UEditor 的 Word 导入到底是怎么实现的UEditor 关于 Word 文档导入这件事老版本里面有两条技术路径。第一条是官方自带的 wordimport 插件老早的版本只能在 IE 浏览器下面跑还依赖一个叫做“Word 文档导入控件”的本地 ActiveX 组件需要用户手动安装。第二条路径是支持粘贴 Word 内容时自动过滤格式也就是你从 Word 里 CtrlC 复制然后到 UEditor 的编辑区里 CtrlV 粘贴它能把 Word 的冗余标签清洗一遍。ActiveX 这条路在信创环境下直接废弃没有商量的余地。国产浏览器哪怕加载兼容模式内核也是 ChromiumActiveX 只在 Windows 内核里存在信创系统默认环境下不会支持。至于粘贴过滤这条路Word 客户端在 Linux 和国产系统上的覆盖率也不高很多用户用的是 WPS 办公软件而 WPS 复制出来的 HTML 剪贴板数据跟微软 Word 的格式结构差别很大UEditor 的默认过滤规则并不会完全适配。还有一个看似不起眼、实际很要命的点老版 wordimport 插件内部用了 window.getSelection() 和 document.execCommand() 这一套旧 API就算浏览器不拦截体验也非常差。在信创环境里遇到报错“out of memory at line xxx”那更是家常便饭因为插件和 Chromium 的进程模型不兼容。所以我最后确定的思路是换掉 wordimport 插件本身而不是花时间去修它。1.3 原生方案有三座大山插件、协议、表单我最初尝试直接用现成方案去解决遇到的三座大山值得单独讲一讲。第一座是插件生态刚才说的 ActiveX 下载、npapi 插件都已经退出了历史舞台国产浏览器即便开放了扩展能力也不会有厂商专门去兼容一个 2016 年的 UEditor 插件。第二座是协议兼容。正常来说富文本编辑器上传 Word 有一个约定俗称的流程把文档传到服务端由服务端转换出 HTML再回调编辑器。老的 UEditor 用表单上传到服务器然后由服务端扩展程序去解析而信创环境里服务端很可能是国产处理器和国产中间件组成的你原来部署在 Windows Server 上的转换程序比如基于 Office COM 组件的代码根本没法直接迁移。第三座是前端页面编码差异。IEC 时代的 Word 文档导入默认认为页面编码是 gb2312 或者 gbk而信创浏览器和新版前端框架生成的页面默认编码基本都是 UTF-8两者一错位就乱码。很多开发者遇到的所谓“导入后全是乱码”十有八九不是文件坏了而是编码协议的问题。好在这三座大山并不是无解的因为现在的浏览器功能比以前强太多了我们用纯前端加轻量后端就能绕过去。接下来这一章说说我最终选定的方案是怎么设计的。2. 技术方案选型与设计思路2.1 为什么前端解析是当前的最优选择要做 Word 文档导入首先得明确“导入”的产物是什么。UEditor 最终需要的不是 Word 文件本身而是一段 HTML。所以谁都能做这个转换可以在服务端用 LibreOffice、可以在前端用 JavaScript 解析、甚至可以调第三方在线预览服务但前提是结果要成为一段 UEditor 能识别的 HTML。我最终选择了以前端解析为主、后端转换为辅的混合方案。前端解析用 mammoth.js 这个库后端备用 LibreOffice 转 HTML。为什么不是纯前端或者纯后端原因有三点。第一纯前端方案在小型文档上优势明显不需要额外部署服务、不需要考虑服务器处理器架构、也不会引入国产中间件兼容问题。用户选中本地 Word 文件浏览器用 FileReader 读取二进制内容mammoth.js 在内存里转换成 HTML整个过程非常干净。第二超大文档或者复杂排版比如几十页带页眉页脚、多级编号的文档纯前端解析的内存占用会很高还需要应对样式丢失的问题这种时候后端转换就更稳。第三对信创环境来说后端转换是一个必须做兜底的选项因为你不知道用户会传什么怪异的文档进来前端解析总有覆盖不到的边缘情况。两头都准备前端正常走后端兜底。这个思想贯穿了后面所有的开发工作。2.2 主流转换库横向对比mammoth.js、docx-preview、LibreOffice顺着方案选型继续说几个具体的技术组件。先说 mammoth.js这是目前 .docx 转 HTML 用得最多的前端库。它的定位是“把 Word 文档转换为干净的网页”针对正文、标题、列表、表格、图片都有处理机制。要说明的是mammoth.js 对 .docx 的解析能力强但对老式 .doc 文件无能为力所以前端只能处理 Word 2007 以上格式。docx-preview 则是另一个方向它主要做的是在浏览器里预览文档效果输出的是 canvas 或者渲染后的页面节点并不是用来转 HTML 的。虽然也很有用但它的产出不契合 UEditor 的接入方式如果直接拿它做 Word 导入填进编辑器的是各种 div 和 style后续编辑体验会很差。后端方案里LibreOffice 是信创环境下最可靠的转换工具它对 .doc、.docx 都支持转换命令也简单但它的缺点是系统资源占用高、样式有差异、还需要在服务器上安装依赖。所以只有在文档特别复杂或者用户上传 .doc 老格式的时候才走这个通道。我做的取舍是这样的文件后缀是 .docx 且大小在 5MB 以内走前端 mammoth.js文件后缀是 .doc 或者大小超过 5MB走服务端 LibreOffice 方案。这样既保证体验又保证兜底能力。这个判断逻辑下面直接放伪代码。// 方案选择策略示例 function wordImportStrategy(file) { if (file.size 5 * 1024 * 1024) { return server-convert; // 大文件走服务端转换 } const ext file.name.split(.).pop().toLowerCase(); if (ext doc) { return server-convert; // 老格式 .doc 走服务端转换 } return client-convert; // 新版 .docx 走 mammoth.js }2.3 还是要聊一下能不能直接换一个编辑器这个问题几乎每个做适配的人最后都会问一遍。既然 UEditor 这么老、坑这么多为什么不干脆换成一个现代化的编辑器有道理但真实项目里不能只看技术爽不爽还要看迁移成本。老系统里可能已经存了大量 UEditor 生成的 HTML 内容这些内容的样式依赖 UEditor 的 CSS 规则结构也带着 UEditor 特有的自定义标签属性比如 classue_t、data-xxx 之类的换编辑器意味着历史内容展示全要回归工作量可能比做 Word 导入适配还要大。所以我的建议是分三种情况去看。系统在初始建设阶段、历史数据少、团队也有精力做页面改版那确实可以直接用信创适配更好的现代编辑器比如 wangEditor 5.x、TinyMCE 7、或者 CKEditor 5。但如果系统是老系统、历史数据量大、或者本次改造只要求解决 Word 导入这一个需求那老老实实给 UEditor 接一个新通道是性价比最高的选择。别忘了UEditor 提供了一套还算稳定的 API新增一个按钮来触发自定义上传逻辑然后把解析结果塞进去这并不难。编辑器的内核不用动动的只是边缘模块风险完全可控。2.4 整体架构长什么样为了直观地表达我把整体数据流描述一下。用户在前端页面上点击“导入 Word”弹窗中选择文件前端根据 2.2 里的策略决定是前端解析还是调后端接口。前端解析成功后生成 HTML 字符串经过一个样式白名单过滤函数清洗干净再调用 editor.setContent() 或者 editor.execCommand(insertHTML, html) 插入到编辑区域。后端转换的成功结果同样是 HTML 字符串走同样的回填流程。整个过程有四个关键点。一是文件读取不经过 UEditor 自带的上传通道全部由我们自己的控件控制。二是图片要单独处理Word 里的图片转出来是 Base64 数据需要决定是直接塞进 HTML 还是上传到服务器换 URL。三是样式过滤要用白名单防止 Word 自带的一堆垃圾样式把编辑器撑爆。四是错误提示要到位用户传了一个完全不支持的加密文档也得有个清晰的中文提示而不是“TypeError: Cannot read properties of undefined”。3. 实操过程与核心环节实现3.1 环境准备在国产系统上把开发环境跑起来实操第一步永远是环境准备。我在银河麒麟 V10 的桌面环境上做了开发处理器是海光 x86 架构浏览器用奇安信浏览器和 Chrome 各测了一轮。开发用的 Node.js 环境直接在系统自带终端里安装这里有几个要注意的点。第一国产系统默认的源有时候包不是最新版安装 Node.js 建议直接用官方 tar.xz 包解压避免源里版本和前端构建工具不兼容。第二项目如果是老式 jQuery 后台系统没有 npm 工作流那 mammoth.js 就不要用 Node 语法去引直接用浏览器标签引入 dist 目录下的 mammoth.min.js挂在全局变量 window.mammoth 下面简单实惠。第三线上部署时如果还是纯静态服务器没有构建步骤那需要把需要的依赖全部下载到本地 vendor 目录手工引入千万别想在生产环境临时联网装依赖。我实际用的开发环境是银河麒麟 V10 SP1、飞腾/海光两套机器、奇安信浏览器Chromium 86 内核版本和统信 UOS 上的 360 浏览器前端构建用 Vite但最后产物兼容性都验证过。这里要提醒一下老后台系统如果还停留在 jQuery RequireJS 时代就别引现代 ESM 的依赖了用 UMD 或者 IIFE 格式的构建产物反而省心。3.2 后端转换接口的落地实现先讲服务端方案因为它是兜底。我在服务端写了一个简单的接口用 Java Spring Boot 实现核心是调用系统命令执行 LibreOffice 转换。LibreOffice 的安装不用多表直接 apt 装或者 yum 装都行。安装完成后转换命令有固定的套路先把文档放到临时目录然后命令行执行 soffice --headless --convert-to html --outdir /tmp/output /tmp/input.docx成功之后会在输出目录生成一个同名 HTML 文件和一堆图片文件。这里容易踩一个大坑LibreOffice 生成的 HTML 是带大段 CSS 的而且会把所有图片以独立文件形式放在同目录下。如果你直接拿这个 HTML 去塞 UEditor图片路径全部失效。所以服务端要做两步处理一是把 HTML 里的图片读取出来转成 Base64二是把 HTML 里多余的外链样式、脚本标签全部剥掉只留下 body 内部的 DOM 结构。Java 端的实现我给个精简版方便理解// 服务端 LibreOffice 转换核心逻辑简化版 public String convertDocxToHtml(File docFile) throws Exception { File outDir new File(/tmp/lo-convert); if (!outDir.exists()) outDir.mkdirs(); Process process Runtime.getRuntime().exec( new String[]{soffice, --headless, --convert-to, html, --outdir, outDir.getAbsolutePath(), docFile.getAbsolutePath()} ); process.waitFor(); String htmlFileName docFile.getName().replaceAll((?i)\\.(doc|docx)$, .html); File htmlFile new File(outDir, htmlFileName); // 此处继续解析 HTML、把 img src 转 Base64、移除多余样式 return cleanHtml(htmlFile); }这个接口上线之后每天晚上跑转换任务稳定性还可以唯一的问题就是首次调用的时候 LibreOffice 启动比较慢大概要 2 到 4 秒。所以实际生产环境里我们做了个保活机制进程常驻通过 unix socket 或者端口去请求转换服务而不是每次转换都启动一个新进程。如果你们转换量不大用上面的示例代码完全够用真正高并发和大批量场景再去优化也不迟。3.3 前端实现mammoth.js 解析 Word 并回填编辑器前端解析是整个方案的亮点。我直接把完整思路和关键代码放出来你照着接就能用。页面引入 mammoth.min.js 之后我需要一个文件选择框通常做成独立按钮监听 change 事件。选中文件后读取为 ArrayBuffer然后调用 mammoth.convertToHtml({arrayBuffer: buffer})它返回一个 Promiseresolve 的是一个 result 对象result.value 就是转换出来的 HTML 字符串result.messages 里可能有警告信息。转换完成后用 editor.setContent(html) 回填。这里我要特别提醒不要用 editor.execCommand(insertHTML) 直接插入因为 UEditor 的过滤机制会对 HTML 做二次清洗如果清洗规则里没有放行某些标签转换出来的内容会被删掉一部分。setContent 是整体替换能保留得更完整。关键实现如下// 基于 mammoth.js 的 Word 导入前端实现 function handleWordImport(file) { const reader new FileReader(); reader.onload async function (e) { const arrayBuffer e.target.result; try { const result await mammoth.convertToHtml( { arrayBuffer: arrayBuffer }, { styleMap: [ p[style-name标题 1] h1:fresh, p[style-name标题 2] h2:fresh, p[style-name正文] p:fresh ]} ); const html cleanWordHtml(result.value); if (window.ue ue.ready) { // 整体替换内容保留更完整 ue.setContent(html); } } catch (err) { console.error(解析失败, err); alert(文档解析失败请确认文件未加密且格式正确); } }; reader.readAsArrayBuffer(file); }这个函数有几个细节值得展开讲讲。第一个细节是 styleMap 参数mammoth.js 默认把 Word 的段落映射到 p标题映射到 h1 到 h6但很多国产 WPS 文档里标题样式名称不标准映射会失效所以通过 styleMap 自己指定名称映射保底效果更好。第二个细节是 cleanWordHtml 这个函数它做的是白名单清洗我放下面。3.4 图片处理解决 Base64 图片的存储问题Word 文档里一插入图片mammoth.js 默认会用 Base64 的方式把图片数据直接写进 HTML 的 img 标签 src 属性里面。这种方式对小型文档没毛病但图片一多整个 HTML 体积翻几倍是常事。UEditor 编辑区要处理长文档浏览器渲染和用户编辑都会卡。所以我的处理原则是图片超过一定大小或数量超过一定阈值就把 Base64 图片提取出来使用 UEditor 的上传接口把图片传到服务器、拿到 URL 地址然后替换 img 的 src。如果图片不多且用户只要求预览就保留 Base64 也还行但生产环境建议用 URL 方案。代码实现可以考虑在 cleanWordHtml 里面做正则替换async function handleBase64Images(html) { const imgRegex /img[^]*src\data:image\/(png|jpeg|jpg|gif);base64,([^\])\[^]*/gi; let match; const tasks []; while ((match imgRegex.exec(html)) ! null) { tasks.push(uploadBase64Image(match[2], match[1])); } if (tasks.length 0) return html; const urls await Promise.all(tasks); let index 0; return html.replace(imgRegex, (m) { return m.replace(/data:image\/(png|jpeg|jpg|gif);base64,[^\]/, urls[index]); }); }这里至少要留两个坑提醒大家。一是 UEditor 自带的上传图片接口是请求 /ueditor/upload/image 之类的路径你的后端必须兼容否则图片会出现 404。二是大量图片并发上传会不会把服务器打挂如果一次导入几十张图片建议限流同一时间只允许 3 个请求并发其余排队。3.5 样式清洗与 UEditor 的适配Word 导出的 HTML 最大的问题不是内容而是样式。一堆 font-family、一堆 span style、一堆 class 属性UEditor 的配置里如果开启了 xssFilter 白名单很多样式会被剥掉如果不开启又会把乱七八糟的样式全部注入。所以我在插入编辑器前会做一个轻量级清洗。清洗规则只有一个核心思路只保留基础布局标签和行内文字样式过滤掉所有自定义 class 和大部分内联样式尤其是 font-family因为 Word 里带的字体信创环境不一定有强行保留会显示为乱码的替代字体。一个简单的正则清洗示例function cleanWordHtml(html) { return html .replace(/span[^]*/gi, span) // 去掉 span 上的内联样式 .replace(/p[^]*/gi, p) // 去掉 p 标签的样式 .replace(/ class\[^\]*\/gi, ) // 移除 class .replace(/ style\[^\]*\/gi, ) // 移除 style .replace(/font[^]*/gi, font); // 清理字体标签 }想强调一下上面的清洗不能完全替代 UEditor 自带的 XSS 过滤功能生产环境还是要保留 UEditor 的最初配置。我的建议是UEditor 的 xssFilterRules 里确保放行了 table、td、th、tr、ul、ol、li、h1-h6、p、img、a 这些标签同时把 style 属性过滤改成白名单字段监听机制比如只允许 text-align、font-weight、font-style、color 这样几个样式字段其余一律清空。这样 Word 表格、列表、标题等常见结构能保留下来细节样式又不会失控。4. 常见问题与排查技巧实录4.1 导入后全是乱码问题可能不在文件而在路径这个现象在信创环境里特别常见说严重也严重说好解决也好解决。有一次用户在统信 UOS 上用 WPS 编辑的一个 .docx 文件导入后所有中文都变成了“锟斤拷”这样的乱码符号英文和数字反而正常。排查下来发现乱码的根源不是 mammoth.js 解析的问题而是文件读取环节。有些国产浏览器的旧版本fileInput.files[0] 返回的文件对象在读取 arrayBuffer 时未按 UTF-8 处理导致二进制流被错误搬迁。解决方式是读完 ArrayBuffer 之后先检测字节序标记对带 BOM 的 UTF-8 文件做特殊处理。第二个常见原因是 WPS 另存的 .docx 文件中 XML 声明的编码格式与正文实际编码不一致这种情况 run 节点里的中文内容不是 UTF-8 编码。mammoth.js 偶尔会解析出 字符。对策是服务端转换方案兜底在 LibreOffice 转换时显式指定编码比如用 --filter-options 把输入输出编码强制成 UTF-8。排查路径别乱猜打开浏览器开发者工具在读取到文件后用 TextDecoder 手动打印前 200 个字符一眼就能判断是否正确编码。这个技巧比不停地换库、加插件都管用。4.2 表格样式太差导入后表格边框消失Word 里的表格通常默认不显示边框WPS 表格里是“表格样式”的蓝色边框风格但转换成 HTML 之后mammoth.js 会把表格转为 table 标签默认不带 border 属性也不带任何 CSS 边界样式。结果就是用户看到的表格像一团乱码结构没有任何分隔线。我的处理方式是清洗 HTML 后通过正则给所有 table 标签默认加上 border1 和 cellspacing0 cellpadding4同时给 td 加上最小宽度。还可以进一步利用 UEditor 的样式规则写一段统一的后置处理代码把样式类统一映射到编辑器自带的表格样式上这样渲染出来就是整洁美观的实线表格。这里提醒一下如果你在 css 里动了 table 的 border-collapse 属性千万别忘了全局重置否则只对导入的文档生效会破坏原有页面的其他表格样式。4.3 图片上传失败或 404这种情况很多时候不是程序逻辑错误而是部署路径问题。调用 UEditor 自带上传接口时如果项目有 context-path 或者做了一层反向代理上传地址会拼接错误。尤其是在信创环境里服务器加了各种安全策略上传接口的路径必须和前端的 baseUrl 保持一致。另一个坑是图片扩展名判定。WPS 编辑的文档里图片可能是 EMF、WMF 这种矢量格式mammoth.js 会把它转成 PNG 吗并不会。它转出来的 img 标签 src 里可能还是 image/x-emf 的 Base64 数据后端的图片上传接口如果只接受 jpg/png就会直接 400 或者 415。我的建议是在 Base64 提取阶段把 image/x-emf、image/wmf 这类格式先用 canvas 转成 PNG 再上传或者干脆丢弃避免界面出现坏图。实测下来WPS 里插入的“屏幕截图”功能产出的图片经常是 EMF 格式这些人踩过的坑能绕就绕。4.4 性能瓶颈与分片转换策略大型 Word 文档比如 20 页、几十张图片的标书前端解析时 mammoth.js 会明显卡住浏览器主线程这时候页面像是假死了一样。处理这个问题有两个方向。第一个方向是 Web Worker。把 mammoth.js 放到一个 Worker 里解析解析完成后把结果 postMessage 回主线程避免阻塞 UI。这个方法很推荐代码改动也不大唯一要注意的是 mammoth.js 本身兼容浏览器 Worker 环境需要打包时单独处理。第二个方向是服务端转换。对于 5MB 以上文件直接走后端接口不在前端折腾。这样还能顺带解决超大文档在编辑器中编辑的性能问题因为服务端转换结果通常是优化后的 HTML体积更小。对于那种文件不大但内容特别复杂的比如用了大量艺术字、文本框、邮件合并域无论前端还是后端都会出问题。我的经验是给这种文档单独设一个“导入失败请复制粘贴正文内容”的兜底提示别让用户卡死在那里。4.5 常见问题速查表我把这段时间实际遇到的问题整理成一个速查表方便大家排查现象可能原因快速解决导入后中文乱码文件编码与解析器不一致检测 BOM、强制 UTF-8、或走服务端转换导入后表格无边框mammoth.js 不生成表格边框样式清洗后统一给 table 添加默认边框图片导入后是空图EMF/WMF 格式不支持用 canvas 转 PNG 或丢弃该类图片编辑器里样式乱套Word 内联样式与编辑器 CSS 冲突清洗 style 和 class用白名单过滤导入 20MB 文档卡死前端主线程阻塞改用 Web Worker 或服务端转换图片上传 404部署路径/接口路径不一致检查 baseUrl 与代理配置二次打开文档样式丢失setContent 后 UEditor 过滤了标签调整 xssFilterRules 白名单配置文档导入按钮不显示UEditor 按钮配置未包含自定义插件检查 toolbars 数组和插件注册这些问题的排查路径基本都遵循同一个原则先看网络请求、再看转换结果、最后看编辑器过滤别一上来就猜是编辑器坏了。5. 一点适配心得绕了这么一大圈真正让我觉得值得记录的其实是方法论上的东西。兼容性适配不是一个“能不能”的是非题而是“在哪个环节做适配”的方案题。UEditor 本身的容器很小一旦理解了它的输入输出接口它可以接上任何现代前端解析方案。我个人的建议是每次遇到这类老组件适配问题先别急着重写先画一条数据流文件从哪来、解析在哪做、结果给到谁、中间经过几次过滤。这条链路走通之后再决定替换哪个环节。替换一个输入处理模块的成本永远低于替换整个编辑器。最后再分享一个小技巧在做信创环境适配的开发过程中最好在至少两台不同架构的机器上做交叉验证。X86 的麒麟、ARM 的统信跑出来的浏览器行为经常有细节差异。在一些 x86 上完全正常的功能可能在 ARM 上就有奇怪字体渲染问题。把这些差异记录下来做成一个自身项目的兼容性备注表后面再做二期三期能省很多回头排查的功夫。
