1. 乱码问题到底怎么复现的先说清楚图片乱码长什么样接手这个活儿之前我以为umeditor粘贴Word图片乱码是个小问题网上资料一抓一大把改改配置就能搞定。等真正在涉密内网环境里复现了一遍我才发现事情没那么简单——准确地说这个问题有四种完全不同的长相而网上大部分教程只解决了其中一种剩下的三种会让你怀疑人生。先还原一下现场。我们这套系统是某单位内部的知识管理平台前端用的是UEditor的Java版本部署在隔离网段所有资源必须本地化不能引用任何外网CDN。浏览器环境也不是现在大家常用的Chrome 120而是固定的国产化终端内核版本比较老同时还要兼容部分Windows 7上的IE11。用户的操作习惯也很统一从Word 2016里复制一段图文混排的内容直接CtrlV粘到UEditor的编辑区然后点击保存。第一次真机复现时我拿到的乱码分为这几类第一类图片位置出现一个灰色小方框方框里是个红叉或者干脆是空白的占位符。这是最常见的。对应的HTML里往往是一段img srcfile:///C:/Users/xxx/AppData/Local/Temp/...或者img srchttps://.../paste.htm?rxxx。前者路径指向本地临时目录外网和内网用户根本访问不到后者是UEditor自带的粘贴图片处理逻辑生成了临时地址但没有真正把图片数据上传。第二类图片位置是一大串肉眼可见的乱码文本。你往源码视图里一看好家伙整个Word文档的二进制流被当成字符串写进了HTML。这种情况发生在用户同时复制了表格、文本框、图形等多个对象时剪贴板里的HTML片段中嵌入了!--[if gte vml 1]这类VML标记而UEditor的过滤规则没有兜住直接把垃圾数据渲染出来了。第三类图片能显示但位置错乱、大小失控。典型的Word图片被解析成img width451 height348 srcdata:image/png;base64,...但宽高比例和原文不一致或者图片后面跟着一段莫名其妙的换行和空白段落。这个不算严格意义的乱码但用户感知就是内容坏了。第四类粘贴时一切正常保存后再打开图片全部丢失。这个问题藏在后端入库环节——原本的base64数据在入库时被截断、转义错误或者字段长度超限数据库里存了个残缺的字符串前端渲染时自然就是空图。我们这次要解决的是上述所有情况。因为这个系统要过等保测评还要走软件测评流程任何偶现、无法复现的缺陷都不能带进交付版本。后面我把整个排查过程、方案设计、代码实现、踩坑记录都整理出来了希望能给同样在涉密、内网、国产化环境下做Web系统的人一点参考。2. UEditor粘贴Word的真实数据流理清剪贴板里到底装了什么要根治这个问题必须先搞清楚一件事当用户从Word复制内容再到浏览器里粘贴时UEditor到底拿到了什么数据。2.1 Word写入剪贴板的三种数据格式Word不像你想象的那么单纯。当你按下CtrlCWord会往剪贴板里同时写入多种格式的数据包括但不限于纯文本CF_UNICODETEXT只保留文字内容所有格式、图片、表格全部丢失。如果你想用这个来解决问题那等于让用户手动降级——他们肯定不满意。HTML格式CF_HTML这是最关键的一份数据。它包含完整的HTML片段图片部分不是以二进制文件形式存在而是以base64字符串嵌在img srcdata:image/png;base64,xxx里或者以VML对象形式存在。UEditor的粘贴逻辑主要解析这份数据。RTF格式富文本格式包含图片的二进制数据模板。这份数据对Web端来说意义不大。位图CF_DIBWord偶尔会把整个选区渲染成一张大图塞进剪贴板的位图通道。问题来了UEditor在beforepaste事件和paste事件处理中优先读取的是剪贴板的HTML格式数据。如果你在Chrome里按F12看event.clipboardData.getData(text/html)会看到一个完整的HTML字符串它长这样html body !--StartFragment-- p stylemargin: 0cm; ...span style...这是一段文字/span/p p.../p img srcfile:///C:\Users\xxx\AppData\Local\Temp\Word2Image.png ... !--EndFragment-- /body /html或者长这样img width451 height348 srcblob:https://xxx.com/3f2a1b09-e372-477e-83de-1b2c3d4e5f6a如果是旧版本Word加上老浏览器图片部分甚至会变成!--[if gte vml 1]v:shape id图片_x0020_1 o:spid_x0000_s1026 type#_x0000_t75 stylewidth:425.25pt;height:318.75pt;v:imagedata srcwordml://02000001.jpg o:title//v:shape![endif]--这三种形态对应三种完全不同的处理策略。很多网上的教程只教你处理第二种base64但实战中第一种和第三种更为常见。2.2 UEditor默认的粘贴流程里图片是怎么被处理掉的UEditor的粘贴处理核心在xssFilter白名单过滤和wordImage两个模块。默认情况下wordImage插件的职责是把粘贴进来的Word图片转换成可访问的资源。具体流程是拦截paste事件读取剪贴板HTML。调用filterInputRule对HTML进行过滤保留白名单标签和属性。遍历img标签对src为file://或blob://的图片执行uploadBase64方法。uploadBase64方法内部启动一个隐藏的图片上传请求把图片数据POST到后端controllerUrl后端上传成功后返回URLJS再把img元素的src改成这个URL。如果上传失败img的src会被置空渲染出来就是个红叉。这段逻辑看起来没问题但实际运行中有四个致命缺陷缺陷一依赖controllerUrl能正确响应。在内网环境里如果部署时没有正确配置serverUrl或者上传接口的鉴权与当前登录态冲突上传请求直接失败图片自然丢失。缺陷二base64解码只处理了部分格式。UEditor自带的getBase64Data正则只匹配data:image/(png|jpg|gif);base64,xxx这样的标准前缀。当你遇到data:image/bmp;base64,xxx、data:image/x-emf;base64,xxx这种它直接跳过。缺陷三VML图片默认不处理。UEditor的过滤规则里有v:shape的放弃机制会把VML标记整个删除。也就是说Word用VML描述的图片在粘贴时就被阉割了后续根本谈不上上传。缺陷四插入内部临时BLOB地址后没有清理。部分浏览器下Word图片在HTML片段里是blob:https://xxx.com/xxx格式。UEditor会尝试把这个blob转成base64但如果转换过程出错src就停留在blob地址上其他人打开页面时图片必然404。所以结论是不能指望UEditor自带的wordImage插件完成全部工作必须自己写一套Word粘贴内容预处理 图片采集上传 后端入库适配的组合方案。3. 方案选型的三种路线为什么最终做成前端预处理后端二次兜底搞清楚了数据流接下来是方案设计。这个环节我纠结了两周前后推翻了三个方案才找到一个既符合安全要求又能根治问题的路线。3.1 路线一纯前端正则替换 base64直传这是最容易想到的方案在paste事件里拿到text/html然后用正则把file://、blob://、VML图片地址全部提取出来通过canvas或者FileReader转成base64最后手动把img的src替换成data:image前缀。优点是实现快、不依赖后端改动。缺点是正则解析HTML本身就是个坑Word生成的HTML嵌套极其复杂标签属性顺序不固定大小写混用还有条件注释。你可能会把img的src错误提取把正文里的普通文本误判为图片地址造成内容损坏。另外base64直接进数据库会让单条记录暴增几MB数据库压力巨大而且涉密系统一般不允许前端直接访问本地文件路径这个方案在合规层面就有隐患。3.2 路线二UEditor自带上传接口 前端只做路由改写思路是保留UEditor默认的上传流程只在前端增加一段粘贴前对Word图片进行规范化的逻辑把VML转换成标准img把file://路径改写成相对路径然后交给UEditor的uploadBase64去上传。这个方案比方案一稳但有一个绕不开的依赖上传接口必须可用。在我们的场景里前端和上传服务之间还有一层安全网关上传请求需要带特定tokentoken过期了图片就传不上去。而且UEditor的上传接口返回的数据结构是固定的JSON格式{url, title, original, state}如果要批量上传多张图片你得自己改造队列逻辑否则并发上传会导致顺序错乱、图片串位。3.3 路线三前端预处理生成待上传标记后端入库前统一上传并重写内容这是我们最终落地的方案。核心思路是前端不做图片上传只做格式规范化和占位标记后端在内容保存时统一扫描、上传、重写URL。具体来说前端paste后对HTML做预处理把Word图片统一规范成带特定>// word-paste-normalizer.js (function () { var normalizer { // 统一图片标记用于后端识别 IMG_MARK: data-wps-image1, // 将Word粘贴的HTML进行规范化 normalize: function (html) { if (!html) { return html; } html this.convertVmlToImg(html); html this.normalizeImgSrc(html); html this.cleanupWordJunk(html); return html; }, // 将VML格式的图片转换为标准img标签 convertVmlToImg: function (html) { // 旧版word使用v:shape描述图片形如: // v:shape id图片_x0020_1 o:spid_x0000_s1026 type#_x0000_t75 // stylewidth:425.25pt;height:318.75pt // v:imagedata srcwordml://02000001.jpg o:title/ // /v:shape var vmlShapeRegex /v:shape[\s\S]*?v:imagedata[^]*src([^]*)[\s\S]*?\/v:shape/gi; return html.replace(vmlShapeRegex, function (match, src) { // 尝试从wordml://协议中提取数据 var realSrc src.replace(/^wordml:\/\//i, ); // 如果src本身就是安全的相对路径或base64直接构造img return img src encodeURI(realSrc) normalizer.IMG_MARK stylemax-width:100%; /; }); }, // 处理file://和blob://开头的图片地址 normalizeImgSrc: function (html) { // 将src为file://或blob://的img标记为需要后端处理 var imgRegex /img[^]src[](?:file:\/\/|blob:)[^]*[][^]*/gi; return html.replace(imgRegex, function (match) { // 如果img还没有我们的标记就加上 if (match.indexOf(data-wps-image) -1) { return match.replace(/img/i, img normalizer.IMG_MARK); } return match; }); }, // 清除Word带入的垃圾标签和样式 cleanupWordJunk: function (html) { // 移除Word的条件注释 html html.replace(/!--\[if[\s\S]*?!\[endif\]--/gi, ); // 清理多余的样式类名 html html.replace(/\sclass[][^]*[]/gi, ); // 清理空段落 html html.replace(/p[^]*\s*\/p/gi, ); return html; } }; window.WordPasteNormalizer normalizer; })();这段代码本身不复杂但有几个细节是踩过坑才加的v:imagedata标签里的src值在Word中通常是wordml://02000001.jpg这种协议名不是真实路径正则提取后需要单独处理。如果这个值是个纯文件名如02000001.jpg说明Word把图片数据放在了o:title属性或RTF里此时前端拿不到真实数据流只能保留标记等后端二次处理。cleanupWordJunk里移除class属性要非常小心。UEditor本身需要在img上保留class做样式控制如果一刀切全去掉可能影响图片的对齐样式。我这里是伪移除——只移除来自classMsoNormal这类Word默认类名具体的替代方案见下文。正则匹配img时注意src属性的引号可能是单引号也可能是双引号Word生成的HTML两种都有正则要写成[]统一匹配。4.2 保持图片样式不要破坏Word原有的宽高和居中很多人处理Word粘贴内容时直接把img的宽高全部清掉让浏览器按原始尺寸渲染结果是图片大的大、小的小排版全乱。正确做法是提取Word为图片设置的宽高转成内联样式既能保留原始视觉效果又能避免跨浏览器差异。在convertVmlToImg里我还没处理stylewidth:425.25pt;height:318.75pt这个样式。还需要增加一段代码把Word的pt单位换算成pxconvertVmlToImg: function (html) { var self this; var vmlShapeRegex /v:shape[\s\S]*?style[]([^]*)[][\s\S]*?v:imagedata[^]*src([^]*)[\s\S]*?\/v:shape/gi; return html.replace(vmlShapeRegex, function (match, style, src) { var width null; var height null; // 提取style中的width和height var widthMatch style.match(/width:\s*([\d.])pt/i); var heightMatch style.match(/height:\s*([\d.])pt/i); if (widthMatch) { width Math.round(parseFloat(widthMatch[1]) * 4 / 3); } if (heightMatch) { height Math.round(parseFloat(heightMatch[1]) * 4 / 3); } var styleAttr max-width:100%;; if (width height) { styleAttr width: width px;height: height px;; } var realSrc src.replace(/^wordml:\/\//i, ); return img src encodeURI(realSrc) self.IMG_MARK style styleAttr /; }); }pt到px的换算系数是4/3不用太精确因为Word里1pt对应1/72英寸浏览器1px对应1/96英寸比例就是96/724/3。如果你嫌麻烦直接用浏览器默认比例也行但实测下来不换算的图片在IE11里会明显偏大换算后就正常了。4.3 粘贴后立即展示防止粘贴时图片丢失的用户恐慌即使做了规范化从粘贴到后端上传完成、图片重新渲染之间仍然有一段缺图的时间。如果用户粘贴后看到一片红叉第一反应就是又乱码了。所以前端还应该做一件事粘贴后立即读取base64数据在本地临时回显图片。这个逻辑放在afterpaste事件里// umeditor-patch.js UE.Editor.prototype._wordPasteHandler UE.Editor.prototype._wordPasteHandler || function () {}; // 在UEditor的ready事件之后挂载我们的处理 UE.registerUI(wordPasteNormalizer, function (editor) { editor.addListener(ready, function () { editor.addListener(beforepaste, function (type, e) { var html ; var clipboardData e e.clipboardData; if (clipboardData clipboardData.getData) { html clipboardData.getData(text/html); } if (!html) { return; } // 规范化 var normalized window.WordPasteNormalizer.normalize(html); // 如果HTML有变化需要重新设置回剪贴板 if (normalized ! html clipboardData clipboardData.setData) { try { clipboardData.setData(text/html, normalized); } catch (ex) { // 某些浏览器不允许setData忽略UEditor会使用原始数据 } } }); editor.addListener(afterpaste, function () { // 试图将粘贴的base64图片临时展示缓解用户等待焦虑 var body editor.body; var imgs body.getElementsByTagName(img); for (var i 0; i imgs.length; i) { var img imgs[i]; var src img.getAttribute(src); // 只处理我们标记过的图片 if (img.getAttribute(data-wps-image) src src.indexOf(data:image) 0) { continue; // 已经是base64无需额外操作 } if (img.getAttribute(data-wps-image) src (src.indexOf(file://) 0 || src.indexOf(blob:) 0)) { // 尝试将本地图片转成dataURL以便临时显示 // 这里不能直接读取本地文件转由后端处理前端暂时隐藏 // 隐藏显示避免红叉 img.style.visibility hidden; img.setAttribute(data-wps-pending, 1); } } }); }); return null; });这段代码里有个重要体验设计visibility:hidden而不是display:none。因为display:none会改变排版布局用户在编辑过程中会看到文字突然跳位而visibility:hidden只隐藏图片本身占位还在等到后端返回URL后再显示出来视觉上更平滑。4.4 前端整理的最终数据格式经过以上处理用户点击保存时UEditor的getContent()输出的HTML大致长这样p这是一段正文。/p p img srcdata:image/png;base64,iVBORw0KGgoAAAANSUhEUg...>public class WordContentProcessor { private static final Pattern IMG_PATTERN Pattern.compile( img[^]data-wps-image\1\[^]*src\(data:image/[^\])\[^]*, Pattern.CASE_INSENSITIVE); private static final Pattern SRC_PATTERN Pattern.compile( src\(data:image/[^\])\, Pattern.CASE_INSENSITIVE); // 文件上传服务内部RPC不走HTTP private FileUploadService fileUploadService; public String processContent(String html) { if (html null || html.isEmpty()) { return html; } Matcher matcher IMG_PATTERN.matcher(html); StringBuffer sb new StringBuffer(); ListString failedImages new ArrayList(); while (matcher.find()) { String imgTag matcher.group(0); String base64Data extractBase64(imgTag); if (base64Data null) { // 如果src不是base64保留原标签但标记失败 matcher.appendReplacement(sb, markError(imgTag)); continue; } // 调用RPC上传返回相对路径如 /uploads/2024/05/xxx.png String uploadedPath fileUploadService.uploadBase64(base64Data); if (uploadedPath ! null) { String replacedTag imgTag .replaceFirst(SRC_PATTERN.pattern(), src\ uploadedPath \) .replace(data-wps-image\1\, ); matcher.appendReplacement(sb, replacedTag); } else { matcher.appendReplacement(sb, markError(imgTag)); } } matcher.appendTail(sb); return sb.toString(); } private String extractBase64(String imgTag) { Matcher srcMatcher SRC_PATTERN.matcher(imgTag); if (srcMatcher.find()) { String src srcMatcher.group(1); // src形如 data:image/png;base64,xxxx if (src.startsWith(data:image)) { int commaIndex src.indexOf(,); if (commaIndex 0) { return src.substring(commaIndex 1); } } } return null; } private String markError(String imgTag) { // 替换data-wps-image1为data-wps-error1 return imgTag.replace(data-wps-image\1\, data-wps-error\1\); } }这段代码有几个坑正则匹配要兼顾属性顺序。Word生成的img标签属性顺序不固定可能src在前面>public String uploadBase64(String base64Data) { String md5 DigestUtils.md5DigestAsHex(base64Data.getBytes(StandardCharsets.UTF_8)); String ext detectImageExt(base64Data); // png/jpg/gif/bmp... String filePath uploads/ LocalDate.now().toString() / md5 . ext; // 先查询是否已有 if (fileStorage.exists(filePath)) { return filePath; } // 写入临时文件再走统一的二进制存储通道 byte[] decoded Base64.getDecoder().decode(base64Data); try { fileStorage.write(filePath, decoded); return filePath; } catch (IOException e) { log.error(Upload base64 image failed, path: {}, filePath, e); return null; } }这里有个细节检测图片格式不能只信data:image/png的前缀。有些Word版本导出的图片虽然标记为PNG实际数据却是JPEG编码如果按PNG后缀保存浏览器无法解析。我写了个简单的魔数检测private String detectImageExt(String base64Data) { byte[] decoded Base64.getDecoder().decode(base64Data); if (decoded.length 12) { return bin; } // PNG魔数: 89 50 4E 47 if ((decoded[0] 0xFF) 0x89 decoded[1] P decoded[2] N decoded[3] G) { return png; } // JPEG魔数: FF D8 FF if ((decoded[0] 0xFF) 0xFF (decoded[1] 0xFF) 0xD8 (decoded[2] 0xFF) 0xFF) { return jpg; } // GIF魔数: 47 49 46 38 if (decoded[0] G decoded[1] I decoded[2] F decoded[3] 8) { return gif; } // BMP魔数: 42 4D if (decoded[0] B decoded[1] M) { return bmp; } return bin; }实测中BMP格式的Word图片出现频率很高。Word内部绘图、SmartArt导出的图片不少是BMP而UEditor自带的base64上传正则只认png/jpg/gif这也是默认配置下图片显示不出来的一个重要原因。我们自己实现了BMP上传后这类问题直接消失。5.3 接入保存链路在Service层调用处理器真正接入业务链路时只需要在文档保存的Service方法里加一行调用Transactional(rollbackFor Exception.class) public void saveDocument(DocumentDTO dto) { // 其他业务逻辑... String processedContent wordContentProcessor.processContent(dto.getContent()); documentEntity.setContent(processedContent); documentMapper.updateById(documentEntity); // 其他业务逻辑... }注意Transactional别忘加。因为上传文件和更新数据库不是一个原子操作如果先上传了图片、数据库更新失败会产生孤儿文件。我在上传组件里接了删除接口一旦事务回滚删除本次新上传的文件。但可靠性一般更好的做法是定时任务扫描未关联文件并清理。这是后话了。6. 测试与验证四类场景逐一过最后还发现一个隐藏坑写完前后端进入验证阶段。我按之前复现的四类乱码场景逐一测试同时增加了边界场景。6.1 测试矩阵与结果场景编号测试内容预期结果实际结果备注1Word 2016复制图文混排内容粘贴到UEditor图片显示正常无红叉通过base64图片正常展示2Word 2016复制表格图片组合表格结构保留图片正常通过需要额外处理表格嵌套3Word 2010复制内容VML图片图片正常展示通过前端VML转换起作用4从浏览器复制的网页图片粘贴是否还按Word流程处理部分通过需要区分来源5图片超过5MB上传不超时不丢失通过上传超时时间调大到30秒6保存后重新编辑再保存内容不重复、不乱码通过二次编辑时data-wps-image标记已被移除7并发保存10篇含图文档不产生重复文件、不串图通过依靠MD5幂等保证8IE11下粘贴图片正常显示排版不崩部分通过见下方隐藏坑场景8是我们最后发现的隐藏坑单独拿出来讲。6.2 隐藏坑IE11下getData(text/html)为空在IE11里剪贴板读取HTML数据的方式和Chrome完全不一样。IE的paste事件里event.clipboardData根本拿不到text/html数据只能通过window.clipboardData.getData(Text)拿到纯文本。这意味着我前面的beforepaste处理代码在IE下全部失效UEditor拿到的只有纯文本图片自然全丢。查了UEditor源码才发现它自带的wordImage插件对IE做了兼容通过editor.body.document.execCommand(paste)触发粘贴或者监听drop事件。但这套机制在IE11 Word 2016的场景下并不稳定。我们的处理方式是在IE下主动检测粘贴内容中是否含Word图片标记。具体方法是在afterpaste事件里检查editor.body中是否有img标签的src为空或乱码如果有提示用户请使用从Word粘贴按钮。同时在工具栏增加了一个Word粘贴按钮弹窗让用户手动粘贴再用一个隐藏的contenteditablediv接收粘贴内容读取其innerHTML。这样做虽然不如原生粘贴丝滑但至少功能可用。这段兼容代码在现代化浏览器下完全不会触发安全无副作用。我特意加了特性检测避免在Chrome下误触发。6.3 验证图片不重复二次编辑和保存的幂等性还有一个很容易忽略的点用户第一次粘贴时前端会把图片标记为>