1. 项目概述为什么需要自定义上传在富文本编辑器的日常开发中上传图片和视频几乎是绕不开的核心功能。无论是内容管理系统、博客后台还是社区发帖用户都期望能像使用Word一样轻松地拖拽或选择文件然后编辑器自动完成上传并插入内容。wangEditor作为一款流行的开源富文本编辑器其开箱即用的上传功能虽然方便但在实际企业级应用中往往“水土不服”。默认的上传逻辑是将文件发送到wangEditor官方维护的一个临时服务器这对于快速原型验证是极好的。但一旦进入生产环境问题就接踵而至文件存在哪里如何管理比如定期清理如何与现有的用户认证、权限系统结合如何实现文件压缩、水印、CDN分发等业务需求更重要的是数据安全性和业务自主性要求我们必须将文件存储在自己的服务器或云存储如阿里云OSS、腾讯云COS、七牛云等上。这就是customUpload方法存在的意义。它不是一个简单的配置项而是将编辑器核心的文件处理能力与开发者自定义的后端业务逻辑进行桥接的关键接口。通过配置customUpload你告诉wangEditor“上传这个动作我接管了你只需要负责前端的选择、预览和插入剩下的传输、存储、返回链接由我的后端服务来处理。” 这种解耦赋予了开发者极大的灵活性能够无缝对接任何已有的文件上传体系。2. 核心需求与场景拆解在动手写代码之前我们必须明确自定义上传到底要解决哪些具体问题。不同的业务场景对customUpload的实现要求截然不同。2.1 场景一对接自有后端API这是最常见的情况。公司已有成熟的后端服务提供了标准的上传接口。你的任务就是让wangEditor发起的请求符合这个接口的规范。需求点请求方法POST、接口地址/api/upload、请求头如Authorization: Bearer token、表单字段名可能是file也可能是image。关键挑战处理用户认证Token如何携带、处理服务器返回的数据格式你的接口可能返回{ code: 0, data: { url: ‘…’ } }而wangEditor默认期望直接是图片URL。2.2 场景二直传云存储OSS/COS为了减轻服务器压力、提升上传速度和全球访问能力直接将文件从用户浏览器上传到云存储服务。需求点在上传前需要先从自己的后端服务获取一个临时的、有时效性的上传凭证如STS Token、预签名URL。关键挑战实现“两步走”逻辑。第一步编辑器触发上传时先调用你的接口获取凭证第二步使用该凭证调用云服务商的SDK或API直接上传。整个过程需要在customUpload函数内同步完成对异步流程控制要求较高。2.3 场景三上传前处理压缩、水印、格式校验为了节省流量和存储空间或满足统一的内容规范需要在文件上传前进行预处理。需求点在调用后端接口前对用户选择的图片进行压缩、添加水印或校验视频格式、大小。关键挑战全部在前端完成。需要使用File对象、CanvasAPI或第三方库如compressorjs进行处理。处理是异步的需要妥善管理处理状态和错误避免阻塞编辑器界面。2.4 场景四分片上传与断点续传大文件场景当用户上传高清视频或大型设计文件时单次上传可能失败或超时。分片上传将大文件切成小块分别上传最后在服务器合并。需求点customUpload需要管理分片逻辑计算文件哈希、切片、并发上传、记录进度、处理失败重试。关键挑战逻辑极其复杂通常需要引入专门的上传库如tus-js-client或云服务商提供的分片SDKcustomUpload函数主要作为集成入口。同时需要提供精细的上传进度反馈提升用户体验。3. customUpload 方法深度配置指南理解了场景我们进入核心环节如何正确配置customUpload。这个方法接收两个参数file和insertFn。file: 用户选择的文件对象是一个标准的 JavaScriptFile类型。你可以通过file.type判断是图片还是视频通过file.size获取文件大小。insertFn: 一个由wangEditor提供的回调函数。当你成功获取到文件的线上可访问URL后必须调用这个函数并传入该URL编辑器才会将内容插入到光标处。它的参数是insertFn(url)。一个最基础的自定义上传配置骨架如下const editorConfig { MENU_CONF: { uploadImage: { customUpload: async (file, insertFn) { // 1. 在这里实现你的上传逻辑 // 2. 上传成功后获得文件的线上URL const imageUrl ‘https://your-domain.com/path/to/image.jpg’; // 3. 调用 insertFn insertFn(imageUrl); }, }, uploadVideo: { customUpload: async (file, insertFn) { // 视频上传逻辑 const videoUrl ‘https://your-domain.com/path/to/video.mp4’; insertFn(videoUrl); }, }, }, };3.1 对接标准后端API的完整示例假设你的后端上传接口为POST /api/upload使用multipart/form-data格式字段名为file并要求在请求头中携带JWT Token。成功返回格式为{ success: true, data: { url: string } }。customUpload: async (file, insertFn) { // 创建 FormData 对象 const formData new FormData(); formData.append(‘file’, file); // 字段名 ‘file’ 需与后端约定一致 try { const response await fetch(‘/api/upload’, { method: ‘POST’, headers: { // 注意当 body 是 FormData 时浏览器会自动设置 Content-Type 为 multipart/form-data并带上 boundary。 // 我们只需添加认证头。 ‘Authorization’: Bearer ${yourAuthToken}, }, body: formData, }); if (!response.ok) { throw new Error(上传失败: ${response.status}); } const result await response.json(); // 根据你的后端返回结构解析URL if (result.success result.data?.url) { insertFn(result.data.url); } else { // 处理业务逻辑错误 console.error(‘上传成功但返回数据异常:’, result); // 可以在这里触发编辑器提示 editor.alert(‘上传失败服务器返回数据错误’, ‘error’); } } catch (error) { console.error(‘上传过程发生错误:’, error); editor.alert(上传失败${error.message}, ‘error’); // 重要失败时不要调用 insertFn } }注意editor.alert是wangEditor v5 提供的API用于在编辑器内显示提示。你需要确保在函数外部能访问到editor实例或者通过其他方式如Message组件通知用户。3.2 集成阿里云OSS直传实践直传云存储能极大提升性能。这里以阿里云OSS浏览器直传为例采用服务端签名后前端直传的模式。前端customUpload实现customUpload: async (file, insertFn) { // 第一步从你自己的后端获取OSS上传所需的签名信息 let policyData; try { const policyResp await fetch(‘/api/get-oss-policy’, { // 你的后端签名接口 method: ‘POST’, headers: { ‘Content-Type’: ‘application/json’ }, body: JSON.stringify({ fileName: file.name }), }); policyData await policyResp.json(); // policyData 应包含policy, signature, OSSAccessKeyId, host, dir 等信息 } catch (error) { editor.alert(‘获取上传凭证失败’, ‘error’); return; } // 第二步构建新的 FormData用于提交到OSS const ossFormData new FormData(); ossFormData.append(‘key’, policyData.dir ‘${filename}’); // OSS存储路径 ossFormData.append(‘policy’, policyData.policy); ossFormData.append(‘OSSAccessKeyId’, policyData.OSSAccessKeyId); ossFormData.append(‘signature’, policyData.signature); ossFormData.append(‘success_action_status’, ‘200’); // 成功后返回200状态码 ossFormData.append(‘file’, file); // 文件内容必须放在最后 // 第三步直接上传到OSS try { const ossResponse await fetch(policyData.host, { // OSS的Bucket域名 method: ‘POST’, body: ossFormData, }); if (ossResponse.ok) { // 拼接出文件的完整访问URL const fileUrl ${policyData.host}/${policyData.dir}${encodeURIComponent(file.name)}; insertFn(fileUrl); } else { const errorText await ossResponse.text(); throw new Error(OSS上传失败: ${ossResponse.status}, ${errorText}); } } catch (error) { console.error(‘直传OSS失败:’, error); editor.alert(‘文件上传到存储失败’, ‘error’); } }后端签名接口 (/api/get-oss-policy) 简要逻辑Node.js示例这个接口的作用是生成一个有时效性的、安全的临时上传凭证避免将主账号的AccessKey暴露在前端。import OSS from ‘ali-oss’; import crypto from ‘crypto’; app.post(‘/api/get-oss-policy’, async (req, res) { const { fileName } req.body; const dir ‘uploads/’ new Date().toISOString().slice(0, 7) ‘/’; // 按年月分目录 const policyText { expiration: new Date(Date.now() 300000).toISOString(), // 5分钟后过期 conditions: [ [‘content-length-range’, 0, 104857600], // 限制文件大小100MB [‘starts-with’, ‘$key’, dir], // 限制上传路径前缀 ], }; const policy Buffer.from(JSON.stringify(policyText)).toString(‘base64’); const signature crypto.createHmac(‘sha1’, process.env.OSS_ACCESS_KEY_SECRET).update(policy).digest(‘base64’); res.json({ OSSAccessKeyId: process.env.OSS_ACCESS_KEY_ID, host: https://${process.env.OSS_BUCKET}.${process.env.OSS_REGION}.aliyuncs.com, policy, signature, dir, }); });3.3 前端图片压缩与处理在上传前对图片进行压缩可以显著提升用户体验和节省成本。我们可以使用compressorjs这个库。import Compressor from ‘compressorjs’; customUpload: async (file, insertFn) { // 仅对图片进行压缩 if (!file.type.startsWith(‘image/’)) { // 非图片文件直接走普通上传流程 await yourNormalUploadFunction(file, insertFn); return; } new Compressor(file, { quality: 0.6, // 压缩质量 0-1 maxWidth: 1920, // 最大宽度 maxHeight: 1080, // 最大高度 convertSize: 1024 * 1024, // 超过1MB的图片尝试转换为WebP success(compressedFile) { // compressedFile 是一个新的 Blob 或 File 对象 // 将压缩后的文件上传 yourNormalUploadFunction(compressedFile, insertFn); }, error(err) { console.error(‘图片压缩失败:’, err); editor.alert(‘图片处理失败已尝试上传原图’, ‘warning’); // 压缩失败降级为上传原文件 yourNormalUploadFunction(file, insertFn); }, }); }实操心得压缩参数需要根据实际业务平衡。quality: 0.6到0.8在视觉损失和体积减少之间通常是个好选择。一定要设置error回调提供降级方案避免因为压缩失败导致整个上传功能不可用。4. 高级功能与状态管理一个健壮的上传功能离不开良好的用户交互反馈。wangEditor的customUpload本身是异步函数我们可以利用其Promise特性结合编辑器的API实现进度提示和成功/失败反馈。4.1 实现上传进度提示虽然fetchAPI本身不直接支持进度事件但我们可以通过拦截请求体或使用XMLHttpRequest来实现。这里展示一个使用axios它内置了进度支持的示例。import axios from ‘axios’; customUpload: async (file, insertFn) { const formData new FormData(); formData.append(‘file’, file); // 在编辑器菜单栏附近显示一个进度条或提示需要自己实现UI组件 showProgressBar(0); try { const response await axios.post(‘/api/upload’, formData, { headers: { ‘Authorization’: Bearer ${token} }, onUploadProgress: (progressEvent) { const percentCompleted Math.round((progressEvent.loaded * 100) / progressEvent.total); updateProgressBar(percentCompleted); // 更新UI进度 }, }); if (response.data.success) { insertFn(response.data.data.url); editor.alert(‘上传成功’, ‘success’); } } catch (error) { editor.alert(上传失败${error.message}, ‘error’); } finally { hideProgressBar(); // 无论成功失败隐藏进度条 } }如果你的项目没有用axios纯fetch方案较为复杂可以考虑监听ReadableStream的读取进度或者退而求其次只做“上传中”的无限循环动画在上传完成后关闭。4.2 处理多文件上传与并发控制当用户一次性选择多张图片时wangEditor会为每个文件单独调用一次customUpload函数。这意味着默认情况下多个文件的上传是并发的。优势速度快。劣势可能对服务器造成瞬时压力浏览器也有并发连接数限制。如果需要控制并发数需要在customUpload外部实现一个队列管理器。这里提供一个简单的思路class UploadQueue { constructor(maxConcurrent 3) { this.queue []; this.activeCount 0; this.maxConcurrent maxConcurrent; } add(task) { this.queue.push(task); this.run(); } run() { while (this.activeCount this.maxConcurrent this.queue.length) { const task this.queue.shift(); this.activeCount; task().finally(() { this.activeCount--; this.run(); }); } } } // 全局上传队列 const globalUploadQueue new UploadQueue(3); // 在 customUpload 中 customUpload: (file, insertFn) { const uploadTask () yourActualUploadFunction(file, insertFn); globalUploadQueue.add(uploadTask); // 注意这里不能是 async 函数因为我们要立即返回将控制权交给队列。 // yourActualUploadFunction 内部需要处理 insertFn 的调用。 }4.3 文件类型、大小校验与错误处理在文件上传前进行校验是必不可少的这能提前拦截无效请求给出清晰的用户提示。customUpload: async (file, insertFn) { // 1. 校验文件类型 const allowedImageTypes [‘image/jpeg’, ‘image/png’, ‘image/gif’, ‘image/webp’]; const allowedVideoTypes [‘video/mp4’, ‘video/webm’]; const isImage file.type.startsWith(‘image/’); const isVideo file.type.startsWith(‘video/’); if (isImage !allowedImageTypes.includes(file.type)) { editor.alert(不支持图片格式 ${file.type}请使用 JPG, PNG, GIF 或 WebP, ‘error’); return; // 直接返回不进行上传 } if (isVideo !allowedVideoTypes.includes(file.type)) { editor.alert(不支持视频格式 ${file.type}请使用 MP4 或 WebM, ‘error’); return; } if (!isImage !isVideo) { editor.alert(‘请选择图片或视频文件’, ‘error’); return; } // 2. 校验文件大小 (例如图片限制5MB视频限制100MB) const maxImageSize 5 * 1024 * 1024; const maxVideoSize 100 * 1024 * 1024; if (isImage file.size maxImageSize) { editor.alert(图片大小不能超过 ${maxImageSize / 1024 / 1024}MB, ‘error’); return; } if (isVideo file.size maxVideoSize) { editor.alert(视频大小不能超过 ${maxVideoSize / 1024 / 1024}MB, ‘error’); return; } // 3. 校验通过执行上传 try { // ... 你的上传逻辑 } catch (error) { // 4. 统一处理上传过程中的网络或服务器错误 editor.alert(上传失败${error.message}, ‘error’); // 可以在这里上报错误日志 } }5. 常见问题排查与实战技巧即使按照文档配置也难免会遇到各种“坑”。下面是我在多个项目中总结的常见问题及其解决方案。5.1 问题上传成功但图片/视频不显示这是最典型的问题根本原因在于insertFn接收的URL不正确。排查步骤检查URL是否可公开访问在浏览器地址栏直接粘贴insertFn传入的URL看是否能下载或显示文件。如果返回403、404或需要登录说明文件权限或路径有问题。检查URL格式确保是完整的https://或http://开头的绝对URL。如果你传了一个相对路径如/uploads/1.jpg编辑器是无法识别的。检查控制台网络请求上传请求是否真的成功了服务器返回的URL字段路径是否正确是否有拼写错误如ur而不是url解决方案确保后端返回的以及你传给insertFn的是一个能直接被img或video标签src属性使用的、可公开访问的完整URL。5.2 问题TypeError: insertFn is not a function这个错误说明在customUpload函数内部insertFn这个参数是undefined。原因通常是因为wangEditor的配置结构不正确导致customUpload没有被正确绑定。在Vue/React等框架中可能是配置对象在响应式更新过程中被意外修改或覆盖。解决方案确认配置路径完全正确MENU_CONF.uploadImage.customUpload。在框架中使用时确保配置对象是稳定的。可以用useMemo(React) 或computed(Vue) 来包装配置避免重复渲染导致引用变化。在函数开头加一个日志console.log(‘insertFn is:’, typeof insertFn, insertFn)确认其存在。5.3 问题跨域请求被阻止如果你的编辑器页面部署在https://editor.example.com而上传接口在https://api.example.com就会发生跨域。现象浏览器控制台报错CORS policy。解决方案必须在后端上传接口的响应头中配置正确的CORS策略。Access-Control-Allow-Origin: https://editor.example.com // 或 * (不推荐生产环境使用) Access-Control-Allow-Methods: POST, OPTIONS Access-Control-Allow-Headers: Authorization, Content-Type对于带认证的请求如携带Token还需要处理预检请求OPTIONS。5.4 问题大视频上传超时或失败上传大文件时可能会遇到网络超时、服务器请求超时或响应超时。解决方案前端分片上传如前面场景四所述这是最彻底的解决方案。将大文件切片分多个请求上传。调整超时时间如果你使用的是简单上传可以适当增加前端请求的超时时间如axios的timeout配置和后端服务器的相关超时设置如Nginx的client_max_body_size和proxy_read_timeout。提供进度反馈让用户知道上传仍在进行中避免用户误认为卡死而刷新页面。5.5 实战技巧统一封装上传函数在实际项目中上传逻辑可能被多处使用。将customUpload的核心逻辑抽离成一个独立的函数或类是保持代码清晰和可维护性的关键。// uploader.js class FileUploader { constructor(options) { this.endpoint options.endpoint; this.getToken options.getToken; // 获取认证Token的函数 this.onProgress options.onProgress; } async upload(file) { const formData new FormData(); formData.append(‘file’, file); const headers {}; if (this.getToken) { headers[‘Authorization’] Bearer ${await this.getToken()}; } const response await axios.post(this.endpoint, formData, { headers, onUploadProgress: this.onProgress, timeout: 60000, }); // 统一处理响应格式 if (response.data?.code 0) { return response.data.data.url; } else { throw new Error(response.data?.msg || ‘上传失败’); } } } // editor-config.js const uploader new FileUploader({ endpoint: ‘/api/upload’, getToken: () localStorage.getItem(‘token’), }); const editorConfig { MENU_CONF: { uploadImage: { customUpload: async (file, insertFn) { try { const url await uploader.upload(file); insertFn(url); } catch (error) { console.error(‘Upload failed:’, error); // 统一错误提示 } }, }, uploadVideo: { // 可以复用同一个 uploader或者配置不同的 endpoint customUpload: async (file, insertFn) { try { const url await uploader.upload(file); insertFn(url); } catch (error) { console.error(‘Upload failed:’, error); } }, }, }, };这种封装方式使得上传逻辑、错误处理、进度回调都集中在一处未来更换云服务商或调整API时只需修改FileUploader类即可编辑器配置部分几乎不用动。最后记住一个核心原则customUpload的职责是“搬运”和“通知”。它负责把文件搬运到你指定的地方并在成功后把得到的地址通知给编辑器。只要牢牢抓住这个核心无论业务逻辑多复杂你都能清晰地构建出稳定可靠的上传功能。