在uni-app中实现文件上传需使用uni.uploadfile并结合任务管理。首先，通过uni.uploadfile方法完成基础上传操作，传入文件路径、服务器地址和请求参数；其次，利用uni.createuploadtask监听上传进度以提升用户体验；第三，多文件上传时应控制并发数量，采用队列方式限制同时上传的文件数；最后，加入错误处理与重试机制，在fail回调中记录失败次数并支持自动延时重试，确保上传稳定性。
文件上传功能在uni-app开发中非常常见，尤其在涉及用户头像、图片、文档等场景时。实现上传不光是调用接口那么简单，还需要考虑进度监控、错误处理、多文件支持等问题。下面从几个关键点出发，讲讲如何实际操作。
1. 使用 uni.uploadFile 实现基础上传
uni-app 提供了 uni.uploadFile 方法用于上传文件，这是最常用的方式。使用时需要传入文件路径、服务器地址以及请求参数。
uni.chooseImage({
success: (res) => {
const tempFilePath = res.tempFilePaths[0];
uni.uploadFile({
url: 'https://yourdomain.com/upload',
filePath: tempFilePath,
name: 'file',
formData: {
user: 'test'
},
success: (uploadRes) => {
console.log('上传成功', uploadRes);
},
fail: (err) => {
console.error('上传失败', err);
}
});
}
});- url：上传的目标地址
- filePath：要上传的文件路径
- name：后端接收字段名（通常为 file）
- formData：额外参数（可选）
注意：uni.uploadFile 返回的是一个任务对象，可以用来监听上传进度。
2. 监控上传进度的方法
虽然 uni.uploadFile 支持上传，但它本身并没有提供进度回调。不过 uni-app 提供了一个配套方法 uni.createUploadTask，可以创建上传任务并监听进度。
const uploadTask = uni.uploadFile({
url: 'https://yourdomain.com/upload',
filePath: tempFilePath,
name: 'file'
});
uploadTask.onProgressUpdate(res => {
console.log('上传进度:', res.progress + '%');
console.log('已上传字节数:', res.totalBytesSent);
console.log('总字节数:', res.totalBytesExpectedToSend);
});这个回调会定期触发，可以在页面上展示一个进度条或百分比提示，提升用户体验。
注意：不是所有平台都支持精确的进度更新，比如部分小程序可能只能获取到开始和结束状态。
3. 多文件上传与并发控制
如果需要同时上传多个文件，可以循环调用 uni.uploadFile，但要注意控制并发数量，避免资源占用过高或被服务器限制。
一种简单的做法是：
- 将文件列表放入队列
- 每次只发起固定数量的上传请求（如 3 个）
- 每个任务完成后继续取下一个
示例逻辑如下：
let currentIndex = 0;
const maxConcurrent = 3;
function uploadNext(files) {
if (currentIndex >= files.length) return;
for (let i = 0; i < maxConcurrent && currentIndex < files.length; i++) {
const filePath = files[currentIndex++];
const task = uni.uploadFile({
url: 'https://yourdomain.com/upload',
filePath: filePath,
name: 'file',
success: () => {
console.log(`${filePath} 上传完成`);
}
});
task.onProgressUpdate(res => {
console.log(`文件 ${filePath} 的上传进度：${res.progress}%`);
});
}
}这种方式可以有效管理并发，避免一次性上传太多文件导致卡顿或失败。
4. 错误处理与重试机制
上传过程中可能会遇到网络问题、服务器错误等情况。为了提高稳定性，建议加入错误处理和自动重试逻辑。
- 在
fail回调中记录失败次数 - 超过一定次数后提示用户检查网络或手动重试
- 可以配合定时器做延时重试
例如：
- 如果上传失败：
- 增加重试计数
- 判断是否超过最大重试次数
- 否则延迟一段时间后重新上传
这样能提升整体成功率，减少用户重复操作。
基本上就这些。只要掌握好 uni.uploadFile 和进度监听机制，再结合并发控制和错误处理，就能在 uni-app 中稳定地实现文件上传功能。
