简介这份PDF资料面向使用Summernote富文本编辑器的前端开发者聚焦于解决编辑器默认不支持图片上传到服务器的问题。内容围绕onImageUpload回调与insertImage API展开讲解如何挂接文件上传事件、借助FormData与jQuery.ajax将图片POST到后端接口并在上传成功后把返回的图片URL插入编辑框同时提及低版本IE兼容性与错误处理的注意事项。资源包共1个PDF文件约50KB篇幅精炼适合作为快速查阅的参考手册。目前已有689人学习下载说明该方案在实际项目中具有一定参考价值。读者可从中获得一套可直接套用的图片上传实现思路与核心代码片段理解Summernote图片上传的关键接口用法并据此结合自身后端服务进行调整与优化减少反复搜索官方文档与试错的时间成本。1. Summernote 图片上传为什么你的 base64 方案迟早要翻车很多人在后台富文本编辑器里集成 Summernote第一反应是直接用它的默认图片插入功能——选一张图编辑器自动把图片转成 base64 塞进 HTML。本地测试一切正常提交保存也看不出问题。等到文章发了十几篇数据库字段开始膨胀列表页加载越来越慢接口返回的 JSON 动辄几 MB你才意识到这个方案从一开始就不该上生产。Summernote 实现图片上传功能的简单方法核心就一件事把默认的 base64 内嵌改成「上传到服务端、返回 URL、编辑器只存链接」。这件事听起来简单但真正落地时会碰到 CSRF 拦截、跨域、图片尺寸限制、回调格式对不上等一堆细节。这篇笔记面向的是正在用 Summernote 做后台编辑器的前后端开发者不管你用的是 Spring Boot、Express 还是 Django思路一致代码按你熟悉的栈替换即可。接下来我会把选型理由、最小可跑通实现、参数配置和踩过的坑按顺序讲清楚。2. 从 base64 到服务端 URLSummernote 图片上传的选型与最小实现2.1 为什么必须放弃默认的 base64 内嵌Summernote 默认的图片处理逻辑是监听粘贴或选择图片事件用 FileReader 把图片读成 data URL然后直接插入编辑区。这个设计在 demo 阶段很友好零后端依赖但它有三个致命问题。第一是存储成本。一张 200KB 的截图转成 base64 后大约 270KB因为编码膨胀约 33%。如果一篇文章插 10 张图单条记录的 HTML 字段就接近 3MB。数据库的 TEXT 或 LONGTEXT 字段虽然能存但查询、备份、迁移都会变得极其痛苦。第二是传输成本。列表接口如果返回了 content 字段每个请求都要拖着这几 MB 的字符串走。前端渲染时浏览器还要解析 base64 并解码首屏时间肉眼可见地变长。第三是无法复用。base64 图片和文章内容绑死你想在另一篇文章里引用同一张图只能重新上传一份。CDN 缓存、图片压缩、懒加载这些优化手段全都用不上。所以正确的做法是Summernote 只负责触发上传动作和展示图片真正的文件存储交给服务端编辑器里存的是图片 URL。这也是绝大多数生产环境后台编辑器的标准做法。2.2 前端配置callbacks.onImageUpload 的正确写法Summernote 提供了onImageUpload回调这是接管图片上传的入口。当用户选择或粘贴图片时这个回调会被触发参数是文件列表。你需要在回调里把文件通过 FormData 发到自己的上传接口拿到 URL 后再用editor.insertImage插回编辑器。// 初始化 Summernote 并接管图片上传 $(#editor).summernote({ height: 400, lang: zh-CN, toolbar: [ [insert, [picture, link, video]], [style, [bold, italic, underline, clear]], [para, [ul, ol, paragraph]] ], callbacks: { onImageUpload: function (files) { // files 是 FileList可能一次多张逐张上传 for (let i 0; i files.length; i) { uploadImage(files[i], this); } } } }); function uploadImage(file, editor) { // 前端先做一次大小和类型校验减少无效请求 const MAX_SIZE 5 * 1024 * 1024; // 5MB const ALLOW [image/jpeg, image/png, image/gif, image/webp]; if (file.size MAX_SIZE) { alert(图片不能超过 5MB); return; } if (!ALLOW.includes(file.type)) { alert(只支持 JPG/PNG/GIF/WebP 格式); 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 边界 headers: { // 如果后端用 token 鉴权这里带上用 Cookie 的话可省略 X-CSRF-Token: getCsrfToken() }, success: function (res) { if (res.code 0 res.data res.data.url) { // 关键把服务端返回的 URL 插回编辑器 editor.insertImage(editor, res.data.url); } else { alert(res.msg || 上传失败); } }, error: function (xhr) { console.error(upload error, xhr.status, xhr.responseText); alert(上传失败请重试); } }); }这段代码有几个参数必须注意。processData: false和contentType: false是 FormData 上传的固定搭配漏掉任何一个都会导致后端收不到文件。formData.append(file, file)里的字段名要和后端RequestParam(file)或req.file的约定完全一致这是最常见的 400 错误来源。editor.insertImage(editor, url)的第一个参数是编辑器实例在回调里用this拿到如果抽成独立函数就要显式传进去否则会报insertImage is not a function。2.3 后端接口接收文件、落盘、返回 URL后端要做的事情很明确接收 multipart 请求校验文件类型和大小生成不冲突的文件名存到指定目录或对象存储返回可访问的 URL。下面用 Node.js Express multer 举例其他栈逻辑一致。// Express multer 实现图片上传接口 const express require(express); const multer require(multer); const path require(path); const crypto require(crypto); const router express.Router(); // 磁盘存储配置 const storage multer.diskStorage({ destination: function (req, file, cb) { // 按日期分目录避免单目录文件过多 const day new Date().toISOString().slice(0, 10); const dir path.join(__dirname, ../public/uploads, day); require(fs).mkdirSync(dir, { recursive: true }); cb(null, dir); }, filename: function (req, file, cb) { // 用随机串 原扩展名避免中文名和重名问题 const ext path.extname(file.originalname).toLowerCase(); const name crypto.randomBytes(16).toString(hex) ext; cb(null, name); } }); // 文件类型白名单校验 const fileFilter function (req, file, cb) { const allow [image/jpeg, image/png, image/gif, image/webp]; if (allow.includes(file.mimetype)) { cb(null, true); } else { cb(new Error(UNSUPPORTED_TYPE)); } }; const upload multer({ storage: storage, fileFilter: fileFilter, limits: { fileSize: 5 * 1024 * 1024 } // 5MB和前端保持一致 }); router.post(/api/upload/image, upload.single(file), function (req, res) { if (!req.file) { return res.json({ code: 1, msg: 未接收到文件 }); } // 拼接可访问 URL注意和静态资源目录对应 const day new Date().toISOString().slice(0, 10); const url /uploads/${day}/${req.file.filename}; res.json({ code: 0, msg: ok, data: { url: url } }); }); // 统一错误处理把 multer 的错误转成友好提示 router.use(function (err, req, res, next) { if (err.message UNSUPPORTED_TYPE) { return res.json({ code: 1, msg: 不支持的图片格式 }); } if (err.code LIMIT_FILE_SIZE) { return res.json({ code: 1, msg: 图片超过大小限制 }); } res.json({ code: 1, msg: 上传失败 }); }); module.exports router;后端这段代码的关键点在于destination按日期分目录防止单目录下文件数量爆炸导致ls都卡filename用随机串而不是原始文件名规避中文乱码、路径穿越和重名覆盖fileFilter校验 MIME 类型但要注意 MIME 可以被伪造更严格的做法是读取文件头魔数校验。limits.fileSize是服务端最后一道防线前端校验可以被绕过服务端必须自己兜底。返回格式{ code: 0, data: { url: ... } }是自定义约定前端success回调里按这个结构解析。如果你用的框架有统一响应包装确保url字段能被前端取到这是前后端联调时最容易对不上的地方。2.4 静态资源目录与 URL 前缀的对应关系上传成功后图片能不能显示取决于 URL 能不能被正确访问。上面代码把文件存到public/uploads/日期/文件名URL 返回/uploads/日期/文件名那么 Express 必须把public目录挂成静态资源// 静态资源映射必须放在路由注册之前或之后但路径不冲突 app.use(/uploads, express.static(path.join(__dirname, public/uploads)));如果你用的是 Nginx 反代常见做法是让 Nginx 直接处理/uploads/路径不走应用服务器location /uploads/ { alias /var/www/app/public/uploads/; expires 30d; add_header Cache-Control public; }这里有个血泪经验开发环境用相对路径/uploads/xxx没问题但生产环境如果前端和后端不同域相对路径会指向前端域名图片 404。解决办法是后端返回完整 URL带协议和域名或者前端配置一个VITE_API_BASE之类的变量拼接。我一般倾向后者因为域名可能随环境变化写死在数据库里以后迁移很麻烦。3. 参数调优与边界处理让上传功能真正可用3.1 图片尺寸限制前端、后端、Nginx 三层都要设图片上传失败最常见的原因不是代码写错而是某一层的大小限制没对齐。请求体从浏览器到后端要经过多个环节任何一层超限都会返回 413。层级配置项常见默认值建议值前端自定义校验无5MBNginxclient_max_body_size1MB10MB应用multer limits.fileSize无限制5MB框架Spring max-file-size1MB5MBNginx 的client_max_body_size默认只有 1MB这是最隐蔽的坑。前端选了张 2MB 的图请求还没到应用就被 Nginx 拒了返回 413前端error回调里只能看到状态码根本不知道是 Nginx 拦的。排查时先看 Nginx 错误日志再逐层往上查。3.2 粘贴上传和拖拽上传的处理差异Summernote 的onImageUpload回调对「点击工具栏选图」「直接粘贴截图」「拖拽图片进编辑区」三种操作都会触发但行为有细微差别。粘贴截图时files里的 File 对象name字段可能是image.png这种通用名没有扩展名信息后端如果依赖原始文件名判断类型就会失败。所以后端校验必须基于 MIME 或文件魔数不能信originalname。拖拽上传时如果用户拖的是网页上的图片不是本地文件Summernote 默认会插入图片的远程 URL不走onImageUpload。这种情况一般不用管但如果你的业务要求所有图片必须落到自己服务器就需要额外监听onPaste或onDrop事件做拦截把远程 URL 下载后再上传。这个需求比较少见大多数后台场景允许外链图片存在。3.3 上传进度与多图并发一次选多张图时上面的代码是for循环里连续发多个 AJAX 请求浏览器对同域并发请求有数量限制通常 6 个超过的会排队。如果用户一次选 20 张图后面的请求要等前面的完成体验上像是卡住了。更好的做法是用Promise.all控制并发数或者加一个上传进度提示。// 限制并发数为 3 的上传队列 async function uploadBatch(files, editor, concurrency 3) { const queue Array.from(files); const workers []; for (let i 0; i concurrency; i) { workers.push((async () { while (queue.length) { const file queue.shift(); try { const url await uploadOne(file); // 返回 Promisestring editor.insertImage(editor, url); } catch (e) { console.error(上传失败, file.name, e); } } })()); } await Promise.all(workers); }并发数设 3 是个折中值既能利用带宽又不会把服务端打满。如果你的上传接口做了限流并发数要相应调低否则会触发 429。4. 避坑指南Summernote 图片上传的五个高频翻车现场4.1 现象上传成功但编辑器里图片不显示控制台 404原因通常是后端返回的 URL 和静态资源映射路径对不上。比如文件存在public/uploads/2024-01-01/abc.png但返回的 URL 是/upload/2024-01-01/abc.png少了个 s或者 Nginx 的alias路径写错。还有一种情况是返回了相对路径但前端页面在子路由下相对路径解析到了错误的基准地址。解决打开浏览器 Network 面板看图片请求的实际 URL再对照服务器上文件的真实路径逐段核对。最稳妥的做法是后端返回完整 URL或者前端统一拼接 base 地址。4.2 现象后端收到文件但req.file为 undefined原因多半是 FormData 的字段名和后端期望的不一致。前端formData.append(file, file)后端upload.single(file)两边必须完全一样。另一个常见原因是contentType没设成falsejQuery 自动加了application/x-www-form-urlencoded头导致 multipart 边界丢失后端解析不出文件。解决检查字段名拼写确认processData: false和contentType: false都写了。用浏览器 Network 面板看请求头是不是multipart/form-data; boundary...如果不是就是这两个参数的问题。4.3 现象CSRF 校验失败返回 403如果后端开了 CSRF 保护Spring Security、Django 默认都开AJAX 上传请求需要带上 CSRF token。Summernote 的onImageUpload走的是普通 AJAX不会自动带 token。解决在请求头里加X-CSRF-Token值从页面 meta 标签或 Cookie 里取。Django 的话可以用getCookie(csrftoken)Spring Security 可以从meta name_csrf content...读。注意 token 要放在 header 而不是 FormData 里因为 multipart 请求的 body 解析顺序可能影响 token 读取。4.4 现象图片上传后文件名乱码或变成一串数字原因是后端直接用了originalname作为存储文件名中文文件名在不同操作系统和编码下表现不一致而且存在路径穿越风险用户可以把文件名改成../../etc/passwd。解决永远不要用原始文件名做存储名。用 UUID 或随机串 原扩展名原始文件名只存数据库做展示用。扩展名也要做白名单校验不能直接取originalname的后缀因为攻击者可以构造evil.php.jpg这种双扩展名。4.5 现象大图上传后页面卡顿编辑器响应变慢原因是插入的图片没有做尺寸限制一张 4000x3000 的原图直接显示在编辑器里浏览器渲染和内存占用都很高。Summernote 本身不会压缩图片它只是把 URL 插进去。解决后端在上传时做一次压缩或者生成缩略图。用sharpNode.js或ThumbnailsJava把图片最长边限制在 1920px质量压到 80%通常能减少 70% 以上的体积。如果不想动原图至少在前端展示时用 CSS 限制max-width: 100%但这只解决显示问题不解决传输和存储问题。5. 进阶技巧把上传做成可配置、可观测的模块5.1 用配置项管理上传策略把上传相关的参数抽成配置不同环境用不同值避免改代码。下面是一个配置示例// config/upload.js module.exports { maxSize: process.env.UPLOAD_MAX_SIZE || 5 * 1024 * 1024, allowTypes: [image/jpeg, image/png, image/gif, image/webp], storage: process.env.UPLOAD_STORAGE || local, // local | oss | s3 localDir: process.env.UPLOAD_LOCAL_DIR || public/uploads, urlPrefix: process.env.UPLOAD_URL_PREFIX || /uploads, compress: { enabled: true, maxWidth: 1920, quality: 80 } };这样切换存储后端时只需要改storage的值上传接口里根据配置走不同分支。本地开发用local生产用对象存储代码不用动。5.2 上传日志出问题时能快速定位每次上传记录一条日志包含时间、文件名、大小、类型、来源 IP、结果。不用很复杂一个简单的日志中间件就够function uploadLogger(req, res, next) { const start Date.now(); res.on(finish, function () { const log { time: new Date().toISOString(), ip: req.ip, size: req.file ? req.file.size : 0, name: req.file ? req.file.originalname : , status: res.statusCode, cost: Date.now() - start }; console.log([UPLOAD], JSON.stringify(log)); }); next(); }有了这个日志用户反馈「上传失败」时你能快速判断是文件太大、类型不对还是服务端异常不用靠猜。5.3 验证上传功能是否真的可用写完代码别急着交付按这个清单过一遍选一张正常 JPG 能上传并显示选一张超过限制的图前端有提示且不发请求把限制调小确认后端也拦截粘贴一张截图确认走的是上传而不是 base64上传后刷新页面图片还在用另一个浏览器打开同一篇文章图片能显示把图片 URL 复制到新标签页能直接访问。这七步走完基本能覆盖 90% 的线上问题。我自己踩过最深的一个坑是本地开发用localhost上传图片存的是相对路径一切正常部署到测试环境后前端域名和后端域名不同图片全部 404排查了半天才发现是 URL 拼接的问题。从那以后我养成了一个习惯上传接口返回的 URL 一定是完整可访问的绝对路径或者前端统一用环境变量拼接绝不在数据库里存相对路径。这个习惯帮我省了很多后悔药。希望帮到你。本文还有配套的精品资源点击获取
简介这份PDF资料面向使用Summernote富文本编辑器的前端开发者聚焦于解决编辑器默认不支持图片上传到服务器的问题。内容围绕onImageUpload回调与insertImage API展开讲解如何挂接文件上传事件、借助FormData与jQuery.ajax将图片POST到后端接口并在上传成功后把返回的图片URL插入编辑框同时提及低版本IE兼容性与错误处理的注意事项。资源包共1个PDF文件约50KB篇幅精炼适合作为快速查阅的参考手册。目前已有689人学习下载说明该方案在实际项目中具有一定参考价值。读者可从中获得一套可直接套用的图片上传实现思路与核心代码片段理解Summernote图片上传的关键接口用法并据此结合自身后端服务进行调整与优化减少反复搜索官方文档与试错的时间成本。1. Summernote 图片上传为什么你的 base64 方案迟早要翻车很多人在后台富文本编辑器里集成 Summernote第一反应是直接用它的默认图片插入功能——选一张图编辑器自动把图片转成 base64 塞进 HTML。本地测试一切正常提交保存也看不出问题。等到文章发了十几篇数据库字段开始膨胀列表页加载越来越慢接口返回的 JSON 动辄几 MB你才意识到这个方案从一开始就不该上生产。Summernote 实现图片上传功能的简单方法核心就一件事把默认的 base64 内嵌改成「上传到服务端、返回 URL、编辑器只存链接」。这件事听起来简单但真正落地时会碰到 CSRF 拦截、跨域、图片尺寸限制、回调格式对不上等一堆细节。这篇笔记面向的是正在用 Summernote 做后台编辑器的前后端开发者不管你用的是 Spring Boot、Express 还是 Django思路一致代码按你熟悉的栈替换即可。接下来我会把选型理由、最小可跑通实现、参数配置和踩过的坑按顺序讲清楚。2. 从 base64 到服务端 URLSummernote 图片上传的选型与最小实现2.1 为什么必须放弃默认的 base64 内嵌Summernote 默认的图片处理逻辑是监听粘贴或选择图片事件用 FileReader 把图片读成 data URL然后直接插入编辑区。这个设计在 demo 阶段很友好零后端依赖但它有三个致命问题。第一是存储成本。一张 200KB 的截图转成 base64 后大约 270KB因为编码膨胀约 33%。如果一篇文章插 10 张图单条记录的 HTML 字段就接近 3MB。数据库的 TEXT 或 LONGTEXT 字段虽然能存但查询、备份、迁移都会变得极其痛苦。第二是传输成本。列表接口如果返回了 content 字段每个请求都要拖着这几 MB 的字符串走。前端渲染时浏览器还要解析 base64 并解码首屏时间肉眼可见地变长。第三是无法复用。base64 图片和文章内容绑死你想在另一篇文章里引用同一张图只能重新上传一份。CDN 缓存、图片压缩、懒加载这些优化手段全都用不上。所以正确的做法是Summernote 只负责触发上传动作和展示图片真正的文件存储交给服务端编辑器里存的是图片 URL。这也是绝大多数生产环境后台编辑器的标准做法。2.2 前端配置callbacks.onImageUpload 的正确写法Summernote 提供了onImageUpload回调这是接管图片上传的入口。当用户选择或粘贴图片时这个回调会被触发参数是文件列表。你需要在回调里把文件通过 FormData 发到自己的上传接口拿到 URL 后再用editor.insertImage插回编辑器。// 初始化 Summernote 并接管图片上传 $(#editor).summernote({ height: 400, lang: zh-CN, toolbar: [ [insert, [picture, link, video]], [style, [bold, italic, underline, clear]], [para, [ul, ol, paragraph]] ], callbacks: { onImageUpload: function (files) { // files 是 FileList可能一次多张逐张上传 for (let i 0; i files.length; i) { uploadImage(files[i], this); } } } }); function uploadImage(file, editor) { // 前端先做一次大小和类型校验减少无效请求 const MAX_SIZE 5 * 1024 * 1024; // 5MB const ALLOW [image/jpeg, image/png, image/gif, image/webp]; if (file.size MAX_SIZE) { alert(图片不能超过 5MB); return; } if (!ALLOW.includes(file.type)) { alert(只支持 JPG/PNG/GIF/WebP 格式); 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 边界 headers: { // 如果后端用 token 鉴权这里带上用 Cookie 的话可省略 X-CSRF-Token: getCsrfToken() }, success: function (res) { if (res.code 0 res.data res.data.url) { // 关键把服务端返回的 URL 插回编辑器 editor.insertImage(editor, res.data.url); } else { alert(res.msg || 上传失败); } }, error: function (xhr) { console.error(upload error, xhr.status, xhr.responseText); alert(上传失败请重试); } }); }这段代码有几个参数必须注意。processData: false和contentType: false是 FormData 上传的固定搭配漏掉任何一个都会导致后端收不到文件。formData.append(file, file)里的字段名要和后端RequestParam(file)或req.file的约定完全一致这是最常见的 400 错误来源。editor.insertImage(editor, url)的第一个参数是编辑器实例在回调里用this拿到如果抽成独立函数就要显式传进去否则会报insertImage is not a function。2.3 后端接口接收文件、落盘、返回 URL后端要做的事情很明确接收 multipart 请求校验文件类型和大小生成不冲突的文件名存到指定目录或对象存储返回可访问的 URL。下面用 Node.js Express multer 举例其他栈逻辑一致。// Express multer 实现图片上传接口 const express require(express); const multer require(multer); const path require(path); const crypto require(crypto); const router express.Router(); // 磁盘存储配置 const storage multer.diskStorage({ destination: function (req, file, cb) { // 按日期分目录避免单目录文件过多 const day new Date().toISOString().slice(0, 10); const dir path.join(__dirname, ../public/uploads, day); require(fs).mkdirSync(dir, { recursive: true }); cb(null, dir); }, filename: function (req, file, cb) { // 用随机串 原扩展名避免中文名和重名问题 const ext path.extname(file.originalname).toLowerCase(); const name crypto.randomBytes(16).toString(hex) ext; cb(null, name); } }); // 文件类型白名单校验 const fileFilter function (req, file, cb) { const allow [image/jpeg, image/png, image/gif, image/webp]; if (allow.includes(file.mimetype)) { cb(null, true); } else { cb(new Error(UNSUPPORTED_TYPE)); } }; const upload multer({ storage: storage, fileFilter: fileFilter, limits: { fileSize: 5 * 1024 * 1024 } // 5MB和前端保持一致 }); router.post(/api/upload/image, upload.single(file), function (req, res) { if (!req.file) { return res.json({ code: 1, msg: 未接收到文件 }); } // 拼接可访问 URL注意和静态资源目录对应 const day new Date().toISOString().slice(0, 10); const url /uploads/${day}/${req.file.filename}; res.json({ code: 0, msg: ok, data: { url: url } }); }); // 统一错误处理把 multer 的错误转成友好提示 router.use(function (err, req, res, next) { if (err.message UNSUPPORTED_TYPE) { return res.json({ code: 1, msg: 不支持的图片格式 }); } if (err.code LIMIT_FILE_SIZE) { return res.json({ code: 1, msg: 图片超过大小限制 }); } res.json({ code: 1, msg: 上传失败 }); }); module.exports router;后端这段代码的关键点在于destination按日期分目录防止单目录下文件数量爆炸导致ls都卡filename用随机串而不是原始文件名规避中文乱码、路径穿越和重名覆盖fileFilter校验 MIME 类型但要注意 MIME 可以被伪造更严格的做法是读取文件头魔数校验。limits.fileSize是服务端最后一道防线前端校验可以被绕过服务端必须自己兜底。返回格式{ code: 0, data: { url: ... } }是自定义约定前端success回调里按这个结构解析。如果你用的框架有统一响应包装确保url字段能被前端取到这是前后端联调时最容易对不上的地方。2.4 静态资源目录与 URL 前缀的对应关系上传成功后图片能不能显示取决于 URL 能不能被正确访问。上面代码把文件存到public/uploads/日期/文件名URL 返回/uploads/日期/文件名那么 Express 必须把public目录挂成静态资源// 静态资源映射必须放在路由注册之前或之后但路径不冲突 app.use(/uploads, express.static(path.join(__dirname, public/uploads)));如果你用的是 Nginx 反代常见做法是让 Nginx 直接处理/uploads/路径不走应用服务器location /uploads/ { alias /var/www/app/public/uploads/; expires 30d; add_header Cache-Control public; }这里有个血泪经验开发环境用相对路径/uploads/xxx没问题但生产环境如果前端和后端不同域相对路径会指向前端域名图片 404。解决办法是后端返回完整 URL带协议和域名或者前端配置一个VITE_API_BASE之类的变量拼接。我一般倾向后者因为域名可能随环境变化写死在数据库里以后迁移很麻烦。3. 参数调优与边界处理让上传功能真正可用3.1 图片尺寸限制前端、后端、Nginx 三层都要设图片上传失败最常见的原因不是代码写错而是某一层的大小限制没对齐。请求体从浏览器到后端要经过多个环节任何一层超限都会返回 413。层级配置项常见默认值建议值前端自定义校验无5MBNginxclient_max_body_size1MB10MB应用multer limits.fileSize无限制5MB框架Spring max-file-size1MB5MBNginx 的client_max_body_size默认只有 1MB这是最隐蔽的坑。前端选了张 2MB 的图请求还没到应用就被 Nginx 拒了返回 413前端error回调里只能看到状态码根本不知道是 Nginx 拦的。排查时先看 Nginx 错误日志再逐层往上查。3.2 粘贴上传和拖拽上传的处理差异Summernote 的onImageUpload回调对「点击工具栏选图」「直接粘贴截图」「拖拽图片进编辑区」三种操作都会触发但行为有细微差别。粘贴截图时files里的 File 对象name字段可能是image.png这种通用名没有扩展名信息后端如果依赖原始文件名判断类型就会失败。所以后端校验必须基于 MIME 或文件魔数不能信originalname。拖拽上传时如果用户拖的是网页上的图片不是本地文件Summernote 默认会插入图片的远程 URL不走onImageUpload。这种情况一般不用管但如果你的业务要求所有图片必须落到自己服务器就需要额外监听onPaste或onDrop事件做拦截把远程 URL 下载后再上传。这个需求比较少见大多数后台场景允许外链图片存在。3.3 上传进度与多图并发一次选多张图时上面的代码是for循环里连续发多个 AJAX 请求浏览器对同域并发请求有数量限制通常 6 个超过的会排队。如果用户一次选 20 张图后面的请求要等前面的完成体验上像是卡住了。更好的做法是用Promise.all控制并发数或者加一个上传进度提示。// 限制并发数为 3 的上传队列 async function uploadBatch(files, editor, concurrency 3) { const queue Array.from(files); const workers []; for (let i 0; i concurrency; i) { workers.push((async () { while (queue.length) { const file queue.shift(); try { const url await uploadOne(file); // 返回 Promisestring editor.insertImage(editor, url); } catch (e) { console.error(上传失败, file.name, e); } } })()); } await Promise.all(workers); }并发数设 3 是个折中值既能利用带宽又不会把服务端打满。如果你的上传接口做了限流并发数要相应调低否则会触发 429。4. 避坑指南Summernote 图片上传的五个高频翻车现场4.1 现象上传成功但编辑器里图片不显示控制台 404原因通常是后端返回的 URL 和静态资源映射路径对不上。比如文件存在public/uploads/2024-01-01/abc.png但返回的 URL 是/upload/2024-01-01/abc.png少了个 s或者 Nginx 的alias路径写错。还有一种情况是返回了相对路径但前端页面在子路由下相对路径解析到了错误的基准地址。解决打开浏览器 Network 面板看图片请求的实际 URL再对照服务器上文件的真实路径逐段核对。最稳妥的做法是后端返回完整 URL或者前端统一拼接 base 地址。4.2 现象后端收到文件但req.file为 undefined原因多半是 FormData 的字段名和后端期望的不一致。前端formData.append(file, file)后端upload.single(file)两边必须完全一样。另一个常见原因是contentType没设成falsejQuery 自动加了application/x-www-form-urlencoded头导致 multipart 边界丢失后端解析不出文件。解决检查字段名拼写确认processData: false和contentType: false都写了。用浏览器 Network 面板看请求头是不是multipart/form-data; boundary...如果不是就是这两个参数的问题。4.3 现象CSRF 校验失败返回 403如果后端开了 CSRF 保护Spring Security、Django 默认都开AJAX 上传请求需要带上 CSRF token。Summernote 的onImageUpload走的是普通 AJAX不会自动带 token。解决在请求头里加X-CSRF-Token值从页面 meta 标签或 Cookie 里取。Django 的话可以用getCookie(csrftoken)Spring Security 可以从meta name_csrf content...读。注意 token 要放在 header 而不是 FormData 里因为 multipart 请求的 body 解析顺序可能影响 token 读取。4.4 现象图片上传后文件名乱码或变成一串数字原因是后端直接用了originalname作为存储文件名中文文件名在不同操作系统和编码下表现不一致而且存在路径穿越风险用户可以把文件名改成../../etc/passwd。解决永远不要用原始文件名做存储名。用 UUID 或随机串 原扩展名原始文件名只存数据库做展示用。扩展名也要做白名单校验不能直接取originalname的后缀因为攻击者可以构造evil.php.jpg这种双扩展名。4.5 现象大图上传后页面卡顿编辑器响应变慢原因是插入的图片没有做尺寸限制一张 4000x3000 的原图直接显示在编辑器里浏览器渲染和内存占用都很高。Summernote 本身不会压缩图片它只是把 URL 插进去。解决后端在上传时做一次压缩或者生成缩略图。用sharpNode.js或ThumbnailsJava把图片最长边限制在 1920px质量压到 80%通常能减少 70% 以上的体积。如果不想动原图至少在前端展示时用 CSS 限制max-width: 100%但这只解决显示问题不解决传输和存储问题。5. 进阶技巧把上传做成可配置、可观测的模块5.1 用配置项管理上传策略把上传相关的参数抽成配置不同环境用不同值避免改代码。下面是一个配置示例// config/upload.js module.exports { maxSize: process.env.UPLOAD_MAX_SIZE || 5 * 1024 * 1024, allowTypes: [image/jpeg, image/png, image/gif, image/webp], storage: process.env.UPLOAD_STORAGE || local, // local | oss | s3 localDir: process.env.UPLOAD_LOCAL_DIR || public/uploads, urlPrefix: process.env.UPLOAD_URL_PREFIX || /uploads, compress: { enabled: true, maxWidth: 1920, quality: 80 } };这样切换存储后端时只需要改storage的值上传接口里根据配置走不同分支。本地开发用local生产用对象存储代码不用动。5.2 上传日志出问题时能快速定位每次上传记录一条日志包含时间、文件名、大小、类型、来源 IP、结果。不用很复杂一个简单的日志中间件就够function uploadLogger(req, res, next) { const start Date.now(); res.on(finish, function () { const log { time: new Date().toISOString(), ip: req.ip, size: req.file ? req.file.size : 0, name: req.file ? req.file.originalname : , status: res.statusCode, cost: Date.now() - start }; console.log([UPLOAD], JSON.stringify(log)); }); next(); }有了这个日志用户反馈「上传失败」时你能快速判断是文件太大、类型不对还是服务端异常不用靠猜。5.3 验证上传功能是否真的可用写完代码别急着交付按这个清单过一遍选一张正常 JPG 能上传并显示选一张超过限制的图前端有提示且不发请求把限制调小确认后端也拦截粘贴一张截图确认走的是上传而不是 base64上传后刷新页面图片还在用另一个浏览器打开同一篇文章图片能显示把图片 URL 复制到新标签页能直接访问。这七步走完基本能覆盖 90% 的线上问题。我自己踩过最深的一个坑是本地开发用localhost上传图片存的是相对路径一切正常部署到测试环境后前端域名和后端域名不同图片全部 404排查了半天才发现是 URL 拼接的问题。从那以后我养成了一个习惯上传接口返回的 URL 一定是完整可访问的绝对路径或者前端统一用环境变量拼接绝不在数据库里存相对路径。这个习惯帮我省了很多后悔药。希望帮到你。本文还有配套的精品资源点击获取
Sidecar边车模式)
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
