1. 移动端大文件上传的痛点与分片方案选型做过移动端视频类应用的朋友大概率都遇到过这个场景用户选了一段几分钟甚至十几分钟的视频点击上传然后进度条卡在某个位置不动了或者干脆报个网络超时用户骂骂咧咧地退出重试流量白烧体验稀碎。这个问题的根源不在于网络本身有多差而在于单次HTTP请求上传大文件本身就是一件极其脆弱的事情——任何一个环节抖动整个请求就废了。Flutter在跨平台开发里算是目前比较顺手的选择但它的生态里关于视频选择和分片上传的完整方案其实并不算多。很多教程只讲到怎么调起相册选个视频或者只讲怎么发一个multipart请求把“选”和“传”串起来、并且真正处理了分片逻辑的内容比较少。我这次就把自己在实际项目里跑通的一套方案完整拆一遍从选视频、读文件、切片、并发控制、断点续传到服务端合并每个环节的坑和取舍都讲清楚。这套方案适合谁如果你正在做社交类、内容社区类、在线教育类或者任何需要用户上传视频的Flutter应用并且你希望上传成功率能到99%以上、用户等待时间尽量短、流量消耗尽量可控那这篇内容可以直接拿去参考。即使你用的是原生开发或者其他跨平台框架分片上传的核心思路也是通用的。先说结论性的选型视频选择用image_picker或file_picker分片用Dart的RandomAccessFile做字节级切割上传用Dio配合自定义拦截器做并发和重试服务端用分片合并接口收尾。下面逐层展开。2. 视频选择环节的细节拆解与避坑2.1 image_picker与file_picker的取舍逻辑Flutter里选视频最常用的两个库是image_picker和file_picker。很多人随手选一个就用但其实两者在不同平台上的表现差异挺大。image_picker的优势在于它在iOS和Android上都封装了系统原生的媒体选择器用户看到的是系统相册界面体验统一而且它返回的XFile对象直接给了路径读取方便。但它的短板也很明显不能限制文件大小用户选了一个2GB的视频你也得接着不能多选视频部分版本支持但不够稳定在Android上某些定制系统里返回的路径可能是content://格式直接当文件路径用会报错。file_picker则更偏向通用文件选择可以按扩展名过滤可以多选返回的PlatformFile对象里带了bytes小文件或path大文件。但它在iOS上调起的是文件App而不是相册用户如果想从相册选视频操作路径会多一步体验上打折扣。我的实际选择是主用image_picker做视频选择用file_picker做兜底。具体来说在视频上传入口默认调image_picker如果用户反馈找不到视频或者在某些机型上崩溃提供一个“从文件中选择”的次要入口走file_picker。这样兼顾了体验和兼容性。// 主路径image_picker选视频 final ImagePicker _picker ImagePicker(); final XFile? video await _picker.pickVideo( source: ImageSource.gallery, maxDuration: const Duration(minutes: 10), // 限制最长时长 ); if (video ! null) { final file File(video.path); final size await file.length(); // 后续进入分片逻辑 }注意maxDuration在部分Android机型上不生效这是系统相册本身的限制不要依赖它做硬性校验选完之后自己再检查一次文件时长和大小。2.2 选完视频后的预处理元数据读取与校验视频选完之后不要急着上传先做几件事读文件大小、读视频时长、判断格式、生成缩略图。这些信息一方面用于UI展示另一方面用于决定分片策略。读文件大小用File.length()就行但要注意这个操作是异步的而且在大文件上可能有几十毫秒的延迟不要在主isolate里反复调。视频时长和缩略图可以用video_player或video_thumbnail库来获取但这两个库在部分机型上初始化较慢建议放在选完视频之后异步加载不要阻塞上传流程的启动。校验环节我一般设三条线文件大小上限比如500MB超过就提示用户压缩或裁剪、视频时长上限比如10分钟、格式白名单mp4、mov、avi等。这三条线不是拍脑袋定的要根据你服务端的存储成本和用户的实际网络情况来调。我试过把上限放到1GB结果发现大部分用户的4G网络下上传成功率骤降到60%以下后来压到300MB成功率直接回到95%以上。Futurebool validateVideo(File file) async { final size await file.length(); if (size 500 * 1024 * 1024) { // 超过500MB提示用户 return false; } final ext file.path.split(.).last.toLowerCase(); const allowed [mp4, mov, avi, mkv]; if (!allowed.contains(ext)) { return false; } return true; }2.3 权限处理的平台差异Android和iOS在读取相册视频时的权限模型不一样。Android 13之后引入了READ_MEDIA_VIDEO权限之前是READ_EXTERNAL_STORAGE。iOS则是NSPhotoLibraryUsageDescription。这些在pubspec和Info.plist里都要配好否则用户选完视频后读取文件会直接抛异常。我踩过的一个坑是在Android 13上只申请了READ_MEDIA_IMAGES结果选视频时系统相册里视频是灰的。后来改成同时申请READ_MEDIA_IMAGES和READ_MEDIA_VIDEO才正常。这个细节在官方文档里写得很隐蔽但实际项目中一定会遇到。3. 分片策略的核心原理与参数计算3.1 为什么要分片从TCP传输和HTTP协议说起大文件单次上传的问题本质上和TCP的传输机制有关。一个HTTP请求在底层是一条TCP连接TCP有拥塞控制、有滑动窗口、有超时重传。当文件很大时这条连接需要持续传输很长时间期间任何一次网络抖动都可能导致RTT飙升、窗口缩小甚至连接被中间设备比如运营商NAT回收。而且HTTP协议本身没有断点续传的原生支持一旦请求失败整个文件就得重来。分片上传的思路就是把一个大文件切成若干个小块每个小块单独发一个HTTP请求。这样做的好处有几个单个请求体积小失败后只需重传这一片可以并发发送多个分片充分利用带宽服务端可以边收边合并减少内存峰值天然支持断点续传记录哪些片已传成功即可。3.2 分片大小的计算与选择分片大小是这套方案里最关键的参数之一。太小了请求数量暴增每个请求的头部开销和TCP握手成本占比过高太大了单请求失败重传成本高并发粒度粗。我一般用这个公式来估算分片大小 目标单请求传输时间 × 预估上行带宽。假设你希望每个分片在3秒内传完用户4G上行带宽大约1Mbps到5Mbps实际值不是理论峰值取中间值2Mbps那么3秒能传约750KB。所以分片大小设在512KB到1MB之间比较合理。但实际项目中还要考虑服务端的限制。很多网关比如Nginx默认配置对单请求体大小有限制常见的是1MB或10MB。如果你设了5MB的分片但网关只允许1MB那请求会被直接拒掉。所以分片大小必须和服务端的client_max_body_size对齐。我的经验值是移动端视频上传分片大小设在1MB到2MB之间。这个区间在4G和WiFi下都能跑得比较顺请求数量也不会太夸张。一个100MB的视频切成1MB的片就是100个请求并发5个的话20轮就传完了。const int chunkSize 1024 * 1024; // 1MB final int totalChunks (fileSize / chunkSize).ceil();注意最后一个分片的大小可能小于chunkSize计算时要单独处理不要用整除。3.3 分片编号与偏移量计算每个分片需要有一个编号从0或1开始和一个字节偏移量。偏移量 分片编号 × 分片大小。服务端合并时就是按编号顺序把分片拼起来。这里有个容易出错的点如果文件大小正好是分片大小的整数倍最后一个分片的大小就是chunkSize不会多出一个空片。但如果用ceil计算总数当fileSize是chunkSize整数倍时ceil结果正好是整数没问题当有余数时ceil会多算一个片这个片的大小是余数。两种情况都要覆盖到。ListChunkInfo buildChunks(int fileSize, int chunkSize) { final chunks ChunkInfo[]; int offset 0; int index 0; while (offset fileSize) { final end (offset chunkSize fileSize) ? offset chunkSize : fileSize; chunks.add(ChunkInfo( index: index, start: offset, end: end, size: end - offset, )); offset end; index; } return chunks; }3.4 文件哈希与秒传判断在分片之前通常还要算一下整个文件的哈希值比如MD5或SHA1用于服务端判断这个文件是否已经存在如果存在就直接返回成功实现“秒传”。但算哈希本身是要读整个文件的对于大文件来说这个操作可能耗时几秒甚至十几秒。我的做法是先算一个快速哈希比如文件头1MB 文件尾1MB 文件大小的组合哈希用这个快速哈希去问服务端有没有。如果有再算完整哈希确认如果没有直接开始分片上传。这样大部分新文件都能跳过完整哈希的计算节省时间。FutureString quickHash(File file) async { final raf await file.open(); final size await file.length(); final head await raf.read(1024 * 1024); await raf.setPosition(size - 1024 * 1024); final tail await raf.read(1024 * 1024); await raf.close(); final combined [...head, ...tail, size]; // 用crypto库算MD5 return md5.convert(combined).toString(); }4. 分片上传的完整实操流程4.1 上传前的初始化请求在正式传分片之前先发一个初始化请求给服务端带上文件名、文件大小、总分片数、快速哈希。服务端返回一个uploadId本次上传会话的唯一标识以及一个已上传分片列表用于断点续传。这个初始化请求很关键它把上传的元信息先同步给服务端服务端可以提前分配存储空间、创建临时目录、记录会话状态。如果服务端发现这个哈希已经存在直接返回秒传标志客户端就不用传了。FutureUploadInitResult initUpload({ required String fileName, required int fileSize, required int totalChunks, required String quickHash, }) async { final resp await dio.post(/upload/init, data: { fileName: fileName, fileSize: fileSize, totalChunks: totalChunks, quickHash: quickHash, }); return UploadInitResult.fromJson(resp.data); }提示初始化请求要设置合理的超时时间建议5秒。如果5秒内没响应直接提示用户网络异常不要傻等。4.2 分片读取与并发发送分片读取用Dart的RandomAccessFile它可以按偏移量读取指定长度的字节不用把整个文件加载到内存。这对大文件来说非常重要——你不可能把一个500MB的视频全读进内存再切片那样直接OOM。FutureUint8List readChunk(File file, int start, int length) async { final raf await file.open(); await raf.setPosition(start); final bytes await raf.read(length); await raf.close(); return bytes; }并发发送用Dio配合一个并发控制器。Dart里可以用Pool或者自己写一个简单的信号量。我一般用Pool它能把并发数控制在指定值超出的任务排队等待。final pool Pool(5); // 最多5个并发 final uploadFutures chunks.map((chunk) { return pool.withResource(() async { final bytes await readChunk(file, chunk.start, chunk.size); final formData FormData.fromMap({ uploadId: uploadId, chunkIndex: chunk.index, chunk: MultipartFile.fromBytes(bytes, filename: chunk_${chunk.index}), }); await dio.post(/upload/chunk, data: formData); }); }).toList(); await Future.wait(uploadFutures);并发数设多少合适我实测下来4G网络下3到5个并发比较稳WiFi下可以到8个。并发太高会导致TCP连接竞争反而降低总吞吐量并发太低则带宽利用率不足。这个值可以根据网络类型动态调整用connectivity_plus检测当前是WiFi还是移动网络。4.3 进度计算与UI更新上传进度不能只按“已完成分片数/总分片数”来算因为每个分片的大小可能不一样最后一片通常小一些。更准确的做法是按已上传的字节数来算。int uploadedBytes 0; // 每个分片上传成功后 uploadedBytes chunk.size; final progress uploadedBytes / fileSize;但这里有个细节Dio的onSendProgress回调给的是当前请求已发送的字节数不是已确认接收的字节数。也就是说字节发出去了但服务端还没确认进度条就已经涨了。如果这时候请求失败进度条会回退体验不好。我的做法是进度条只按已确认成功的分片来更新当前正在传的分片用一个单独的“传输中”指示器表示。这样进度条只会前进不会后退用户感知更稳定。4.4 断点续传的实现断点续传的核心是每次上传前先问服务端哪些分片已经传成功了只传没传过的。初始化请求返回的已上传分片列表就是干这个用的。final uploadedSet initResult.uploadedChunks.toSet(); final pendingChunks chunks.where((c) !uploadedSet.contains(c.index)).toList();但这里有个坑服务端记录的已上传分片可能因为超时被清理了。比如用户传了一半退出过了24小时再进来服务端可能已经把临时文件删了。所以初始化请求返回的已上传列表要带一个时间戳客户端判断如果距离上次上传超过一定时间比如12小时就忽略这个列表全部重传。另外分片上传成功后服务端要立即持久化记录不能只放在内存里。我见过有的实现把已上传分片列表放在Redis里但没设持久化结果服务端重启后列表丢了客户端以为传过了合并时缺片直接失败。4.5 合并请求与收尾所有分片传完后发一个合并请求给服务端带上uploadId和总分片数。服务端按编号顺序把分片文件拼接成完整文件然后返回最终的文件URL。FutureString mergeChunks(String uploadId, int totalChunks) async { final resp await dio.post(/upload/merge, data: { uploadId: uploadId, totalChunks: totalChunks, }); return resp.data[fileUrl]; }合并操作在服务端可能是耗时的特别是大文件。所以合并请求的超时时间要设长一点建议30秒以上。如果服务端合并是异步的那就返回一个taskId客户端轮询查询合并状态。注意合并完成后服务端要清理临时分片文件否则磁盘会被慢慢占满。清理策略可以是合并成功后立即删也可以是定时任务扫描过期临时目录。5. 常见问题与排查技巧实录5.1 分片上传失败的高频原因速查表问题现象可能原因排查方向解决方案某个分片反复失败该分片字节读取越界检查startlength是否超过fileSize最后一个分片单独计算size上传到99%卡住合并请求超时查看服务端合并日志加长合并超时或改异步合并部分机型选视频后崩溃权限未申请或路径为content://检查AndroidManifest和运行时权限用contentResolver转真实路径进度条回退按发送字节算进度改为按确认分片算进度分离“传输中”和“已完成”状态断点续传后合并失败服务端分片记录丢失检查服务端持久化分片记录写数据库或持久化缓存上传速度慢并发数过低或分片过大测网络类型和实际上行带宽动态调整并发数和分片大小5.2 内存与性能的平衡技巧分片上传最容易出的性能问题是内存。如果你用MultipartFile.fromBytes每个分片的字节数组会先加载到内存再发送。5个并发就是5个分片同时在内存里1MB的分片就是5MB还能接受。但如果你把分片设成10MB5个并发就是50MB在低端机上可能直接触发GC甚至OOM。我的做法是分片大小不超过2MB并发数不超过5这样内存峰值控制在10MB以内。如果确实需要更大的分片就用流式上传Dio支持MultipartFile.fromFileStream可以从文件流直接读不经过内存。final stream file.openRead(chunk.start, chunk.end); final multipartFile MultipartFile.fromStream( () stream, chunk.size, filename: chunk_${chunk.index}, );但流式上传有个限制不能重试。因为流读一次就没了重试时流已经关闭。所以如果要用流式得在重试时重新打开流。我一般只在分片大于5MB时才用流式小分片直接用bytes更简单。5.3 网络切换与重试策略移动端网络切换很频繁WiFi走到信号边缘自动切4G或者进电梯断网几秒。分片上传必须能处理这些情况。我的重试策略是每个分片最多重试3次重试间隔指数退避1秒、2秒、4秒。如果3次都失败标记这个分片为失败但不中断其他分片的上传。等所有分片跑完后再对失败的分片做一轮重试。如果还有失败提示用户“部分内容上传失败是否重试”。Futurevoid uploadWithRetry(ChunkInfo chunk, int maxRetry) async { int attempt 0; while (attempt maxRetry) { try { await uploadChunk(chunk); return; } catch (e) { attempt; if (attempt maxRetry) rethrow; await Future.delayed(Duration(seconds: 1 attempt)); } } }提示重试时不要重新读文件把分片bytes缓存起来重试直接复用。但缓存会占内存所以只缓存失败的分片成功的分片及时释放。5.4 服务端配合的关键点分片上传不是客户端一个人的事服务端有几个必须配合的点第一分片接收接口要支持幂等。同一个uploadId和chunkIndex重复提交时服务端应该覆盖旧分片而不是报错。因为客户端重试时可能上一次请求其实已经成功了只是响应丢了。第二分片存储要用临时目录并且按uploadId隔离。不同用户的上传会话不能混在一起否则合并时会串。第三合并时要校验分片完整性。按编号顺序检查每个分片文件是否存在、大小是否匹配缺任何一个都不能合并。第四要有过期清理机制。超过24小时未完成的上传会话临时分片要自动清理否则磁盘会被垃圾数据占满。我踩过的一个坑是服务端用文件名做临时目录名结果两个用户同时上传同名文件分片互相覆盖合并出来的视频是乱的。后来改成用uploadIdUUID做目录名才解决。6. 完整代码结构与项目组织6.1 模块划分与职责边界这套逻辑在项目里不要全塞在一个文件里按职责拆成几个模块选择模块负责调起相册和文件校验分片模块负责计算分片和读取字节上传模块负责并发控制和重试状态模块负责进度和断点记录。lib/ upload/ video_picker.dart // 视频选择与校验 chunk_builder.dart // 分片计算 chunk_reader.dart // 字节读取 upload_client.dart // Dio封装与并发控制 upload_manager.dart // 整体流程编排 upload_state.dart // 状态与进度upload_manager是整个流程的入口它串起选择、分片、上传、合并四个阶段对外只暴露一个uploadVideo方法内部处理所有细节。这样UI层只需要调一个方法、监听一个进度流就行。6.2 状态管理与进度流用StreamController广播上传状态UI层用StreamBuilder监听。状态包括idle、selecting、validating、uploading、merging、success、failed。每个状态带上进度百分比和已上传字节数。final _stateController StreamControllerUploadState.broadcast(); StreamUploadState get stateStream _stateController.stream; void _emit(UploadState state) { _stateController.add(state); }注意StreamController要在dispose时关闭否则会内存泄漏。如果页面频繁进出建议把UploadManager做成单例或者用Provider管理生命周期。6.3 取消上传的处理用户点了取消怎么办不能直接杀进程要把正在进行的请求abort掉并且通知服务端清理临时分片。Dio的CancelToken可以取消请求。每个分片请求带同一个CancelToken取消时所有进行中的请求都会抛CancelException。然后在catch里判断如果是取消导致的就不再重试直接走清理逻辑。final cancelToken CancelToken(); // 请求时带上 dio.post(/upload/chunk, data: formData, cancelToken: cancelToken); // 取消时 cancelToken.cancel(user cancelled);服务端清理可以发一个/upload/abort请求带上uploadId服务端删除临时目录。如果这个请求也失败了就依赖服务端的过期清理机制兜底。7. 实测数据与优化经验7.1 不同网络环境下的参数调优我在几种典型网络下做过对比测试用同一个100MB的视频文件分片大小和并发数不同组合的结果如下网络类型分片大小并发数总耗时成功率WiFi1MB528秒99%WiFi2MB822秒97%4G1MB365秒96%4G2MB558秒92%弱网512KB2180秒88%弱网1MB3210秒82%从数据看WiFi下2MB分片加8并发最快但成功率略低4G下1MB分片加3并发最稳弱网下必须把分片调小、并发调低否则失败率飙升。所以最优策略是根据网络类型动态调整参数而不是一套参数打天下。7.2 弱网环境下的特殊处理弱网下除了调小分片和并发还有几个额外措施加大重试次数从3次加到5次、加长超时时间从10秒加到30秒、启用压缩如果视频本身可以压缩先压再传。但压缩视频本身很耗CPU低端机上可能压半天所以只对超过一定大小的视频启用并且给用户选择权。还有一个技巧是弱网下先传一个低码率的预览版本让用户快速看到内容高清版本后台慢慢传。这个方案在内容社区类应用里很常见用户体验提升明显。7.3 服务端合并的性能优化服务端合并分片时如果分片很多比如1000个逐个读取再拼接会很慢。优化方法是用文件系统的append模式按顺序把每个分片追加到目标文件避免在内存里拼接大数组。另外可以用sendfile系统调用做零拷贝减少用户态和内核态的数据搬运。如果服务端是分布式存储合并操作可以并行化把分片按顺序分给多个节点每个节点合并自己负责的连续片段最后再合并这些中间结果。但这套逻辑比较复杂一般项目用单机append就够了。8. 几个容易忽略的细节8.1 文件名编码问题用户选的视频文件名可能包含中文、空格、特殊字符。这些字符在HTTP头部传输时如果不编码服务端可能收到乱码。我的做法是客户端把文件名做URL编码后再传给服务端服务端解码后存储。或者干脆客户端生成一个UUID做文件名原始文件名只作为元数据存储不参与实际文件路径。8.2 分片顺序与合并顺序分片上传是并发的到达服务端的顺序是乱的。所以服务端合并时必须按chunkIndex排序不能按到达顺序拼接。我见过一个实现是按文件修改时间排序的结果合并出来的视频画面是乱的排查了半天才发现是排序逻辑错了。8.3 iOS后台上传的限制iOS对后台任务有严格限制App进入后台后网络请求可能被挂起。如果用户选完视频切到其他App上传可能中断。处理方式是用beginBackgroundTask申请一段后台执行时间通常有30秒左右足够传几个分片。如果超过时间还没传完就暂停上传等App回到前台再继续。// iOS后台任务申请需要通过MethodChannel调原生 // 这里只示意逻辑Android相对宽松一些但Doze模式下也会限制网络。可以用WorkManager或者前台服务来保活但前台服务要显示通知体验上要权衡。8.4 上传完成后的清理上传成功后客户端要清理本地的临时文件如果有、取消所有监听、关闭StreamController。服务端要删除临时分片目录。这些清理操作看起来简单但漏掉任何一个都可能导致资源泄漏。我一般会在finally块里统一做清理确保无论成功失败都会执行。这套方案我在几个项目里跑下来上传成功率从最初的70%多提升到了98%以上用户投诉明显减少。核心就是三点分片要合理、并发要可控、失败要能续。把这三点做到位视频上传这个功能就算真正做扎实了。
1. 移动端大文件上传的痛点与分片方案选型做过移动端视频类应用的朋友大概率都遇到过这个场景用户选了一段几分钟甚至十几分钟的视频点击上传然后进度条卡在某个位置不动了或者干脆报个网络超时用户骂骂咧咧地退出重试流量白烧体验稀碎。这个问题的根源不在于网络本身有多差而在于单次HTTP请求上传大文件本身就是一件极其脆弱的事情——任何一个环节抖动整个请求就废了。Flutter在跨平台开发里算是目前比较顺手的选择但它的生态里关于视频选择和分片上传的完整方案其实并不算多。很多教程只讲到怎么调起相册选个视频或者只讲怎么发一个multipart请求把“选”和“传”串起来、并且真正处理了分片逻辑的内容比较少。我这次就把自己在实际项目里跑通的一套方案完整拆一遍从选视频、读文件、切片、并发控制、断点续传到服务端合并每个环节的坑和取舍都讲清楚。这套方案适合谁如果你正在做社交类、内容社区类、在线教育类或者任何需要用户上传视频的Flutter应用并且你希望上传成功率能到99%以上、用户等待时间尽量短、流量消耗尽量可控那这篇内容可以直接拿去参考。即使你用的是原生开发或者其他跨平台框架分片上传的核心思路也是通用的。先说结论性的选型视频选择用image_picker或file_picker分片用Dart的RandomAccessFile做字节级切割上传用Dio配合自定义拦截器做并发和重试服务端用分片合并接口收尾。下面逐层展开。2. 视频选择环节的细节拆解与避坑2.1 image_picker与file_picker的取舍逻辑Flutter里选视频最常用的两个库是image_picker和file_picker。很多人随手选一个就用但其实两者在不同平台上的表现差异挺大。image_picker的优势在于它在iOS和Android上都封装了系统原生的媒体选择器用户看到的是系统相册界面体验统一而且它返回的XFile对象直接给了路径读取方便。但它的短板也很明显不能限制文件大小用户选了一个2GB的视频你也得接着不能多选视频部分版本支持但不够稳定在Android上某些定制系统里返回的路径可能是content://格式直接当文件路径用会报错。file_picker则更偏向通用文件选择可以按扩展名过滤可以多选返回的PlatformFile对象里带了bytes小文件或path大文件。但它在iOS上调起的是文件App而不是相册用户如果想从相册选视频操作路径会多一步体验上打折扣。我的实际选择是主用image_picker做视频选择用file_picker做兜底。具体来说在视频上传入口默认调image_picker如果用户反馈找不到视频或者在某些机型上崩溃提供一个“从文件中选择”的次要入口走file_picker。这样兼顾了体验和兼容性。// 主路径image_picker选视频 final ImagePicker _picker ImagePicker(); final XFile? video await _picker.pickVideo( source: ImageSource.gallery, maxDuration: const Duration(minutes: 10), // 限制最长时长 ); if (video ! null) { final file File(video.path); final size await file.length(); // 后续进入分片逻辑 }注意maxDuration在部分Android机型上不生效这是系统相册本身的限制不要依赖它做硬性校验选完之后自己再检查一次文件时长和大小。2.2 选完视频后的预处理元数据读取与校验视频选完之后不要急着上传先做几件事读文件大小、读视频时长、判断格式、生成缩略图。这些信息一方面用于UI展示另一方面用于决定分片策略。读文件大小用File.length()就行但要注意这个操作是异步的而且在大文件上可能有几十毫秒的延迟不要在主isolate里反复调。视频时长和缩略图可以用video_player或video_thumbnail库来获取但这两个库在部分机型上初始化较慢建议放在选完视频之后异步加载不要阻塞上传流程的启动。校验环节我一般设三条线文件大小上限比如500MB超过就提示用户压缩或裁剪、视频时长上限比如10分钟、格式白名单mp4、mov、avi等。这三条线不是拍脑袋定的要根据你服务端的存储成本和用户的实际网络情况来调。我试过把上限放到1GB结果发现大部分用户的4G网络下上传成功率骤降到60%以下后来压到300MB成功率直接回到95%以上。Futurebool validateVideo(File file) async { final size await file.length(); if (size 500 * 1024 * 1024) { // 超过500MB提示用户 return false; } final ext file.path.split(.).last.toLowerCase(); const allowed [mp4, mov, avi, mkv]; if (!allowed.contains(ext)) { return false; } return true; }2.3 权限处理的平台差异Android和iOS在读取相册视频时的权限模型不一样。Android 13之后引入了READ_MEDIA_VIDEO权限之前是READ_EXTERNAL_STORAGE。iOS则是NSPhotoLibraryUsageDescription。这些在pubspec和Info.plist里都要配好否则用户选完视频后读取文件会直接抛异常。我踩过的一个坑是在Android 13上只申请了READ_MEDIA_IMAGES结果选视频时系统相册里视频是灰的。后来改成同时申请READ_MEDIA_IMAGES和READ_MEDIA_VIDEO才正常。这个细节在官方文档里写得很隐蔽但实际项目中一定会遇到。3. 分片策略的核心原理与参数计算3.1 为什么要分片从TCP传输和HTTP协议说起大文件单次上传的问题本质上和TCP的传输机制有关。一个HTTP请求在底层是一条TCP连接TCP有拥塞控制、有滑动窗口、有超时重传。当文件很大时这条连接需要持续传输很长时间期间任何一次网络抖动都可能导致RTT飙升、窗口缩小甚至连接被中间设备比如运营商NAT回收。而且HTTP协议本身没有断点续传的原生支持一旦请求失败整个文件就得重来。分片上传的思路就是把一个大文件切成若干个小块每个小块单独发一个HTTP请求。这样做的好处有几个单个请求体积小失败后只需重传这一片可以并发发送多个分片充分利用带宽服务端可以边收边合并减少内存峰值天然支持断点续传记录哪些片已传成功即可。3.2 分片大小的计算与选择分片大小是这套方案里最关键的参数之一。太小了请求数量暴增每个请求的头部开销和TCP握手成本占比过高太大了单请求失败重传成本高并发粒度粗。我一般用这个公式来估算分片大小 目标单请求传输时间 × 预估上行带宽。假设你希望每个分片在3秒内传完用户4G上行带宽大约1Mbps到5Mbps实际值不是理论峰值取中间值2Mbps那么3秒能传约750KB。所以分片大小设在512KB到1MB之间比较合理。但实际项目中还要考虑服务端的限制。很多网关比如Nginx默认配置对单请求体大小有限制常见的是1MB或10MB。如果你设了5MB的分片但网关只允许1MB那请求会被直接拒掉。所以分片大小必须和服务端的client_max_body_size对齐。我的经验值是移动端视频上传分片大小设在1MB到2MB之间。这个区间在4G和WiFi下都能跑得比较顺请求数量也不会太夸张。一个100MB的视频切成1MB的片就是100个请求并发5个的话20轮就传完了。const int chunkSize 1024 * 1024; // 1MB final int totalChunks (fileSize / chunkSize).ceil();注意最后一个分片的大小可能小于chunkSize计算时要单独处理不要用整除。3.3 分片编号与偏移量计算每个分片需要有一个编号从0或1开始和一个字节偏移量。偏移量 分片编号 × 分片大小。服务端合并时就是按编号顺序把分片拼起来。这里有个容易出错的点如果文件大小正好是分片大小的整数倍最后一个分片的大小就是chunkSize不会多出一个空片。但如果用ceil计算总数当fileSize是chunkSize整数倍时ceil结果正好是整数没问题当有余数时ceil会多算一个片这个片的大小是余数。两种情况都要覆盖到。ListChunkInfo buildChunks(int fileSize, int chunkSize) { final chunks ChunkInfo[]; int offset 0; int index 0; while (offset fileSize) { final end (offset chunkSize fileSize) ? offset chunkSize : fileSize; chunks.add(ChunkInfo( index: index, start: offset, end: end, size: end - offset, )); offset end; index; } return chunks; }3.4 文件哈希与秒传判断在分片之前通常还要算一下整个文件的哈希值比如MD5或SHA1用于服务端判断这个文件是否已经存在如果存在就直接返回成功实现“秒传”。但算哈希本身是要读整个文件的对于大文件来说这个操作可能耗时几秒甚至十几秒。我的做法是先算一个快速哈希比如文件头1MB 文件尾1MB 文件大小的组合哈希用这个快速哈希去问服务端有没有。如果有再算完整哈希确认如果没有直接开始分片上传。这样大部分新文件都能跳过完整哈希的计算节省时间。FutureString quickHash(File file) async { final raf await file.open(); final size await file.length(); final head await raf.read(1024 * 1024); await raf.setPosition(size - 1024 * 1024); final tail await raf.read(1024 * 1024); await raf.close(); final combined [...head, ...tail, size]; // 用crypto库算MD5 return md5.convert(combined).toString(); }4. 分片上传的完整实操流程4.1 上传前的初始化请求在正式传分片之前先发一个初始化请求给服务端带上文件名、文件大小、总分片数、快速哈希。服务端返回一个uploadId本次上传会话的唯一标识以及一个已上传分片列表用于断点续传。这个初始化请求很关键它把上传的元信息先同步给服务端服务端可以提前分配存储空间、创建临时目录、记录会话状态。如果服务端发现这个哈希已经存在直接返回秒传标志客户端就不用传了。FutureUploadInitResult initUpload({ required String fileName, required int fileSize, required int totalChunks, required String quickHash, }) async { final resp await dio.post(/upload/init, data: { fileName: fileName, fileSize: fileSize, totalChunks: totalChunks, quickHash: quickHash, }); return UploadInitResult.fromJson(resp.data); }提示初始化请求要设置合理的超时时间建议5秒。如果5秒内没响应直接提示用户网络异常不要傻等。4.2 分片读取与并发发送分片读取用Dart的RandomAccessFile它可以按偏移量读取指定长度的字节不用把整个文件加载到内存。这对大文件来说非常重要——你不可能把一个500MB的视频全读进内存再切片那样直接OOM。FutureUint8List readChunk(File file, int start, int length) async { final raf await file.open(); await raf.setPosition(start); final bytes await raf.read(length); await raf.close(); return bytes; }并发发送用Dio配合一个并发控制器。Dart里可以用Pool或者自己写一个简单的信号量。我一般用Pool它能把并发数控制在指定值超出的任务排队等待。final pool Pool(5); // 最多5个并发 final uploadFutures chunks.map((chunk) { return pool.withResource(() async { final bytes await readChunk(file, chunk.start, chunk.size); final formData FormData.fromMap({ uploadId: uploadId, chunkIndex: chunk.index, chunk: MultipartFile.fromBytes(bytes, filename: chunk_${chunk.index}), }); await dio.post(/upload/chunk, data: formData); }); }).toList(); await Future.wait(uploadFutures);并发数设多少合适我实测下来4G网络下3到5个并发比较稳WiFi下可以到8个。并发太高会导致TCP连接竞争反而降低总吞吐量并发太低则带宽利用率不足。这个值可以根据网络类型动态调整用connectivity_plus检测当前是WiFi还是移动网络。4.3 进度计算与UI更新上传进度不能只按“已完成分片数/总分片数”来算因为每个分片的大小可能不一样最后一片通常小一些。更准确的做法是按已上传的字节数来算。int uploadedBytes 0; // 每个分片上传成功后 uploadedBytes chunk.size; final progress uploadedBytes / fileSize;但这里有个细节Dio的onSendProgress回调给的是当前请求已发送的字节数不是已确认接收的字节数。也就是说字节发出去了但服务端还没确认进度条就已经涨了。如果这时候请求失败进度条会回退体验不好。我的做法是进度条只按已确认成功的分片来更新当前正在传的分片用一个单独的“传输中”指示器表示。这样进度条只会前进不会后退用户感知更稳定。4.4 断点续传的实现断点续传的核心是每次上传前先问服务端哪些分片已经传成功了只传没传过的。初始化请求返回的已上传分片列表就是干这个用的。final uploadedSet initResult.uploadedChunks.toSet(); final pendingChunks chunks.where((c) !uploadedSet.contains(c.index)).toList();但这里有个坑服务端记录的已上传分片可能因为超时被清理了。比如用户传了一半退出过了24小时再进来服务端可能已经把临时文件删了。所以初始化请求返回的已上传列表要带一个时间戳客户端判断如果距离上次上传超过一定时间比如12小时就忽略这个列表全部重传。另外分片上传成功后服务端要立即持久化记录不能只放在内存里。我见过有的实现把已上传分片列表放在Redis里但没设持久化结果服务端重启后列表丢了客户端以为传过了合并时缺片直接失败。4.5 合并请求与收尾所有分片传完后发一个合并请求给服务端带上uploadId和总分片数。服务端按编号顺序把分片文件拼接成完整文件然后返回最终的文件URL。FutureString mergeChunks(String uploadId, int totalChunks) async { final resp await dio.post(/upload/merge, data: { uploadId: uploadId, totalChunks: totalChunks, }); return resp.data[fileUrl]; }合并操作在服务端可能是耗时的特别是大文件。所以合并请求的超时时间要设长一点建议30秒以上。如果服务端合并是异步的那就返回一个taskId客户端轮询查询合并状态。注意合并完成后服务端要清理临时分片文件否则磁盘会被慢慢占满。清理策略可以是合并成功后立即删也可以是定时任务扫描过期临时目录。5. 常见问题与排查技巧实录5.1 分片上传失败的高频原因速查表问题现象可能原因排查方向解决方案某个分片反复失败该分片字节读取越界检查startlength是否超过fileSize最后一个分片单独计算size上传到99%卡住合并请求超时查看服务端合并日志加长合并超时或改异步合并部分机型选视频后崩溃权限未申请或路径为content://检查AndroidManifest和运行时权限用contentResolver转真实路径进度条回退按发送字节算进度改为按确认分片算进度分离“传输中”和“已完成”状态断点续传后合并失败服务端分片记录丢失检查服务端持久化分片记录写数据库或持久化缓存上传速度慢并发数过低或分片过大测网络类型和实际上行带宽动态调整并发数和分片大小5.2 内存与性能的平衡技巧分片上传最容易出的性能问题是内存。如果你用MultipartFile.fromBytes每个分片的字节数组会先加载到内存再发送。5个并发就是5个分片同时在内存里1MB的分片就是5MB还能接受。但如果你把分片设成10MB5个并发就是50MB在低端机上可能直接触发GC甚至OOM。我的做法是分片大小不超过2MB并发数不超过5这样内存峰值控制在10MB以内。如果确实需要更大的分片就用流式上传Dio支持MultipartFile.fromFileStream可以从文件流直接读不经过内存。final stream file.openRead(chunk.start, chunk.end); final multipartFile MultipartFile.fromStream( () stream, chunk.size, filename: chunk_${chunk.index}, );但流式上传有个限制不能重试。因为流读一次就没了重试时流已经关闭。所以如果要用流式得在重试时重新打开流。我一般只在分片大于5MB时才用流式小分片直接用bytes更简单。5.3 网络切换与重试策略移动端网络切换很频繁WiFi走到信号边缘自动切4G或者进电梯断网几秒。分片上传必须能处理这些情况。我的重试策略是每个分片最多重试3次重试间隔指数退避1秒、2秒、4秒。如果3次都失败标记这个分片为失败但不中断其他分片的上传。等所有分片跑完后再对失败的分片做一轮重试。如果还有失败提示用户“部分内容上传失败是否重试”。Futurevoid uploadWithRetry(ChunkInfo chunk, int maxRetry) async { int attempt 0; while (attempt maxRetry) { try { await uploadChunk(chunk); return; } catch (e) { attempt; if (attempt maxRetry) rethrow; await Future.delayed(Duration(seconds: 1 attempt)); } } }提示重试时不要重新读文件把分片bytes缓存起来重试直接复用。但缓存会占内存所以只缓存失败的分片成功的分片及时释放。5.4 服务端配合的关键点分片上传不是客户端一个人的事服务端有几个必须配合的点第一分片接收接口要支持幂等。同一个uploadId和chunkIndex重复提交时服务端应该覆盖旧分片而不是报错。因为客户端重试时可能上一次请求其实已经成功了只是响应丢了。第二分片存储要用临时目录并且按uploadId隔离。不同用户的上传会话不能混在一起否则合并时会串。第三合并时要校验分片完整性。按编号顺序检查每个分片文件是否存在、大小是否匹配缺任何一个都不能合并。第四要有过期清理机制。超过24小时未完成的上传会话临时分片要自动清理否则磁盘会被垃圾数据占满。我踩过的一个坑是服务端用文件名做临时目录名结果两个用户同时上传同名文件分片互相覆盖合并出来的视频是乱的。后来改成用uploadIdUUID做目录名才解决。6. 完整代码结构与项目组织6.1 模块划分与职责边界这套逻辑在项目里不要全塞在一个文件里按职责拆成几个模块选择模块负责调起相册和文件校验分片模块负责计算分片和读取字节上传模块负责并发控制和重试状态模块负责进度和断点记录。lib/ upload/ video_picker.dart // 视频选择与校验 chunk_builder.dart // 分片计算 chunk_reader.dart // 字节读取 upload_client.dart // Dio封装与并发控制 upload_manager.dart // 整体流程编排 upload_state.dart // 状态与进度upload_manager是整个流程的入口它串起选择、分片、上传、合并四个阶段对外只暴露一个uploadVideo方法内部处理所有细节。这样UI层只需要调一个方法、监听一个进度流就行。6.2 状态管理与进度流用StreamController广播上传状态UI层用StreamBuilder监听。状态包括idle、selecting、validating、uploading、merging、success、failed。每个状态带上进度百分比和已上传字节数。final _stateController StreamControllerUploadState.broadcast(); StreamUploadState get stateStream _stateController.stream; void _emit(UploadState state) { _stateController.add(state); }注意StreamController要在dispose时关闭否则会内存泄漏。如果页面频繁进出建议把UploadManager做成单例或者用Provider管理生命周期。6.3 取消上传的处理用户点了取消怎么办不能直接杀进程要把正在进行的请求abort掉并且通知服务端清理临时分片。Dio的CancelToken可以取消请求。每个分片请求带同一个CancelToken取消时所有进行中的请求都会抛CancelException。然后在catch里判断如果是取消导致的就不再重试直接走清理逻辑。final cancelToken CancelToken(); // 请求时带上 dio.post(/upload/chunk, data: formData, cancelToken: cancelToken); // 取消时 cancelToken.cancel(user cancelled);服务端清理可以发一个/upload/abort请求带上uploadId服务端删除临时目录。如果这个请求也失败了就依赖服务端的过期清理机制兜底。7. 实测数据与优化经验7.1 不同网络环境下的参数调优我在几种典型网络下做过对比测试用同一个100MB的视频文件分片大小和并发数不同组合的结果如下网络类型分片大小并发数总耗时成功率WiFi1MB528秒99%WiFi2MB822秒97%4G1MB365秒96%4G2MB558秒92%弱网512KB2180秒88%弱网1MB3210秒82%从数据看WiFi下2MB分片加8并发最快但成功率略低4G下1MB分片加3并发最稳弱网下必须把分片调小、并发调低否则失败率飙升。所以最优策略是根据网络类型动态调整参数而不是一套参数打天下。7.2 弱网环境下的特殊处理弱网下除了调小分片和并发还有几个额外措施加大重试次数从3次加到5次、加长超时时间从10秒加到30秒、启用压缩如果视频本身可以压缩先压再传。但压缩视频本身很耗CPU低端机上可能压半天所以只对超过一定大小的视频启用并且给用户选择权。还有一个技巧是弱网下先传一个低码率的预览版本让用户快速看到内容高清版本后台慢慢传。这个方案在内容社区类应用里很常见用户体验提升明显。7.3 服务端合并的性能优化服务端合并分片时如果分片很多比如1000个逐个读取再拼接会很慢。优化方法是用文件系统的append模式按顺序把每个分片追加到目标文件避免在内存里拼接大数组。另外可以用sendfile系统调用做零拷贝减少用户态和内核态的数据搬运。如果服务端是分布式存储合并操作可以并行化把分片按顺序分给多个节点每个节点合并自己负责的连续片段最后再合并这些中间结果。但这套逻辑比较复杂一般项目用单机append就够了。8. 几个容易忽略的细节8.1 文件名编码问题用户选的视频文件名可能包含中文、空格、特殊字符。这些字符在HTTP头部传输时如果不编码服务端可能收到乱码。我的做法是客户端把文件名做URL编码后再传给服务端服务端解码后存储。或者干脆客户端生成一个UUID做文件名原始文件名只作为元数据存储不参与实际文件路径。8.2 分片顺序与合并顺序分片上传是并发的到达服务端的顺序是乱的。所以服务端合并时必须按chunkIndex排序不能按到达顺序拼接。我见过一个实现是按文件修改时间排序的结果合并出来的视频画面是乱的排查了半天才发现是排序逻辑错了。8.3 iOS后台上传的限制iOS对后台任务有严格限制App进入后台后网络请求可能被挂起。如果用户选完视频切到其他App上传可能中断。处理方式是用beginBackgroundTask申请一段后台执行时间通常有30秒左右足够传几个分片。如果超过时间还没传完就暂停上传等App回到前台再继续。// iOS后台任务申请需要通过MethodChannel调原生 // 这里只示意逻辑Android相对宽松一些但Doze模式下也会限制网络。可以用WorkManager或者前台服务来保活但前台服务要显示通知体验上要权衡。8.4 上传完成后的清理上传成功后客户端要清理本地的临时文件如果有、取消所有监听、关闭StreamController。服务端要删除临时分片目录。这些清理操作看起来简单但漏掉任何一个都可能导致资源泄漏。我一般会在finally块里统一做清理确保无论成功失败都会执行。这套方案我在几个项目里跑下来上传成功率从最初的70%多提升到了98%以上用户投诉明显减少。核心就是三点分片要合理、并发要可控、失败要能续。把这三点做到位视频上传这个功能就算真正做扎实了。
