做跨平台桌面应用时最让人意外的往往不是菜单和弹窗而是一个富文本编辑器。之前我们团队做一个桌面内容管理工具在 Electron 里集成 UEditor 提供富文本编辑能力表单适配、中文输入、语法高亮这些都顺利唯独“图片转存”来回折腾了一周。问题本身不复杂但网上大多数方案都是基于传统 Web 后端的桌面端没法直接照搬。UEditor 默认在处理粘贴截图、拖拽图片或复制网页图片时要么把图片变成 base64 数据塞进编辑器要么请求一个服务端接口去“抓取远程图片”。放在 Electron 里这两个行为都会因为缺少服务端而失败最终导致编辑器内容里出现一堆无法显示的图片地址保存下来全是废内容。这篇文章把完整方案整理出来UEditor 与 Electron 如何组织进程图片转存链路怎么设计具体代码怎么落以及我踩过的坑。整套思路源自一个实际的跨平台内容管理 Demo覆盖图片本地化、路径回填、自定义协议注册和常见问题排查可以直接照着抄。1. 整体设计思路先把图片转存链路理清楚1.1 编辑器里的“图片转存”到底在转什么很多人把图片转存理解得很简单以为就是把图片文件保存一下。其实在 UEditor 里“图片”有几种完全不同的存在形态本地图片用户用工具栏的图片上传按钮选择的文件。UEditor 会以 multipart 表单形式提交给serverUrl对应的uploadimageaction服务端保存后返回一个可访问的 URL。剪贴板图片用户直接截图后粘贴到编辑器。UEditor 在大多数情况下会把图片转成 base64 字符串直接写进img标签的src属性。远程图片用户在浏览器里复制了别的网页内容图片 URL 可能是https://xxx.com/1.jpg。如果开启了catchRemoteImageEnableUEditor 会把远程 URL 列表提交给catchimageaction由服务端抓取图片并换成自己的地址。所谓“转存”本质就是把这三种形态统一转换成“本地文件 可访问路径”的最终形态。Web 端这套链路依赖 PHP、Java 或 Node 后端但 Electron 桌面端没有传统意义上的服务端所以必须换一种思路在 Electron 内部自己造一个“服务端”再把图片文件落到本地磁盘里。1.2 Electron 与浏览器环境的三个关键差异在浏览器项目里集成 UEditor配置好serverUrl指向一台服务器就行。但到了 Electron 里环境发生了几个根本性变化第一渲染进程的页面是本地文件不是公网地址直接请求外部服务器会很别扭而且很多桌面场景要求内容离线可用。第二Electron 主进程和渲染进程是隔离的渲染进程不能随便写文件。图片最终要由主进程用 Node 的fs模块写进用户数据目录。第三本地文件不能简单用file://协议塞给img。在打包后的生产环境里file://协议会有跨域限制、目录权限限制而且不同系统对路径格式的宽容度也不一样Windows 下反斜杠问题尤其多。这三个差异决定了我们不能按浏览器那套逻辑去做必须走“主进程提供本地服务 渲染进程消费 自定义协议回显”的路线。1.3 方案选型本地微型服务比 IPC 拦截更好用我一开始想过完全靠 IPC 拦截图片数据也就是渲染进程检测到 base64 图片后调用主进程的方法保存文件再把结果通过 preload 桥接回渲染进程。这个思路可行但有个致命问题它绕过了 UEditor 自己那套图片处理逻辑。UEditor 内部有上传队列、回调状态、偶发加载时序强行在外部拦截很容易出现“图片已经插进编辑器了但转存结果还没回来”的竞态。最后我选择了更稳的方案在 Electron 主进程里启动一个本地 HTTP 服务把 UEditor 的serverUrl指向它。这样 UEditor 会认为自己在跟一个正常的服务端通信上传、抓取、重新加载编辑器内容时都能自动完成 URL 回填行为最接近 Web 端。如果担心服务端口占用可以监听随机端口然后把端口号通过 preload 暴露给渲染进程。本地服务方案对比 IPC 拦截有几个明显优势UEditor 在上传图片以后会自己维护img标签和回调状态不需要额外代码干预。保存文档时图片 URL 已经是本地协议地址HTML 里没有大段 base64体积和可读性都更好。后续如果要做图片压缩、格式转换、去重都统一在本地服务里处理逻辑集中。2. 核心配置拆解UEditor 参数与本地服务约定2.1 初始化配置里必须明确的参数UEditor 的初始化配置项非常多但在 Electron 集成场景下真正影响图片转存的只有下面几个const editor UE.getEditor(editor-container, { serverUrl: window.editorServerUrl, // 指向主进程本地服务 catchRemoteImageEnable: false, // 默认开启的实时抓取桌面端建议先关掉 imageActionName: uploadimage, imageFieldName: upfile, imageMaxSize: 10485760, imageAllowFiles: [.png, .jpg, .jpeg, .gif, .bmp, .webp], catcherActionName: catchimage, catcherFieldName: source, catcherMaxSize: 10485760, });serverUrl是整个方案的地基。UEditor 初始化时会请求serverUrl?actionconfig来拉取服务端配置上传图片时请求serverUrl?actionuploadimage远程抓取时请求serverUrl?actioncatchimage。所以本地服务至少要实现这三个端点。catchRemoteImageEnable建议先设为false。原因在后面第 4 部分会详细说简单讲是桌面端让 UEditor 实时去抓外部图片会在网络不稳定时出现大量不可控的失败重试不如把抓取工作统一挪到“保存文档”这个明确的节点。2.2 本地服务需要返回给 UEditor 的数据格式UEditor 对服务端返回的 JSON 有固定预期格式不对编辑器就会弹“上传失败”。本地服务必须严格遵守处理 config 请求时返回一个包含所有 action 字段名的 JSON{ imageActionName: uploadimage, imageFieldName: upfile, imageUrlPrefix: , imagePathFormat: /editor-images/, catchRemoteImageEnable: false, catcherActionName: catchimage, catcherFieldName: source, catcherUrlPrefix: }处理上传图片请求时返回{ state: SUCCESS, url: app-img://local/20240901_abc123.png, title: 20240901_abc123.png, original: screenshot.png }state必须是字符串SUCCESS大写。url必须是最终可访问的图片地址。这里我们不用https://或相对路径而是用后文要讲的自定义协议app-img://。2.3 为什么必须注册自定义协议而不是直接用 file://很多人习惯在 Electron 里拿到本地文件路径以后直接拼一个file:///C:/Users/...塞给img短期看没毛病但长期会有三个隐患Windows 路径里的反斜杠、空格、中文在某些渲染环境下会被转义出问题。打包后的 asar 环境里资源路径的解析会变得非常复杂。如果编辑器内容后续要同步到 Web 端或别的设备file://路径完全不可移植。自定义协议的优势是把“路径映射”这件事收口在主进程。我们约定图片统一使用app-img://local/文件名形式而真实文件存放在用户数据目录下的某个文件夹里。渲染进程只认协议地址主进程负责把协议地址解析成实际文件路径并返回文件内容。这样跨窗口、跨平台、后续迁移都非常干净。注册协议的代码在下面实操部分给出。这里想强调一个容易被忽略的知识点Electron 16 之后protocol.registerSchemesAsPrivileged必须在app.ready之前调用否则注册无效。很多人第一步就写错结果协议注册代码没生效在本文第 4 部分的排查表里会单独提醒。3. 完整实操一步步跑通图片转存3.1 项目骨架与目录结构我用一个标准的 Electron 自定义预加载脚本项目来演示目录结构如下electron-ueditor-demo/ ├── package.json ├── main.js // 主进程负责本地服务和协议注册 ├── preload.js // 通过 contextBridge 暴露服务端口 ├── renderer/ │ ├── index.html // 编辑器页面 │ └── ueditor/ // 从官方下载的 UEditor 静态文件 └── images/ // 运行时生成的本地图片目录程序内也可动态创建main.js是重头戏负责三件事启动本地 HTTP 服务、注册app-img协议、复用同一个图片目录句柄。3.2 主进程启动本地 HTTP 服务并注册自定义协议先看协议注册这部分代码必须放在app.whenReady()之前const { app, protocol, net } require(electron); const path require(path); const fs require(fs); const crypto require(crypto); const { URL } require(url); const { pathToFileURL } require(url); const http require(http); let imageStoreDir ; protocol.registerSchemesAsPrivileged([ { scheme: app-img, privileges: { standard: true, secure: true, supportFetchAPI: true, corsEnabled: true, stream: true, }, }, ]); app.whenReady().then(() { imageStoreDir path.join(app.getPath(userData), editor-images); fs.mkdirSync(imageStoreDir, { recursive: true }); registerImageProtocol(); startLocalServer(); });registerImageProtocol的实现如下function registerImageProtocol() { protocol.handle(app-img, (request) { const url new URL(request.url); const fileName decodeURIComponent(url.pathname.replace(/^\//, )); // 这里必须做安全校验防止路径穿越 const safeName path.basename(fileName); const filePath path.join(imageStoreDir, safeName); if (fs.existsSync(filePath)) { return net.fetch(pathToFileURL(filePath).toString()); } return new Response(Not Found, { status: 404 }); }); }这段代码的思路很直接凡是app-img://local/xxx.png形式的请求都从 URL 中取出文件名在图片目录里找到真实文件然后用net.fetch以标准 response 的形式返回。渲染进程里的img标签不需要关心文件真实在哪它只认协议地址。本地 HTTP 服务用 Node 自带的http模块写不引入额外依赖function startLocalServer() { const server http.createServer(async (req, res) { const url new URL(req.url, http://127.0.0.1); const action url.searchParams.get(action); if (action config) { res.setHeader(Content-Type, application/json; charsetutf-8); res.end(JSON.stringify({ imageActionName: uploadimage, imageFieldName: upfile, imageUrlPrefix: , imagePathFormat: /editor-images/, catcerActionName: catchimage, catcherActionName: catchimage, catcherFieldName: source, catcherUrlPrefix: , })); return; } if (action uploadimage) { // 这里对 UEditor 的 multipart 表单做简化 // 实际项目可用 busboy 解析重点看返回结构 const body await readBody(req); const base64Data extractBase64FromBody(body); const result saveBase64Image(base64Data); res.setHeader(Content-Type, application/json; charsetutf-8); res.end(JSON.stringify({ state: SUCCESS, url: result.url, title: result.fileName, original: result.fileName, })); return; } if (action catchimage) { const body await readBody(req); const sourceUrls extractSourceUrls(body); const savedList []; for (const item of sourceUrls) { try { const result await saveRemoteImage(item); savedList.push({ state: SUCCESS, url: result.url }); } catch (e) { savedList.push({ state: FAIL, url: item }); } } res.setHeader(Content-Type, application/json; charsetutf-8); res.end(JSON.stringify({ state: SUCCESS, list: savedList })); return; } // 自定义的 base64 转存接口保存文档时前端会调用它 if (url.pathname /save-base64) { const body JSON.parse(await readBody(req)); const result saveBase64Image(body.data); res.setHeader(Content-Type, application/json; charsetutf-8); res.end(JSON.stringify({ state: SUCCESS, url: result.url })); return; } res.setHeader(Content-Type, application/json; charsetutf-8); res.end(JSON.stringify({ state: FAIL, message: unknown action })); }); // 监听随机端口避免冲突 server.listen(0, 127.0.0.1, () { const port server.address().port; // 把端口写入全局变量preload 读取时使用 global.editorServerPort port; }); }saveBase64Image和saveRemoteImage是核心工具函数function saveBase64Image(base64Str) { const match base64Str.match(/^data:(image\/(\w));base64,(.)$/); if (!match) { throw new Error(非法 base64 图片数据); } const ext match[2] jpeg ? jpg : match[2]; const buffer Buffer.from(match[3], base64); const fileName ${Date.now()}_${crypto.randomBytes(4).toString(hex)}.${ext}; fs.writeFileSync(path.join(imageStoreDir, fileName), buffer); return { url: app-img://local/${fileName}, fileName }; } async function saveRemoteImage(sourceUrl) { const http require(http); const https require(https); const client sourceUrl.startsWith(https) ? https : http; const buffer await new Promise((resolve, reject) { client.get(sourceUrl, (res) { if (res.statusCode ! 200) { reject(new Error(HTTP ${res.statusCode})); return; } const chunks []; res.on(data, (c) chunks.push(c)); res.on(end, () resolve(Buffer.concat(chunks))); }).on(error, reject); }); // 用 URL 后缀从远程链接里提取扩展名 let ext path.extname(new URL(sourceUrl).pathname).toLowerCase(); if (![.png, .jpg, .jpeg, .gif, .webp, .bmp].includes(ext)) { ext .png; } const fileName ${Date.now()}_${crypto.randomBytes(4).toString(hex)}${ext}; fs.writeFileSync(path.join(imageStoreDir, fileName), buffer); return { url: app-img://local/${fileName}, fileName }; }这里有几个细节图片命名统一用“时间戳 随机数”避免多用户或多次转存时文件名冲突扩展名从原始 URL 或 base64 头的 MIME 类型提取不依赖用户文件名从远程抓图时只接受有限几个图片扩展名避免下载到恶意文件。3.3 preload 脚本把本地服务端口暴露给渲染进程因为server.listen(0)监听的是随机端口渲染进程在初始化 UEditor 时并不知道端口是多少。用 preload 脚本在页面加载前注入即可const { contextBridge } require(electron); contextBridge.exposeInMainWorld(editorBridge, { getServerUrl: () { return http://127.0.0.1:${global.editorServerPort}; }, });然后index.html里初始化 UEditor 时使用const editor UE.getEditor(editor-container, { serverUrl: window.editorBridge.getServerUrl(), catchRemoteImageEnable: false, // 其他配置... });这里要特别注意preload 脚本里绝对不能直接require(electron)之外的 Node 模块去操作页面里的对象推荐直接用contextBridge。以前踩过坑在 preload 里用ipcRenderer做事件监听然后传给页面回调结果发现回调里的this指向全乱了而且主进程可以接收到页面所有进程的消息安全上也有隐患。3.4 完整的图片转存调用链从粘贴到保存把以上代码跑起来以后整个调用链是这样的用户从剪贴板粘贴一张截图UEditor 生成一个img srcdata:image/png;base64,...。此时图片只是临时显示在编辑器中内容里全是 base64体积很大。用户点击“保存文档”前端脚本执行转存逻辑遍历编辑器 DOM找到所有src以data:开头的图片把它们批量 POST 到本地服务的/save-base64。本地服务把 base64 解码成文件存入图片目录返回app-img://local/xxx.png。前端脚本用返回的 URL 替换原img的src再调用editor.getContent()获取最终 HTML提交到应用的数据层。下次重新打开编辑器时UEditor 渲染 content遇到app-img://local/xxx.png请求由主进程的protocol.handle接管输出真实图片文件。保存时统一转存的前端代码大致如下async function saveEditorContent() { const content editor.getContent(); const container document.createElement(div); container.innerHTML content; const images container.querySelectorAll(img); for (const img of images) { if (img.src.startsWith(data:)) { const res await fetch(window.editorBridge.getServerUrl() /save-base64, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ data: img.src }), }); const result await res.json(); if (result.state SUCCESS) { img.setAttribute(src, result.url); } } } const finalHtml container.innerHTML; // 这里再提交给应用的数据层执行持久化 return finalHtml; }这段代码没有走 UEditor 官方图片上传插件的字段流程而是更贴近“转存”这个动作本身不管编辑器里有多少 base64 图片保存时一次性全部转成本地文件。好处是转存时机可控不会因为用户在编辑过程中反复粘贴、删除图片而产生大量垃圾文件。4. 常见问题与排查技巧实录4.1 粘贴后图片显示为破图或一直加载中这是 Electron 集成 UEditor 最常见的现象。排查思路按顺序来先确认本地服务有没有收到请求。在startLocalServer里打日志如果完全没有请求进来说明serverUrl没配置对或者随机端口在渲染进程没拿到。如果actionuploadimage的请求进来了但返回的 JSON 格式不对UEditor 也会判定失败。还有一种情况是渲染进程的 CSP 策略拦截了向http://127.0.0.1发起的请求需要在index.html的 meta 标签里放宽 CSP。最容易被忽略的是 UEditor 的serverUrl末尾是否带斜杠。如果配置的是http://127.0.0.1:9527/而你在本地服务的 URL 解析里又拼了一层?action不同版本的 UEditor 对斜杠处理不一样建议统一先replace(/\/$/, )再拼参数。4.2 本地图片在编辑器里能看到但导出 HTML 后就没了这个问题的根源是app-img://协议只在桌面应用运行时存在。如果用户把内容导出成一封邮件、一份 Markdown、或者上传到 Web 内容库对方没有你的协议处理器当然显示不了。我在实际项目里的做法是增加一个“导出时转存为云端 URL”的按钮在导出前把内容里所有app-img://local/xxx.png地址收集起来请求后端上传接口把本地文件上传到对象存储拿到https://URL 后替换。这样桌面工作流里用本地协议跨端分发时用公网地址。实现它并不复杂核心就是把app-img://local/文件名转成实际本地路径再以 FormData 上传function resolveLocalImagePath(appImgUrl) { const fileName appImgUrl.replace(app-img://local/, ); // 返回 ${app.getPath(userData)}/editor-images/${fileName} return path.join(imageStoreDir, fileName); }4.3 Windows 路径反斜杠和中文文件名导致图片加载失败Windows 下载到本地的文件名如果包含中文或者通过 URL 传递时没有编码很容易出现加载不了的情况。我建议所有文件名统一用时间戳和随机字符不保留任何用户原始文件名。这不仅是跨平台兼容的需要也是安全考虑避免文件名里出现特殊字符或路径穿越。同时在protocol.handle里一定要对 URL pathname 做decodeURIComponent否则浏览器在显示 URL 编码后的%E4%B8%AD.png时会和实际文件名对应不上而在中文 Windows 系统上这种现象尤其明显。4.4 远程图片抓取成功但原图太大导致编辑器卡顿如果用户粘贴的内容里有一张 10MB 的远程图saveRemoteImage会一次性把整个图下载进内存再写磁盘。在图片多的时候主进程会被大量 IO 阻塞界面卡顿非常明显。我的建议是在saveRemoteImage里读取远程Content-Length响应头超过catcherMaxSize就直接跳过或返回失败提示。另一个思路是在保存后对图片做轻量压缩用sharp或 Electron 自带的nativeImage把超过宽度的图片等比缩小。压缩逻辑不要放在同步请求里扔到独立的异步队列更安全。4.5 自定义协议注册看起来没生效最常见的错误是把protocol.registerSchemesAsPrivileged放在了app.whenReady()之后。官方规定这个 API 必须在 ready 之前调用否则什么都不做。调试时可以先在app.whenReady().then里调用protocol.handle的方法再用一个简单的net.fetch去访问app-img://local/test.png如果返回了文件内容说明协议注册成功否则优先检查注册位置。4.6 常见问题速查表我把实际项目里遇到过的问题整理成了一张速查表方便后续排查对照现象可能原因解决方案粘贴图片无任何反应serverUrl未正确注入检查 preload 端口是否正常传递图片保存失败但无报错imageStoreDir权限不足使用userData目录不要写入项目目录本地服务端口冲突listen(0)被包装后不一致用全局变量记录端口不要重复创建服务大图导致界面卡顿同步写入大文件改异步写入加文件大小限制导出后图片不可访问内容里仍是app-img://导出前做云端 URL 替换远程抓图一直失败外网图片协议或证书问题统一走 https并忽略证书校验时需谨慎编辑器重开内容丢失保存的 HTML 里仍含 base64保存前强制走/save-base64逻辑5. 图片转存方案的优化与避坑心得5.1 图片目录统一管理支持多窗口共享如果把图片目录写死在某个窗口或进程里一旦应用创建多个编辑器窗口各自不知道对方的图片目录就会出现“一个窗口能显示另一个窗口图片全部 404”的诡异问题。正确做法是在主进程启动时就把imageStoreDir定义为全局单例无论哪个渲染进程请求app-img://local/xxx.png主进程都用同一张图片目录去解析。目录内部也可以按月份拆分比如editor-images/202409/xxx.png方便后期清理和备份。但为了不把protocol.handle的逻辑写复杂我在 Demo 里直接用平铺目录如果你的图片量非常大建议按月拆目录并且 URL 里保留月份路径。5.2 转存时做图片去重避免几十个重复文件我们在实际使用中发现用户在编辑一篇文章时可能会反复粘贴同一个截图每次保存都会产生一个新文件。一篇文章改十几次图片目录里就堆了一堆完全相同的文件。解决办法是保存前先计算图片内容的哈希值以哈希值作为文件名的一部分。例如先把 base64 解码成 Buffer用crypto.createHash(sha1).update(buffer).digest(hex)生成哈希然后检查图片目录是否存在同名文件存在就直接使用不存在再写入。这个逻辑非常值得加上因为图片转存的场景里重复图占比很高。5.3 转存失败的兜底策略本地服务偶尔会返回失败尤其是远程图片抓取时目标网站有反爬或证书问题。开发者不能假设转存一定成功前端代码里必须有兜底。我的做法是转存失败的图片在最终 HTML 里保留原始的 base64 数据同时用editor.execCommand(drafts)把内容存到本地草稿。这样用户下次打开草稿时还能看到完整图片不会因为一次转存失败导致整篇内容损坏。用户重新点击保存时转存逻辑会再次处理这些 base64 图片至少不会丢失数据。5.4 关于 Electron 版本与 UEditor 版本的兼容性Electron 更新迭代很快特别是protocol.handle这个 API 在 Electron 25 以后行为和早期版本差异比较大。我们 Demo 的开发环境是 Electron 28如果你用的是 20 以下的旧版本建议把net.fetch(pathToFileURL(...))改成net.fetch(url)并确认路径编码方式。UEditor 方面目前官方发行版最新版是 2.0网上还有 1.4.3 的各种魔改版不要贪图新功能去用不明来源的魔改包因为编辑器内部对img标签的处理逻辑一改转存方案就需要跟着变。综合这些经验我认为 UEditor 集成 Electron 的核心就是一句话给编辑器一个它能理解的本地服务再通过自定义协议解决本地文件的展示问题。只要服务端返回结构符合 UEditor 的预期协议注册时机正确保存时统一做一次 base64 到本地文件的转换整个图片转存链路就能稳定跑起来。个人体会是桌面应用里编辑器的集成往往不是功能本身难而是“浏览器设计的行为”和“桌面端环境”之间的缝隙需要花时间去填补。先把第一条链路打通再逐步考虑压缩、去重、跨端同步整个方案就会越来越顺手。如果你也正在做类似的项目希望这篇记录能帮你少踩几个坑。
