简介：这份PDF资料面向使用Summernote富文本编辑器的前端开发者，聚焦于解决编辑器默认不支持图片上传到服务器这一常见痛点。内容围绕onImageUpload回调与insertImage API两个核心接口展开，讲解如何挂接文件上传事件、借助FormData与jQuery.ajax将图片POST到后端接口，并在上传成功后把返回的图片URL插入编辑框，同时提及低版本IE兼容性与错误处理的注意事项。资源包为1个PDF文件，约50KB，篇幅精炼，适合作为快速查阅的参考手册。目前已有689人学习下载，说明该方案在实际项目中具有一定参考价值。读者可从中获得一套可直接套用的图片上传实现思路与关键代码片段，理解Summernote自定义上传的接口写法，并据此与自身后端服务对接，减少反复搜索与试错成本。
1. Summernote 图片上传：从 base64 到服务端落盘的必经之路
很多人在后台管理系统里用 Summernote 做富文本编辑器，文字加粗、列表、超链接都跑通了，一到图片上传就卡住。默认情况下，Summernote 会把图片转成 base64 字符串直接塞进 HTML，短内容看着没问题，一旦用户传了几张手机拍的照片，编辑器内容瞬间膨胀到几 MB，提交表单时后端接口直接超时，数据库字段也被撑爆。这不是玄学，是 Summernote 默认行为决定的。
这个标题要解决的核心问题就一个：把 Summernote 的图片从「内嵌 base64」改成「上传到服务器、返回 URL 插入」。适合正在做后台内容管理、论坛发帖、商品详情编辑的开发者，前端用 jQuery 或原生 JS 都行，后端语言不限。下面按「先理解默认行为 → 再改上传回调 → 最后处理粘贴和拖拽」的顺序拆开讲，每一步都能直接抄。
2. 先搞懂 Summernote 的图片处理链路：默认行为与改造点
2.1 默认 base64 模式为什么在真实项目里必翻车
Summernote 初始化后，工具栏上的图片按钮默认走insertImage命令，把用户选中的文件用 FileReader 读成 data URL，然后以<img src="data:image/png;base64,...">的形式插入编辑区。这个设计在官方 Demo 里很优雅，因为不需要后端配合，但放到生产环境有三个硬伤。
第一，内容体积失控。一张 2MB 的 JPG 转成 base64 后大约 2.7MB，用户传五张图，编辑器 HTML 就超过 13MB。表单提交时浏览器要序列化整个字符串，后端要解析，数据库要存储，每一环都在放大延迟。第二，无法复用。base64 图片只存在于当前这段 HTML 里，其他文章想引用同一张图只能重新上传。第三，浏览器渲染压力大。编辑区里同时存在多张 base64 大图时，光标移动、撤销重做都会明显卡顿，低配电脑上尤其明显。
所以真实项目里几乎不会保留默认行为，改造点集中在onImageUpload这个回调上。Summernote 暴露了callbacks.onImageUpload，只要你在初始化配置里覆盖它，图片按钮和粘贴、拖拽进来的图片都会走你的逻辑，不再自动转 base64。
2.2 改造点的选择：onImageUpload 与 insertImage 的分工
onImageUpload负责「拿到文件后干什么」，insertImage负责「把什么 URL 插进编辑区」。两者配合的标准流程是：在onImageUpload里遍历files数组，逐个用FormData发到后端上传接口，接口返回图片可访问的 URL，再调用$('#editor').summernote('insertImage', url)把图片插进去。
这里有个容易混淆的点：insertImage既可以接受 URL 字符串，也可以接受 base64 字符串。如果你在后端返回的是完整 URL，直接传字符串即可；如果后端返回的是相对路径，需要拼上域名或 CDN 前缀再插入，否则编辑区里图片显示裂图，但保存后前端页面可能又正常，造成「编辑时看不到、预览时能看到」的迷惑现象。
常见做法是后端统一返回{ code: 0, data: { url: 'https://cdn.example.com/upload/2025/01/abc.jpg' } }这种结构，前端取data.url后插入。注意 URL 必须是浏览器可直接访问的，不能是服务器本地文件路径。
2.3 最小可跑通的上传回调代码
下面这段代码是改造的核心，前端用 jQuery 是因为 Summernote 本身依赖它，后端接口假设为POST /api/upload/image，接收字段名file，返回 JSON。
// 初始化 Summernote 并覆盖图片上传回调 $('#editor').summernote({ height: 400, lang: 'zh-CN', toolbar: [ ['style', ['bold', 'italic', 'underline', 'clear']], ['font', ['strikethrough', 'superscript', 'subscript']], ['para', ['ul', 'ol', 'paragraph']], ['insert', ['picture', 'link', 'video']], ['view', ['fullscreen', 'codeview']] ], callbacks: { // 核心：拦截图片上传，改为服务端存储 onImageUpload: function (files) { // files 是 FileList，可能包含多张图，逐个上传 for (let i = 0; i < files.length; i++) { uploadSingleImage(files[i]); } } } }); function uploadSingleImage(file) { // 前端先做一次类型和大小校验，减少无效请求 const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']; if (!allowedTypes.includes(file.type)) { alert('仅支持 JPG/PNG/GIF/WebP 格式'); return; } if (file.size > 5 * 1024 * 1024) { alert('单张图片不能超过 5MB'); return; } const formData = new FormData(); formData.append('file', file); // 字段名要和后端约定一致 $.ajax({ url: '/api/upload/image', type: 'POST', data: formData, processData: false, // 必须 false，否则 jQuery 会转换 FormData contentType: false, // 必须 false，让浏览器自动设置 multipart 边界 success: function (res) { if (res.code === 0 && res.data && res.data.url) { // 插入图片，URL 必须是浏览器可访问的完整地址 $('#editor').summernote('insertImage', res.data.url, function ($img) { // 可选：给插入的图片加上样式，防止超出编辑区宽度 $img.css('max-width', '100%'); $img.attr('alt', file.name); }); } else { alert('上传失败：' + (res.msg || '未知错误')); } }, error: function (xhr) { // 把后端返回的错误信息尽量暴露出来，方便排查 alert('上传接口异常，状态码：' + xhr.status); } }); }逻辑说明：onImageUpload收到的是FileList，用户一次选多张图时不能只处理第一张，所以用循环逐个调用uploadSingleImage。processData: false和contentType: false是 jQuery 发 FormData 的固定搭配，漏掉任何一个都会导致后端收不到文件。insertImage的第二个参数是回调，$img是插入后的 jQuery 对象，可以在这里统一加max-width: 100%，避免大图撑破编辑区。
参数说明：height控制编辑区高度，按页面布局调；lang设成zh-CN需要额外引入语言文件，不引入会报错；toolbar里picture就是图片按钮，如果不想让用户点按钮上传，可以去掉它，只保留粘贴和拖拽上传。
3. 后端接口与存储：让图片真正落到服务器上
3.1 上传接口的四个关键约束
前端改完后，后端接口必须满足几个条件才能配合上。第一，接收字段名要和前端formData.append('file', file)一致，否则$_FILES或request.files里取不到。第二，返回结构要包含前端约定的code和data.url，不要返回纯文本或重定向。第三，接口不能有登录态拦截导致的 302 跳转，否则 jQuery 的success不会触发，会走到error。第四，上传目录要有写权限，且返回的 URL 要能通过 Web 服务器直接访问。
以常见的后端处理为例，核心步骤是：校验 MIME 类型和扩展名、生成不冲突的文件名、按日期分目录存储、返回可访问 URL。文件名不要用用户原始文件名，避免中文、空格、特殊字符导致 URL 异常，也避免同名覆盖。常见做法是用时间戳加随机串，例如20250115_8f3a2b1c.jpg。
3.2 一个可复用的上传处理伪代码
不同语言写法不同，但流程一致。下面用伪代码描述，你按自己技术栈翻译即可。
# 伪代码：图片上传处理流程 def upload_image(request): file = request.files.get('file') # 字段名必须和前端一致 if not file: return json_response(code=1, msg='未收到文件') # 1. 校验扩展名白名单 ext = get_extension(file.filename).lower() if ext not in ['jpg', 'jpeg', 'png', 'gif', 'webp']: return json_response(code=1, msg='不支持的格式') # 2. 校验真实 MIME，防止改扩展名绕过 if file.mimetype not in ['image/jpeg', 'image/png', 'image/gif', 'image/webp']: return json_response(code=1, msg='文件类型不合法') # 3. 生成安全文件名，按日期分目录 date_path = datetime.now().strftime('%Y/%m/%d') safe_name = generate_random_name() + '.' + ext save_path = os.path.join(UPLOAD_ROOT, date_path, safe_name) ensure_dir(os.path.dirname(save_path)) file.save(save_path) # 4. 返回完整可访问 URL url = CDN_PREFIX + '/' + date_path + '/' + safe_name return json_response(code=0, data={'url': url})逻辑说明：第 2 步的 MIME 校验不能省，只靠扩展名判断会被改后缀的文件绕过。第 3 步按日期分目录是为了避免单目录文件过多导致ls或文件管理器卡死，也方便后续按时间清理。第 4 步的CDN_PREFIX如果暂时没有 CDN，就填 Web 服务器的静态资源域名或相对路径前缀。
参数说明：UPLOAD_ROOT是服务器上的物理存储根目录，要确保 Web 服务器有读权限；CDN_PREFIX是 URL 前缀，本地开发时可能是http://localhost:8080/static，生产环境换成实际域名。如果后端和前端不同域，还要处理跨域，上传接口需要允许OPTIONS预检并返回正确的 CORS 头。
3.3 粘贴和拖拽上传为什么经常被忽略
用户除了点图片按钮，还会直接截图后 Ctrl+V 粘贴，或者从文件夹拖图片进编辑区。这两种操作同样会触发onImageUpload，但有个坑：粘贴的图片在 Chrome 里file.name可能是image.png这种通用名，拖拽的图片可能没有扩展名。如果后端依赖原始文件名取扩展名，就会失败。
解决办法是在前端上传前根据file.type反推扩展名，或者后端根据 MIME 类型决定存储扩展名，不信任原始文件名。另外，拖拽上传时如果用户拖的是图片 URL 而不是本地文件，Summernote 会走另一条逻辑直接插入外链图片，不会触发onImageUpload，这是正常行为，不用处理。
4. 避坑与排查：图片上传最常见的五类翻车
4.1 上传成功但编辑区不显示图片
现象：Network 面板里上传接口返回 200，data.url也有值，但编辑区里图片是裂图或空白。
原因：返回的 URL 浏览器无法直接访问。常见情况是后端返回了服务器本地路径如/var/www/upload/abc.jpg，或者返回了相对路径但编辑区所在页面路径不同导致拼接错误。
解决：在浏览器地址栏直接粘贴返回的 URL，能打开图片才算合格。如果是相对路径，前端插入前拼上正确的域名前缀。另外检查图片目录是否被 Web 服务器配置为可访问，Nginx 下需要单独的location规则。
4.2 上传接口返回 302 或 401
现象：error回调触发，xhr.status是 302 或 401，后端日志显示请求被重定向到登录页。
原因：上传接口被全局登录拦截器拦截，未登录或 token 过期时返回重定向。jQuery 的 AJAX 默认跟随 302，最终拿到的是登录页 HTML，success里解析 JSON 失败。
解决：把上传接口加入登录拦截白名单，或者在请求头里带上 token。如果必须登录，确保前端在初始化 Summernote 前已经完成登录，且 token 有效。排查时看 Network 面板的请求响应体，如果是 HTML 而不是 JSON，基本就是被拦截了。
4.3 大图上传后编辑区卡顿
现象：上传一张 4000x3000 的照片后，编辑区滚动和输入明显变慢。
原因：原图尺寸太大，浏览器渲染和内存占用高。虽然后端存的是原图，但编辑区里显示的是同一张大图。
解决：前端插入时用 CSS 限制显示尺寸只是视觉上变小，实际解码的还是原图。更彻底的做法是后端在上传时生成一张压缩后的展示图，返回展示图 URL 给编辑区，原图另存备用。或者前端在上传前用 Canvas 压缩，但会损失画质，按业务需求选。
4.4 多图上传时只成功一张
现象：一次选三张图，只有一张插入编辑区，另外两张没反应。
原因：onImageUpload里没有循环处理files，只取了files[0]。或者循环里用了同一个变量导致闭包问题。
解决：用for循环或Array.from(files).forEach逐个上传，每个请求独立。注意异步请求返回顺序不确定，插入顺序可能和选择顺序不一致，如果业务要求顺序，需要串行上传或记录索引后按序插入。
4.5 上传目录文件越来越多，磁盘报警
现象：运行几个月后服务器磁盘满，排查发现上传目录几十 GB。
原因：只上传不清理，用户传了图但文章没保存，图片成了孤儿文件。
解决：常见做法是上传时先存到临时目录，文章保存成功后再移动到正式目录，定时清理临时目录。或者定期跑脚本对比数据库里引用的图片 URL 和实际文件，删除未被引用的。这个策略要在项目初期就定，后期补很痛苦。
5. 进阶技巧：让图片上传更稳、更快、更好维护
5.1 上传前压缩：在浏览器端用 Canvas 减体积
如果业务允许轻微画质损失，前端压缩能显著减少上传时间和存储占用。核心思路是用FileReader读文件，画到 Canvas 上按最大边缩放，再导出为 Blob 上传。下面是一个可复用的压缩函数。
// 前端压缩图片，maxSize 为最大边像素，quality 为 JPEG 质量 function compressImage(file, maxSize = 1920, quality = 0.8) { return new Promise((resolve) => { const reader = new FileReader(); reader.onload = function (e) { const img = new Image(); img.onload = function () { let { width, height } = img; // 按最大边等比缩放 if (width > maxSize || height > maxSize) { if (width > height) { height = Math.round(height * maxSize / width); width = maxSize; } else { width = Math.round(width * maxSize / height); height = maxSize; } } const canvas = document.createElement('canvas'); canvas.width = width; canvas.height = height; const ctx = canvas.getContext('2d'); ctx.drawImage(img, 0, 0, width, height); // 导出为 Blob，PNG 转 JPEG 可大幅减体积 canvas.toBlob((blob) => { resolve(new File([blob], file.name.replace(/\.\w+$/, '.jpg'), { type: 'image/jpeg' })); }, 'image/jpeg', quality); }; img.src = e.target.result; }; reader.readAsDataURL(file); }); }逻辑说明：maxSize控制最长边，1920 适合大多数网页展示场景；quality是 JPEG 压缩质量，0.8 在肉眼几乎无损的前提下能减掉一半以上体积。注意 PNG 透明图转 JPEG 后透明区域会变黑，如果业务需要透明背景，保持 PNG 格式但压缩尺寸即可。
参数说明：maxSize按展示需求调，商品详情图可以设 1200，文章配图 1920 足够；quality低于 0.6 会出现明显噪点，不建议。压缩后要重新校验大小，如果压缩后反而变大（小图压缩常见），直接用原文件。
5.2 上传失败重试与用户提示
网络抖动导致上传失败时，直接弹「上传失败」体验很差。可以在uploadSingleImage里加一层重试，最多重试两次，间隔 1 秒。同时给编辑区插入一个占位提示，成功后再替换成图片，失败则移除占位并提示用户。
实现上，可以在上传前用$('#editor').summernote('insertText', '图片上传中...')插入临时文本，但更干净的做法是维护一个上传队列，在编辑器外部显示进度。Summernote 本身没有内置上传进度条，需要自己监听xhr.upload.onprogress事件更新 UI。
5.3 用配置项统一管理上传参数
项目变大后，上传接口地址、大小限制、允许格式这些参数散落在代码各处会很难维护。建议抽一个配置对象，前端初始化时读取，后端也维护一份对应的白名单，两边保持一致。
| 配置项 | 前端作用 | 后端对应 | 建议值 |
|---|---|---|---|
| uploadUrl | AJAX 请求地址 | 路由路径 | /api/upload/image |
| maxSize | 前端拦截大小 | 服务端二次校验 | 5MB |
| allowedTypes | 前端格式校验 | MIME 白名单 | jpg/png/gif/webp |
| compress | 是否前端压缩 | 无 | true |
| maxWidth | 压缩最大边 | 无 | 1920 |
这张表建议直接写进项目文档，前后端联调时对着核对，能省掉大量「前端说传了、后端说没收到」的扯皮。
5.4 一个我踩过的坑：CDN 缓存导致图片更新不生效
有次用户反馈换了图片但页面还是显示旧图，排查半天发现是 CDN 缓存了旧 URL 的内容。因为文件名是随机生成的，理论上不会重复，但那次后端生成随机串的算法有缺陷，短时间内高并发下产生了重复文件名，后上传的覆盖了先上传的，CDN 又缓存了旧内容。后来改成时间戳加更长的随机串，并在文件名里加入用户 ID 哈希，彻底避免碰撞。这个教训是：文件名唯一性不能只靠时间戳，并发场景下必须加随机因子。
图片上传这件事，前端改一个回调、后端加一个接口就能跑通，但要在生产环境稳住，校验、压缩、清理、重试这些环节一个都不能少。我现在的习惯是，任何上传功能上线前，先用手机拍的大图、截图粘贴、多选拖拽三种方式各测一遍，再模拟一次网络断开看错误提示是否友好。希望帮到你。
本文还有配套的精品资源，点击获取
