跳到主要内容前端文件上传核心原理与实战详解 | 极客日志JavaScript大前端
前端文件上传核心原理与实战详解
前端文件上传全流程。涵盖 HTML input 标签基础、File 对象属性、多文件及文件夹选择、文件类型大小校验、图片视频本地预览(URL.createObjectURL)、FormData 封装与 AJAX 请求(XHR/Axios)、以及大文件分片上传方案。包含原生实现与主流框架用法,解决跨域、进度监控等常见问题,适合前端开发者掌握核心知识点。
FlinkHero31 浏览 前言
文件上传是前端开发中高频且核心的业务能力,几乎所有中后台系统、用户中台、内容平台都离不开该功能,如头像上传、Excel 导入、附件提交、视频/图片发布等。前端文件上传并非简单的表单提交,而是涉及 HTML 基础语法、JavaScript 核心 API、浏览器兼容性、大文件分片、断点续传、进度监控、文件校验、跨域处理、文件预览等多维度的综合知识点。
本文将从基础原理到高级实战,从原生实现到主流方案,详细讲解前端文件上传的核心知识点。
一、文件上传的核心前置知识:HTML 核心上传标签
前端文件上传的根基是 HTML 提供的两个核心标签/属性,所有上传逻辑都基于它们实现,重中之重,必须先掌握:
1. 核心标签:
这是前端文件上传的唯一入口,专门用于让用户选择本地文件,是实现文件上传的核心标签,无它不可。
2. 核心属性:files
当用户通过 选择文件后,这个 DOM 元素会自动生成一个只读属性 files,它的本质是:一个【FileList 文件列表对象】。
- FileList 是一个类数组对象,里面每一个成员都是一个 File 对象
- 每一个 File 对象,就代表用户选择的一个本地文件,包含了文件的所有信息(名称、大小、类型、最后修改时间等)
3. File 对象 核心属性(开发高频必用)
每一个选中的文件,都是一个 File 实例,自带以下只读属性,可直接获取,无兼容性问题:
file.name;
file.size;
file.type;
file.lastModified;
二、核心属性:multiple 实现「多文件上传」、webkitdirectory 开启文件夹选择(H5 新特性)
multiple:
默认只能选择一个文件,想要实现「按住 Ctrl/Shift 选择多个文件」的多文件上传,只需要加一个属性即可:
<input type="file">
<input type="file" multiple>
关键特性:
- 加了 multiple 后,input.files 里会包含所有选中的文件,长度 input.files.length 就是选中的文件数量
- 不加 multiple,input.files.length 永远是 1(选中一个文件时)
webkitdirectory:
作用:支持用户直接选择整个文件夹,浏览器会自动解析文件夹内的所有文件(包含子文件夹的文件),适配「批量上传大量文件」的业务场景,兼容 Chrome、Edge、Safari 等现代浏览器:
<input type="file" webkitdirectory />
三、文件上传的核心 JS 逻辑:监听文件选择事件 change
1. 核心逻辑
2. 基础示例:获取选中的文件信息(单文件)
<input type="file">
<script>
const fileInput = document.querySelector('#fileInput');
fileInput.addEventListener('change', function() {
if (this.files.length === 0) {
console.log('未选择任何文件');
return;
}
const file = this.files[0];
console.log('文件名:', file.name);
console.log('文件大小:', file.size, '字节');
console.log('文件类型:', file.type);
console.log('最后修改时间:', new Date(file.lastModified));
})
</script>
3. 多文件选择:获取所有选中的文件
<input type="file" multiple>
<script>
const fileInput = document.querySelector('#fileInput');
fileInput.addEventListener('change', function() {
const fileList = this.files;
console.log('选中的文件总数:', fileList.length);
for(let i = 0; i < fileList.length; i++) {
const file = fileList[i];
console.log(`第${i+1}个文件:`, file.name, file.size);
}
})
</script>
四、开发高频需求:文件类型 / 大小 限制
实际开发中,一定会限制文件的类型和大小(比如:只能传图片、图片不能超过 2MB;只能传 PDF,不能超过 10MB),这个功能是前端文件上传的标配,核心实现逻辑就是:通过 File 对象的属性做判断,不符合则提示用户并阻止后续操作。
案例 1:限制「只能上传图片文件」+「文件大小≤2MB」
<input type="file" accept="image/*">
<script>
const fileInput = document.querySelector('#fileInput');
fileInput.addEventListener('change', function() {
if (!this.files.length) return;
const file = this.files[0];
const maxSize = 2 * 1024 * 1024;
if (!file.type.startsWith('image/')) {
alert('⚠️ 只能上传图片格式的文件!');
this.value = '';
return;
}
if (file.size > maxSize) {
alert('⚠️ 文件大小不能超过 2MB!');
this.value = '';
return;
}
console.log('文件验证通过,可上传:', file.name);
})
</script>
锦上添花:accept 属性(前端筛选,提升体验)
- 只显示图片:
accept="image/*"
- 只显示 PDF:
accept=".pdf"
- 只显示 Word/Excel:
accept=".doc,.docx,.xls,.xlsx"
- 只显示视频:
accept="video/*"
❗ 注意:accept 只是前端筛选,用户可以手动选择「所有文件」,所以必须配合 JS 的 File.type 判断,双重验证才安全!
案例 2:多文件上传 - 批量验证
<input type="file" multiple accept="image/*">
<script>
const fileInput = document.querySelector('#fileInput');
fileInput.addEventListener('change', function() {
const fileList = this.files;
if (!fileList.length) return;
const maxSize = 2 * 1024 * 1024;
let isValid = true;
for(let file of fileList) {
if (!file.type.startsWith('image/')) {
alert(`⚠️ 文件【${file.name}】不是图片格式!`);
isValid = false;
break;
}
if (file.size > maxSize) {
alert(`⚠️ 文件【${file.name}】大小超过 2MB!`);
isValid = false;
break;
}
}
if (isValid) {
console.log('所有文件验证通过,可批量上传');
} else {
this.value = '';
}
})
</script>
五、开发高频需求:文件预览(图片 / 视频)
用户选择文件后,在「点击上传」之前,预览选中的文件(比如:图片预览、视频预览)是非常常见的需求,能极大提升用户体验。前端实现文件预览的核心是:URL.createObjectURL(file) 这个 API,也是浏览器原生提供的 BOM 方法。
1. 核心 API 说明:URL.createObjectURL(file)
- 作用:接收一个 File 文件对象,返回一个临时的、唯一的 blob 本地预览地址
- 特点:这个地址只在当前页面有效,页面刷新 / 关闭后自动失效,不会占用服务器资源
- 配套:用完之后可以调用 URL.revokeObjectURL(url) 释放内存(非必须,但推荐)
2. 案例 1:图片文件预览(最常用)
<input type="file" accept="image/*">
<div>
<img id="previewImg" alt="图片预览">
</div>
<script>
const fileInput = document.querySelector('#fileInput');
const previewImg = document.querySelector('#previewImg');
let oldUrl = '';
fileInput.addEventListener('change', function() {
if (!this.files.length) {
previewImg.style.display = 'none';
return;
}
const file = this.files[0];
if (!file.type.startsWith('image/')) {
alert('只能上传图片!');
return;
}
if (oldUrl) {
URL.revokeObjectURL(oldUrl);
}
const previewUrl = URL.createObjectURL(file);
oldUrl = previewUrl;
previewImg.src = previewUrl;
previewImg.style.display = 'block';
})
</script>
3. 案例 2:视频文件预览
和图片预览逻辑完全一致,只是把
换成
<input type="file" accept="video/*">
<div>
<video id="previewVideo" controls></video>
</div>
<script>
const fileInput = document.querySelector('#fileInput');
const previewVideo = document.querySelector('#previewVideo');
let oldUrl = '';
fileInput.addEventListener('change', function() {
if (!this.files.length) return;
const file = this.files[0];
if(oldUrl) URL.revokeObjectURL(oldUrl);
const previewUrl = URL.createObjectURL(file);
previewVideo.src = previewUrl;
previewVideo.style.display = 'block';
})
</script>
六、文件上传的核心:通过 AJAX 把文件传给后端(重中之重)
前面所有的操作都是「前端本地操作」,真正的文件上传是把本地文件通过网络发送到后端服务器,这个过程必须通过 AJAX 请求实现(原生 XHR /axios 都可以)。
1. 核心注意点:文件上传的请求格式
文件属于二进制数据,不能用普通的 JSON 格式传参!前端上传文件时,必须把请求体的格式设置为:multipart/form-data,这是 HTTP 协议规定的「文件上传专用格式」。
2. 关键对象:FormData
浏览器原生提供的 FormData 对象,是实现文件上传的「核心载体」,它的作用是:
- 可以像「表单」一样,存放普通键值对参数 + 二进制文件对象
- 自动将请求的 Content-Type 设置为 multipart/form-data,无需手动设置
- 兼容所有浏览器,无兼容性问题
FormData 核心方法
const fd = new FormData();
fd.append('key', value);
fd.append('username', '张三');
fd.append('avatar', file);
七、两种主流上传实现方案
方案一:原生 XMLHttpRequest (XHR) 上传文件(无依赖,推荐原生)
无任何第三方库,纯原生 JS 实现,兼容性最好,面试 / 开发都常用,必学!
<input type="file" accept="image/*">
<button>点击上传</button>
<script>
const fileInput = document.querySelector('#fileInput');
const uploadBtn = document.querySelector('#uploadBtn');
let file = null;
fileInput.addEventListener('change', function() {
if (this.files.length) {
file = this.files[0];
uploadBtn.disabled = false;
} else {
file = null;
uploadBtn.disabled = true;
}
})
uploadBtn.addEventListener('click', function() {
if (!file) return;
const fd = new FormData();
fd.append('avatar', file);
fd.append('userId', 1001);
const xhr = new XMLHttpRequest();
xhr.open('POST', 'http://localhost:3000/api/upload', true);
xhr.upload.onprogress = function(e) {
if (e.lengthComputable) {
const percent = (e.loaded / e.total) * 100;
console.log(`上传进度:${percent.toFixed(2)}%`);
}
}
xhr.onload = function() {
if (xhr.status >= 200 && xhr.status < 300) {
const res = JSON.parse(xhr.responseText);
console.log('上传成功!', res);
alert('文件上传成功~');
} else {
console.error('上传失败!');
alert('文件上传失败,请重试~');
}
}
xhr.send(fd);
})
</script>
方案二:axios 上传文件(Vue/React 项目主流,推荐)
在 Vue/React 等工程化项目中,我们都用 axios 发送请求,axios 上传文件的逻辑更简洁,底层还是基于 XHR,核心依然是 FormData,开发中 90% 用这个!
前提:已引入 axios 库(CDN /npm 安装均可)
<input type="file" accept="image/*">
<button>axios 上传</button>
<script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
<script>
const fileInput = document.querySelector('#fileInput');
const uploadBtn = document.querySelector('#uploadBtn');
let file = null;
fileInput.addEventListener('change', () => file = fileInput.files[0]);
uploadBtn.addEventListener('click', async () => {
if (!file) return;
const fd = new FormData();
fd.append('avatar', file);
fd.append('userId', 1001);
try {
const res = await axios.post('http://localhost:3000/api/upload', fd, {
onUploadProgress: (e) => {
const percent = (e.loaded / e.total) * 100;
console.log(`axios 上传进度:${percent.toFixed(2)}%`);
}
});
console.log('上传成功', res.data);
alert('上传成功');
} catch (err) {
console.error('上传失败', err);
alert('上传失败');
}
})
</script>
八、文件上传的高阶功能:大文件分片上传
1. 什么是大文件分片上传?
当上传几百 MB / 几 GB 的大文件(比如:视频、压缩包)时,直接上传会有很多问题:
- 上传速度慢,容易超时失败
- 断网后需要重新上传整个文件,体验极差
- 后端服务器可能限制「单次请求的文件大小」,直接拒绝大文件
分片上传的核心思想:把一个 大文件切割成多个小文件(切片),比如:把 1GB 的视频切成 100 个 10MB 的切片,然后并发 / 串行上传所有切片,后端接收完所有切片后,再合并成一个完整的文件。
2. 核心 API:File.slice(start, end)
实现分片的核心是 File 对象的 slice 方法,它的作用是:对文件进行切割,返回一个新的 Blob 对象(和 File 对象兼容)
- 参数 1 start:开始切割的字节位置(如:0)
- 参数 2 end:结束切割的字节位置(如:1010241024 → 10MB)
- 特点:原文件不会被修改,只是生成一个切片副本
3. 分片上传核心流程(极简版核心代码)
const fileInput = document.querySelector('#fileInput');
fileInput.addEventListener('change', async () => {
const file = fileInput.files[0];
if (!file) return;
const chunkSize = 10 * 1024 * 1024;
const totalChunks = Math.ceil(file.size / chunkSize);
const fileId = Date.now() + '-' + file.name;
console.log(`文件大小:${file.size},切片数:${totalChunks}`);
for (let i = 0; i < totalChunks; i++) {
const start = i * chunkSize;
const end = Math.min(start + chunkSize, file.size);
const chunk = file.slice(start, end);
const fd = new FormData();
fd.append('chunk', chunk);
fd.append('fileId', fileId);
fd.append('chunkIndex', i);
fd.append('totalChunks', totalChunks);
fd.append('fileName', file.name);
await axios.post('http://localhost:3000/api/upload-chunk', fd);
console.log(`第${i+1}片上传完成`);
}
await axios.post('http://localhost:3000/api/merge-chunk', { fileId, fileName: file.name, totalChunks });
console.log('大文件上传成功!');
})
分片上传的进阶优化:断点续传(记录已上传的切片,下次只传未上传的),核心是「后端返回已上传的切片索引」,前端跳过即可,逻辑基于分片上传拓展,这里不展开。
九、文件上传的常见问题 & 解决方案
1. 问题:选择文件后,再次选择同一个文件,change 事件不触发?
fileInput.addEventListener('change', function() {
this.value = '';
})
2. 问题:后端接收不到文件,或者提示文件为空?
排查清单(按优先级):
① 前端是否用了 FormData 封装文件?(必须用)
② FormData.append('字段名', file) 的「字段名」是否和后端约定的一致?(比如后端要 file,前端传了 avatar)
③ 是否手动设置了 Content-Type: multipart/form-data?(不要手动设置!FormData 会自动处理,手动设置会导致边界符丢失)
3. 问题:上传文件时,浏览器报 CORS 跨域错误?
原因:前端域名和后端接口域名不一致,浏览器的同源策略限制
✅ 解决方案:后端在接口中配置跨域允许(前端无法解决,必须后端配合),比如:
- 设置响应头:Access-Control-Allow-Origin: *
- 允许跨域的请求头、请求方法
4. 问题:文件大小超过后端限制,上传失败?
解决方案:
① 前端提前做文件大小校验,超过则提示用户,不上传
② 后端修改配置,增大文件上传的大小限制(比如:nginx 的 client_max_body_size、node 的 body-parser 等)
③ 大文件直接用「分片上传」方案
十、文件上传核心知识点总结
以上就是前端文件上传的所有核心内容,从基础到进阶,从原理到实战,覆盖了开发中所有的常见场景,掌握这些内容,你就能应对所有的前端文件上传需求啦!
相关免费在线工具
- Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
- Escape 与 Native 编解码
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
- JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
- JavaScript 压缩与混淆
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online