uni-app实现Android大文件分片上传的实践方案

1. 问题背景与核心挑战在开发基于uni-app的Android应用时文件上传是一个常见需求。当需要处理大文件上传时分片上传Chunked Upload成为必备技术方案。然而在Android 10API 29及更高版本系统中随着存储访问权限的收紧传统的文件路径处理方式会遇到严重兼容性问题。核心问题具体表现为当应用的targetSdkVersion设置为29或更高时尝试直接访问通过uni.chooseImage等API获取的临时文件路径如/storage/emulated/0/...会失败。这是因为Android 10引入了Scoped Storage分区存储机制限制应用直接访问外部存储路径。提示从Android 10开始应用只能通过Storage Access Framework或MediaStore API访问共享存储空间中的特定类型文件否则必须将文件复制到应用私有目录App-specific directory才能进行操作。2. 整体解决方案设计2.1 技术选型与架构我们的解决方案基于以下技术栈uni-app跨平台开发框架使用Vue.js语法HTML5 Runtimeuni-app底层依赖的原生能力扩展Java FileChannelAndroid平台的高效文件操作类整体流程分为四个关键阶段获取安全的文件路径私有目录计算分片参数大小、数量等使用FileChannel导出分片临时文件通过uni.uploadFile上传分片并清理临时文件2.2 与传统方案的对比传统方案通常尝试直接使用FileReader.readAsArrayBuffer读取文件内容并切片但在Android平台上存在明显缺陷方案优点缺点Base64ArrayBuffer纯前端实现不依赖原生API内存占用高大文件易OOMFileWriter.write()简单直接存在数据膨胀问题iOS兼容性差FileChannel方案内存高效性能稳定需要原生API支持实现较复杂3. 核心实现细节3.1 安全路径处理首先需要将用户选择的文件复制到应用私有目录。关键代码如下const ensurePrivateDocPath (rawPath, extname ) { return new Promise((resolve, reject) { if (!rawPath) return reject(new Error(文件路径为空)); const withPrefix rawPath.startsWith(file://) ? rawPath : file://${rawPath}; // 已在私有目录则直接返回 if (/_doc\//.test(withPrefix)) { return resolve(withPrefix); } plus.io.resolveLocalFileSystemURL(withPrefix, (entry) { plus.io.requestFileSystem(plus.io.PRIVATE_DOC, (fs) { const newName upload_${Date.now()}${extname ? . extname.replace(/^\./, ) : }; entry.copyTo(fs.root, newName, (newEntry) { const url typeof newEntry.toLocalURL function ? newEntry.toLocalURL() : newEntry.fullPath; resolve(url.startsWith(file://) ? url : file://${url}); }, reject); }, reject); }, reject); }); };注意事项Android 10设备上必须确保所有文件操作都在应用私有目录_doc/内进行。plus.io.PRIVATE_DOC对应的是应用专属存储空间不受Scoped Storage限制。3.2 分片参数计算分片上传需要精确计算每个分片的起始位置和大小const chunkSize 5 * 1024 * 1024; // 5MB const chunks Math.ceil(fileSize / chunkSize); for (let i 0; i chunks; i) { const start i * chunkSize; const endInclusive Math.min(((i 1) * chunkSize) - 1, fileSize - 1); const realChunkSize Math.max(0, (endInclusive - start 1)); // 构造分片参数 const payload { chunk: i, chunks, chunkSize, realChunkSize, // ...其他元数据 }; }参数说明chunkSize固定分片大小如5MB用于后端校验realChunkSize实际分片大小最后一片可能小于chunkSizestart/endInclusive分片在文件中的字节范围包含结束位置3.3 FileChannel分片导出核心的分片导出使用Android的FileChannel类相比传统IO流具有更好性能export const exportAndroidChunkFile ( originPath, start, length, tempFileName ) { return new Promise((resolve, reject) { // 导入Java类 const File plus.android.importClass(java.io.File); const FileInputStream plus.android.importClass(java.io.FileInputStream); const FileOutputStream plus.android.importClass(java.io.FileOutputStream); const FileChannel plus.android.importClass(java.nio.channels.FileChannel); const ByteBuffer plus.android.importClass(java.nio.ByteBuffer); // 创建输入输出流 const originFile new File(absOrigin); const fis new FileInputStream(originFile); const inChannel fis.getChannel(); inChannel.position(actualStart); const targetFile new File(absTargetPath); const fos new FileOutputStream(targetFile, false); const outChannel fos.getChannel(); // 使用直接内存缓冲区 const buffer ByteBuffer.allocateDirect(64 * 1024); // 64KB缓冲区 let remaining finalLength; while (remaining 0) { buffer.clear(); const limit Math.min(remaining, buffer.capacity()); buffer.limit(limit); const read inChannel.read(buffer); if (read 0) break; buffer.flip(); const written outChannel.write(buffer); remaining - written; } outChannel.force(true); // 强制刷盘 // ...关闭资源 resolve(normalizeUploadFilePath(absTargetPath)); }); };关键优化点直接内存缓冲区通过ByteBuffer.allocateDirect()分配堆外内存减少GC压力固定大小缓冲区64KB平衡了内存占用和IO效率强制刷盘force(true)确保数据写入物理存储精确位置控制position()和limit()实现准确的分片范围4. 完整上传流程实现4.1 主流程代码整合各环节的完整上传示例async function uploadFile(file) { // 1. 获取安全路径 const safePath await ensurePrivateDocPath(file.tempFilePath); // 2. 准备上传参数 const fileSize file.size; const chunkSize 5 * 1024 * 1024; const chunks Math.ceil(fileSize / chunkSize); // 3. 分片上传 for (let i 0; i chunks; i) { const start i * chunkSize; const end Math.min((i 1) * chunkSize, fileSize) - 1; const realChunkSize end - start 1; // 4. 导出分片临时文件 const tempName chunk_${i}_${Date.now()}; const tempPath await exportAndroidChunkFile( safePath, start, realChunkSize, tempName ); // 5. 上传分片 const uploadRes await uni.uploadFile({ url: https://api.example.com/upload, filePath: tempPath, name: file, formData: { chunk: i, chunks, chunkSize, realChunkSize, fileName: file.name } }); // 6. 清理临时文件 try { plus.io.resolveLocalFileSystemURL(tempPath, (entry) { entry.remove(() {}, (e) {}); }); } catch (e) {} } }4.2 进度反馈实现良好的用户体验需要实时上传进度反馈// 在for循环内添加 const progress Math.round(((i 1) / chunks) * 100); uni.showLoading({ title: 上传中 ${progress}%, mask: true }); // 可选的更精细进度基于实际字节传输 let transferred 0; const progressInterval setInterval(() { const chunkProgress Math.round((transferred / realChunkSize) * 100); const totalProgress Math.round( (i * chunkSize transferred) / fileSize * 100 ); console.log(分片${i}进度: ${chunkProgress}%总进度: ${totalProgress}%); }, 500); // 在buffer写入循环中更新 transferred written; // 上传完成后 clearInterval(progressInterval);5. 关键问题与解决方案5.1 Android高版本兼容性问题问题现象targetSdkVersion≥29时直接访问外部存储路径失败错误信息包含Permission denied或Exposed beyond app through Intent.getData()解决方案将所有文件操作限制在应用私有目录_doc/使用plus.io.convertLocalFileSystemURL()处理路径转换对于用户选择的文件立即复制到私有目录5.2 内存溢出(OOM)问题问题现象使用readAsArrayBuffer时大文件分片导致内存不足日志中出现Java heap space或OutOfMemoryError解决方案使用FileChannel替代内存缓冲分片大小建议值普通设备2-5MB低内存设备512KB-1MB避免在JavaScript层处理二进制数据5.3 分片大小不一致问题问题现象后端校验失败报告分片大小不符最后一片大小计算错误解决方案// 正确的分片结束位置计算 const endInclusive Math.min( ((i 1) * chunkSize) - 1, // 理论结束位置 fileSize - 1 // 文件实际结束位置 ); const realChunkSize endInclusive - start 1; // 包含结束位置5.4 临时文件清理最佳实践每个分片上传后立即清理添加上传失败的重试机制应用启动时清理残留临时文件// 启动时清理旧临时文件 plus.io.requestFileSystem(plus.io.PRIVATE_DOC, (fs) { fs.root.getDirectory(temp_uploads, {}, (dir) { const reader dir.createReader(); reader.readEntries((entries) { entries.forEach(entry { if (entry.name.startsWith(a_chunk_)) { entry.remove(() {}, (e) {}); } }); }); }); });6. 性能优化建议6.1 上传并发控制虽然分片可以并行上传但需要平衡速度和设备性能// 示例最大3个并发上传 const MAX_CONCURRENT 3; let currentConcurrent 0; const queue []; async function processQueue() { while (queue.length 0 currentConcurrent MAX_CONCURRENT) { currentConcurrent; const task queue.shift(); try { await task(); } catch (e) { console.error(上传失败:, e); } finally { currentConcurrent--; processQueue(); } } } // 将分片上传任务加入队列 for (let i 0; i chunks; i) { queue.push(() uploadChunk(i)); processQueue(); }6.2 断点续传实现通过本地存储记录上传状态// 获取已上传分片信息 const uploadedChunks uni.getStorageSync(file.name) || []; async function uploadChunk(index) { if (uploadedChunks.includes(index)) return; // ...上传逻辑 // 上传成功后记录 uploadedChunks.push(index); uni.setStorageSync(file.name, uploadedChunks); } // 全部完成后清理记录 uni.removeStorageSync(file.name);6.3 网络状态适配根据网络类型动态调整分片大小function getDynamicChunkSize() { const networkType uni.getNetworkType(); switch(networkType) { case wifi: return 5 * 1024 * 1024; // 5MB case 4g: return 1 * 1024 * 1024; // 1MB default: return 512 * 1024; // 512KB } }7. 完整工具类封装建议将核心功能封装为可复用的工具类// androidUploader.js export default { /** * 初始化上传器 * param {Object} options * param {Number} options.maxConcurrent 最大并发数 * param {Function} options.onProgress 进度回调 */ init(options) { this.options options; this.queue []; this.activeCount 0; }, /** * 添加上传任务 * param {File} file 文件对象 * param {String} uploadUrl 上传接口 */ async addTask(file, uploadUrl) { const task { file, uploadUrl, chunks: [], uploaded: [] }; // 获取安全路径 task.safePath await this._ensurePrivatePath(file); task.fileSize file.size; task.chunkSize this._getOptimalChunkSize(); task.totalChunks Math.ceil(task.fileSize / task.chunkSize); // 创建分片任务 for (let i 0; i task.totalChunks; i) { task.chunks.push({ index: i, start: i * task.chunkSize, end: Math.min((i 1) * task.chunkSize, task.fileSize) - 1 }); } this.queue.push(task); this._processQueue(); }, // ...其他内部方法 };使用示例import AndroidUploader from ./androidUploader; const uploader AndroidUploader.init({ maxConcurrent: 3, onProgress: (progress) { console.log(上传进度:, progress); } }); uni.chooseImage({ success: (res) { uploader.addTask(res.tempFiles[0], https://api.example.com/upload); } });8. 实际应用中的经验总结经过多个项目的实践验证以下是关键经验点路径处理黄金法则所有文件操作前先调用normalizeUploadFilePath()永远不要假设路径是否包含file://前缀Android 10必须使用_doc/私有目录分片大小选择WiFi环境3-5MB4G网络1-2MB弱网环境256-512KB测试表明过小的分片100KB反而降低整体吞吐量内存管理要点避免在JavaScript层保留大文件引用每个分片处理完成后手动置空相关变量使用ByteBuffer.allocateDirect()而非普通缓冲区调试技巧// 在关键节点添加详细日志 console.log(分片${index}参数, { originPath: originPath.replace(/file:\/\//, ), start, length, tempFileName });使用Android Studio的Logcat查看原生层日志重点关注FileChannel的position()和limit()值兼容性检查清单[x] targetSdkVersion≥29的设备[x] Android 10的存储权限处理[x] 各种文件扩展名测试含无扩展名文件[x] 超大文件测试1GB[x] 网络切换测试WiFi/4G切换9. 扩展思考iOS适配方案虽然本文聚焦Android实现但iOS平台也有其特殊性关键差异点iOS没有Scoped Storage限制但需要注意FileWriter.write(string)会导致数据膨胀推荐使用NSData或NSFileHandle进行文件操作统一接口设计function exportChunkFile(platform, originPath, start, length, tempName) { if (platform android) { return exportAndroidChunkFile(originPath, start, length, tempName); } else { return exportIosChunkFile(originPath, start, length, tempName); } }iOS实现要点使用NSFileHandle的seekToFileOffset和readDataOfLength避免将整个分片读入内存注意NSData到ArrayBuffer的转换效率10. 总结与资源推荐通过本文介绍的技术方案我们成功解决了uni-app在Android高版本系统上的分片上传难题。核心创新点包括安全的私有目录文件操作流程基于FileChannel的高效分片导出全面的异常处理和资源管理进一步学习资源Android文件存储最佳实践Java NIO FileChannel文档uni-app原生插件开发指南在实际项目中建议将上传模块封装为独立的服务类便于各页面复用。同时结合后台实现秒传、断点续传等高级特性可以进一步提升用户体验。