HTML5多图上传预览源码：File API与FormData实战

简介面向前端初学者和需要实现本地图片预览功能的开发者这份 HTML5 多图片上传预览源码围绕 File API、FileReader 与拖放 API 展开演示如何在不依赖服务器端处理的情况下完成多选图片读取、Base64 预览和拖拽上传交互。压缩包共 18 个文件约 145KB包含 9 个 png 界面图片、5 个 js 脚本、1 个 css 样式、1 个 html 页面及 2 个 url 快捷方式便于直接查看页面结构、样式组织与脚本调用关系。已有 1473 人学习下载适合作为课堂示例或小型项目原型参考。源码保留了页面入口、示例脚本、上传控制与核心逻辑等模块可帮助读者理解文件读取回调、闭包保存文件对象、dragover 与 drop 事件处理等关键点并在此基础上改造成头像上传、商品图批量预览等常见场景。对于希望从原生 JavaScript 入手理解上传流程的读者这份源码结构轻量适合逐行阅读和二次修改。1. 从一次选 30 张图卡死说起HTML5 多图预览源码到底能干什么一个后台上传页用户一次选了三十张商品图缩略图只出来一半页面还卡得无法滚动。排查后发现不是接口慢而是前端把原图直接塞进页面blob URL 用完也没释放。这份 HTML5 多图片上传预览源码解决的正是这类问题它把文件选择、类型与大小校验、缩略图渲染、删除重选、FormData 上传和进度反馈串成一条可运行链路适合做商品图、工单附件、资料提交的团队直接拿来做基线。它不依赖复杂框架核心是浏览器原生的 File API、URL.createObjectURL、FormData 和 XMLHttpRequest。新手能照着把页面跑起来熟手也能把预览、上传、删除拆成独立模块接进自己的业务页面。源码不大但上传组件最容易翻车的地方基本都覆盖到了下面按目录结构、核心渲染、上传交互和二次开发几个层面拆开讲。2. 技术选型与目录结构原生 HTML5 File API 的轻量组合2.1 为什么不用框架File API 与 URL.createObjectURL 的边界多图预览这件事浏览器原生能力已经够用。用户点选择文件后input typefile multiple会给出一个FileList里面的每个File本质上是带文件名的Blob。前端要做的第一件事不是上传而是把本地文件变成页面能显示的图像。常见做法有两条URL.createObjectURL(file)生成blob:地址或者FileReader.readAsDataURL(file)读成 base64 字符串。两条路都能显示图片但内存和释放方式差别很大。方式生成速度内存占用释放方式适合场景URL.createObjectURL快不读取文件内容较低只持有 Blob 引用手动URL.revokeObjectURL多图、大图预览FileReader.readAsDataURL需要完整读取文件较高base64 字符串比原文件大约多三分之一变量置空后等垃圾回收单图、需要把图片字符串存起来这份源码选择createObjectURL做预览原因是多图场景下它不会把每张图都转成一大段字符串。代价是每个生成的 URL 都要手动释放删除图片、重新渲染、离开页面时都得管。很多上传组件预览正常但越用越卡问题就出在这里只创建不释放页面里堆着一批已经没人用的 blob 地址。File API 还有几个边界要提前知道。浏览器不会把本地文件的真实路径交给 JavaScriptinput.value也不能反过来赋一个本地路径File对象是只读的要压缩或旋转得先读进canvas再导出新的 Blob拖拽上传拿到的文件在DataTransfer.files里和 input 选择出来的FileList不是同一个对象但结构相似可以统一转成数组处理。把这些边界认清后面写校验和渲染就不容易乱。如果页面已经在某个前端框架里这套逻辑也可以包成组件但核心 API 不变选择文件、校验、生成预览 URL、维护文件数组、组装 FormData。原生写法适合做轻量后台页也适合作为框架组件的底层实现参考。2.2 目录怎么摆一个入口页、一个样式、一个上传脚本源码的目录结构不复杂典型摆法是一个入口页、一个样式文件、几个按职责拆开的脚本。下面这棵树是这类项目最常见的组织方式二次开发时也方便定位问题multi-image-upload/ ├── index.html # 入口文件选择、拖拽区、预览列表、上传按钮 ├── css/ │ └── upload.css # 预览网格、删除按钮、拖拽高亮、进度条样式 ├── js/ │ ├── config.js # 上传地址、字段名、数量与大小限制 │ ├── preview.js # 文件校验、缩略图渲染、删除与重选 │ └── upload.js # FormData 组装、XHR 上传、进度与失败处理 └── README.md # 运行方式、接口字段约定、常见问题文件主要职责二次开发常改点index.html页面骨架放 input、拖拽区、预览容器改按钮文案、加业务说明、调整布局css/upload.css预览项尺寸、删除按钮位置、拖拽态改成表格布局、适配移动端js/config.js上传接口、字段名、最大数量、单文件大小换上传地址、改字段名、调限制js/preview.js文件过滤、生成预览、删除重选加压缩、加排序、换预览样式js/upload.js组装 FormData、发请求、更新进度加并发队列、加签名、改重试策略我一般会把config.js单独抽出来因为上传地址、后端接收字段名、最大数量这三项在不同项目里几乎必改。预览逻辑和网络逻辑分开排查时也清楚缩略图不出来就看preview.js接口报错就看upload.js不用在一大坨代码里来回翻。预览容器建议用div网格每个预览项里放img、文件名和删除按钮。文件名不要用innerHTML直接拼用户可以把文件名改成带尖括号的字符串拼进 HTML 会变成注入点。用textContent或 DOM API 创建节点更稳。2.3 运行方式本地静态服务与后端接口占位源码是静态页面启动不需要构建工具。进入目录后起一个本地静态服务即可cd multi-image-upload python3 -m http.server 8080 # 或者用 Node 环境下的静态服务命令 npx serve .然后在浏览器访问http://localhost:8080。不建议直接双击index.html用file://打开部分浏览器在本地文件协议下对 XHR、跨域和 File API 的限制不一样预览可能正常上传却失败排查起来很绕。本地静态服务更接近真实页面环境。上传地址在config.js里留成占位接自己的接口时先改这里// js/config.js window.UPLOAD_CONFIG { url: /api/upload, // 换成自己的上传接口 fieldName: images[], // 必须与后端接收字段一致 maxCount: 9, // 一次最多保留多少张 maxSize: 5 * 1024 * 1024, // 单文件大小上限单位字节 accept: image/* // 文件选择器的默认过滤 };url是上传接口地址前后端同域时写相对路径最省事fieldName要和后端约定一致很多“文件传上去了但后端收不到”的问题就是字段名对不上maxCount和maxSize是前端第一道限制后端仍然要再校验一次accept只影响系统文件选择器的默认过滤不能当成安全校验。跑通验证可以按这个顺序先选两三张图看缩略图是否正常点删除看列表和文件数组是否同步点上传在浏览器开发者工具的 Network 面板里看请求体是不是multipart/form-data字段名和文件数量对不对最后把maxCount改成 2再选 5 张看限制是否生效。接口失败时先看状态码413 多半是请求体超过网关限制400 多半是字段或参数不对500 才去查服务端日志。提示acceptimage/*只影响文件选择器的默认过滤用户仍可能通过“所有文件”或拖拽带进非图片文件JavaScript 里的类型校验不能省。3. 核心模块拆解从 input change 到缩略图渲染的完整链路3.1 文件选择与多选约束multiple、accept 与 FileList 转换页面上的文件选择入口通常是一个隐藏的input加一个可见按钮点击按钮触发 input 的点击事件。multiple决定能不能多选accept决定选择器默认显示哪些文件input idfileInput typefile nameimages[] acceptimage/* multiple hidden label forfileInput classupload-btn选择图片/label div iddropzone classdropzone也可以把图片拖到这里/div div idpreviewList classpreview-list/divmultiple加上后用户可以在文件选择器里按住 Ctrl 或 Shift 多选。acceptimage/*会让选择器默认过滤图片但它不是强制拦截拖拽和“所有文件”都可能带进别的类型。真正校验要在change事件里做。FileList是类数组对象不能直接调map、filter常见做法是先Array.from转成数组再做类型、大小、数量校验const input document.querySelector(#fileInput); const state { files: [], // 当前保留的 File 对象 urls: [] // 对应的 blob 预览地址后面统一释放 }; input.addEventListener(change, (event) { const picked Array.from(event.target.files || []); const valid []; for (const file of picked) { // 类型可能为空用扩展名兜底更稳 const isImage file.type.startsWith(image/) || /\.(jpe?g|png|gif|webp|bmp)$/i.test(file.name); if (!isImage) continue; if (file.size UPLOAD_CONFIG.maxSize) continue; valid.push(file); } // 追加而不是覆盖剩余名额按 maxCount 截断 const remain UPLOAD_CONFIG.maxCount - state.files.length; state.files.push(...valid.slice(0, Math.max(remain, 0))); renderPreview(); input.value ; // 允许第二次选择同一张图时再次触发 change });这段代码做了三件事把FileList转成数组过滤非图片和超大文件把合格文件追加进state.files。参数maxSize的单位是字节5MB 写成5 * 1024 * 1024maxCount控制总保留数量已经选了 6 张、上限 9 张时下次最多再收 3 张。input.value 是重复选择同一文件的关键浏览器会把 input 的值和上次比较值没变就不触发change。注意文件名、类型、大小都是客户端可以伪造的前端校验只负责体验和第一道过滤后端仍要检查 MIME、扩展名、文件头和存储大小。3.2 预览渲染createObjectURL 和 FileReader 怎么选预览渲染的核心是把state.files映射成页面节点。每次文件数组变化时重新渲染一遍但重新渲染前要先释放上一轮的 blob URL否则旧地址会一直占着内存function renderPreview() { const oldUrls state.urls; // 先保存旧地址 state.urls []; previewList.replaceChildren(); // 清空旧节点 oldUrls.forEach((url) URL.revokeObjectURL(url)); state.files.forEach((file, index) { const url URL.createObjectURL(file); state.urls.push(url); const item document.createElement(div); item.className preview-item; item.dataset.index String(index); const img document.createElement(img); img.src url; img.alt file.name; img.loading lazy; // 图片多时延迟加载 const name document.createElement(span); name.className file-name; name.textContent file.name; // 不用 innerHTML避免文件名注入 const btn document.createElement(button); btn.type button; btn.className remove-btn; btn.dataset.index String(index); btn.textContent 删除; item.append(img, name, btn); previewList.appendChild(item); }); }这段代码的顺序有讲究先保存旧 URL 数组清空容器再统一revokeObjectURL。如果先生成新 URL 再释放旧 URL容易把还在页面上的图片地址提前释放出现缩略图裂开。img.loading lazy在图片多时能减少一次性解码压力textContent写文件名比innerHTML安全>previewList.addEventListener(click, (event) { const btn event.target.closest(.remove-btn); if (!btn) return; const index Number(btn.dataset.index); if (!Number.isInteger(index) || index 0 || index state.files.length) return; state.files.splice(index, 1); renderPreview(); // 以 state.files 为准重新渲染索引自然更新 });这段逻辑的关键是“单一数据源”state.files是唯一事实页面只是它的投影。删除时只改数组然后整体重渲染不要手动去删某个 DOM 节点再自己维护下标。否则删掉第一张后第二张的>async function uploadAll() { if (!state.files.length) return; const formData new FormData(); state.files.forEach((file) { formData.append(UPLOAD_CONFIG.fieldName, file, file.name); }); formData.append(bizType, goods); // 业务字段按需添加 const xhr new XMLHttpRequest(); xhr.open(POST, UPLOAD_CONFIG.url, true); xhr.upload.onprogress (event) { if (event.lengthComputable) { const percent Math.round((event.loaded / event.total) * 100); updateProgress(percent); } }; xhr.onload () { if (xhr.status 200 xhr.status 300) { try { const result JSON.parse(xhr.responseText || {}); console.log(上传成功, result); } catch (error) { console.error(响应不是合法 JSON, xhr.responseText); } } else { console.error(上传失败, xhr.status, xhr.responseText); } }; xhr.onerror () console.error(网络错误或跨域失败); xhr.send(formData); }formData.append(fieldName, file, file.name)里的第三个参数决定后端收到的文件名不传时浏览器会用默认文件名某些后端拿到的名字会变成blob。bizType是示例业务字段实际项目里可能是订单号、资料类型、用户标识按接口文档加。xhr.upload.onprogress只监听上传阶段event.lengthComputable为true时loaded / total才有意义。注意用 FormData 上传时不要手动设置Content-Type浏览器需要自己生成带 boundary 的请求头手动写死反而会让后端解析失败。批量上传和逐张上传要按业务选。批量提交一次请求文件多进度是整体进度单文件失败不好定位逐张上传可以给每张图单独显示状态和重试但请求数多。常见折中是限制并发数比如同时最多传 3 张其余排队。4.2 拖拽上传dragenter/dragover/drop 的事件顺序拖拽区要让浏览器知道“这里可以放文件”关键是dragover里调用preventDefault否则drop不会触发const dropzone document.querySelector(#dropzone); [dragenter, dragover].forEach((type) { dropzone.addEventListener(type, (event) { event.preventDefault(); event.stopPropagation(); dropzone.classList.add(is-over); }); }); [dragleave, drop].forEach((type) { dropzone.addEventListener(type, (event) { event.preventDefault(); event.stopPropagation(); dropzone.classList.remove(is-over); }); }); dropzone.addEventListener(drop, (event) { const dropped Array.from(event.dataTransfer.files || []); const images dropped.filter((file) file.type.startsWith(image/)); addFiles(images); // 复用前面 change 里的校验和追加逻辑 });dragenter和dragover都要阻止默认行为只写drop是不够的。dragleave在鼠标经过子元素时会频繁触发导致高亮闪烁简单做法是给拖拽区套一层计数器进入加一、离开减一减到零再移除高亮。drop里从event.dataTransfer.files取文件拖文件夹时这个列表可能为空要提示用户拖具体图片文件。拖拽和 input 选择最后都走同一个addFiles校验入口避免两套逻辑规则不一致。移动端浏览器对桌面拖拽支持有限移动端还是以点击选择为主拖拽区可以隐藏或降级成提示文案。4.3 进度与失败重试xhr.upload.onprogress 的可用范围上传进度用 XHR 最稳fetch在不少浏览器里拿不到上传阶段进度。重试策略要区分错误类型网络中断、超时、5xx 可以重试4xx 通常重试也没用反而增加无效请求function uploadWithRetry(file, retry 2) { return new Promise((resolve, reject) { const attempt (left) { const xhr new XMLHttpRequest(); const formData new FormData(); formData.append(image, file, file.name); xhr.open(POST, UPLOAD_CONFIG.url, true); xhr.onload () { if (xhr.status 200 xhr.status 300) { resolve(xhr.responseText); } else if (xhr.status 500 left 0) { attempt(left - 1); } else { reject(new Error(HTTP ${xhr.status})); } }; xhr.onerror () { if (left 0) attempt(left - 1); else reject(new Error(network error)); }; xhr.send(formData); }; attempt(retry); }); }retry是额外重试次数传 2 表示首次失败后最多再试两次。xhr.status 500才重试401、403、413、422 这类状态码直接失败并提示用户。并发上传时不要把所有文件同时send浏览器对同域并发连接有限制太多请求会互相排队进度条也会跳。常见做法是维护一个长度 3 左右的队列每完成一个再取下一个。如果后端支持分片或断点续传重试可以只传失败分片普通图片上传没必要上分片先把单文件大小限制和压缩做好更实际。5. 避坑与排查图片预览正常但上传失败的 5 个现场5.1 现象缩略图裂开控制台没有明显报错现象是选图后预览区出现破图图标刷新或重新选择又偶尔正常。原因多半是 blob URL 被提前释放在重新渲染时先生成了新 URL又把旧 URL 全部revoke如果旧节点还没被替换掉正在显示的图片地址就失效了。另一种情况是删除图片后只移除了 DOM没有同步释放 URL下一次渲染复用了已经释放的地址。解决顺序要固定先保存旧 URL 数组清空预览容器再统一释放旧 URL最后生成新 URL。删除、重选、离开页面都走同一个清理函数。排查时在createObjectURL和revokeObjectURL两边打日志看某个 URL 是不是在图片还在页面上时就被释放了。5.2 现象第二次选择同一张图change 不触发现象是用户删掉一张图后又从本地选择同一张图预览没有增加。原因是 input 的 value 还停留在上一次的文件名浏览器认为值没变不再派发change。解决很简单在change处理完后执行input.value 把 input 重置为空下次选择同一文件也会触发。如果页面用了表单提交而不是 FormData重置 input 会影响原生表单字段这种情况可以每次点击选择按钮时动态创建新的 input或者用DataTransfer重新组装文件列表。多数上传组件用 FormData 提交直接清空 input 最省事。5.3 现象一次选 50 张后页面内存暴涨、滚动卡顿现象是图片数量一多页面滚动明显掉帧任务管理器里内存持续上涨。原因通常有三个blob URL 只创建不释放预览直接渲染原图几千像素的大图被塞进小缩略图用 FileReader 把每张图转成 base64字符串常驻内存。解决方向是限制数量、生成缩略图、及时释放。常见做法是在上传前用canvas把大图压到最长边 1600 像素左右再导出 Blob 参与预览和上传。压缩代码要注意图片方向部分手机拍的照片带 EXIF 旋转信息直接画到 canvas 可能方向不对。前端不处理的话后端转码时统一纠正也可以。5.4 现象接口返回 413或者后端说收不到文件413 是请求体超过限制先查反向代理、网关和应用服务器的上传大小配置再看前端有没有把多张原图一次性塞进同一个请求。字段收不到则常见于三种情况前端append的字段名和后端接收名不一致手动设置了Content-Type导致 boundary 丢失append文件时没传文件名后端按普通字段解析。排查时打开 Network 面板看请求头是不是multipart/form-data; boundary...再看请求体里每个 part 的name和filename。字段名带[]的写法要和后端约定一致有些框架按同名多值接收有些按数组接收。不要靠猜直接拿浏览器发出的请求和后端接口文档对。5.5 现象移动端拍照方向不对或者某些格式选不了、传不了现象是手机拍的照片在预览里横着或者用户选了一些特殊格式的图片前端预览失败、后端也不识别。原因是照片文件里带方向标记浏览器渲染时不一定按标记旋转部分图片格式在浏览器里的解码支持不一致accept过滤只是选择器行为。解决方向分两层前端展示时按方向信息旋转或者上传前用 canvas 重绘一遍后端统一转成常见格式并纠正方向。对于浏览器不支持的格式前端可以在选择后检测解码是否成功失败时提示用户换图不要等上传完才报错。限制accept只能减少误选不能代替解码检测。6. 二次开发把预览组件接到真实业务里的 4 个改造点拿到源码后先别急着加功能把四个地方改对就能接进大多数业务改造点改哪里验证方式上传地址与字段名js/config.js的url、fieldNameNetwork 里看请求体和后端接收参数数量与大小限制maxCount、maxSize选超限文件看是否被拦截并提示上传前压缩preview.js或独立的compress.js对比压缩前后file.size和清晰度并发队列upload.js的uploadAll一次选 9 张看同时请求数是否受控压缩这块我一般放在生成预览之前先读文件到Image按最长边缩放画到 canvas再canvas.toBlob导出新文件把新 Blob 塞回state.files。这样预览和上传用的都是压缩后的文件内存压力小接口也不容易 413。压缩质量别一上来就压到 0.5商品图、证件照对清晰度要求不同按业务调。验证顺序也有讲究。我后来养成一个习惯上传组件先断网测一次失败提示再限速测一次进度条最后拿一张 20MB 的大图压一遍才提测。断网能暴露重试和错误提示的问题限速能看出进度是不是真的在动大图能试出内存和接口限制。这套源码不大但预览、删除、上传三段拆得比较清楚拿到后先改config.js和字段名再按业务加压缩和队列基本就能落地。希望帮到你。本文还有配套的精品资源点击获取