做上传功能最怕的就是文件传到一半网断了，尤其是几十上百 MB 的日志包和视频素材。你在 Flutter 项目里找了半天，发现 chunked_uploader 这个三方库正好支持分片传输和断点续传，本来以为加上去就能收工，结果一到鸿蒙设备上就各种水土不服：路径不对、权限报错、请求失败、插件没有 HarmonyOS 实现。这篇指南就是把我这次适配的完整过程、踩过的坑、改过的代码和最终跑通的方案整理出来，给要在鸿蒙上做 Flutter 大文件上传的开发者一个可以直接抄作业的参考。
1. 项目整体思路：为什么绕不开分片传输与断点续传
1.1 完整上传的最大痛点：重来成本太高
很多人会问断点续传和完整上传到底有什么区别，其实一句话就能说清楚：完整上传是一个请求从头传到尾，中间断了就全部作废；分片上传是把文件切成 N 块，每块单独请求，已经传成功的块不需要再传。听起来很简单，但真要在生产环境里落地，区分点很关键。
我这次接的业务是需要上传 100MB 到 1GB 级别的安装包和日志文件，首次提交时用的就是 Flutter 自带的http.MultipartFile直接post。最开始小文件没问题，文件一大问题立刻来：手机网络切换导致连接超时、弱网环境下 TCP 连接被重置、上传进度只能靠一个简陋的onProgress回调去猜，一旦失败整包重传。用户那边 4G 网络一波动，单文件传到 80% 就断，重来一次又是十几分钟，这是完整上传方案在移动端完全行不通的根本原因。
分片传输要做对，不只是把文件拆开那么简单，还涉及分片大小怎么定、失败后怎么重试、暂停恢复后如何跳过已传分片、服务端如何合并这些片。核心目标只有一个：让每一次网络失败的成本被限制在一个可控的小范围内。这也是我最后选择基于 chunked_uploader 方案去改造的根本动机。
1.2 chunked_uploader 到底解决了什么问题
chunked_uploader 是一个纯 Dart 实现的 Flutter 三方库，核心思路是把大文件拆成多个 chunk，然后并行或串行上传这些分片，并提供暂停、继续、进度回调这些能力。它没有绑定 Android/iOS 原生代码，这也是我在鸿蒙上敢碰它的重要原因——纯 Dart 的三方库在鸿蒙 Flutter 引擎里有很大概率直接编译通过。
从实际功能上看，它解决的是“切块”和“单块重试”的问题：你把文件路径传进去，它内部按指定 chunk 大小读取文件内容，封装成可以重复提交的分片请求；某个分片失败了，只需要重试那一片，而不是重新传整个文件。对于断点续传，它把上传库的基础能力做出来了，但真正要支撑“稳健”两个字，光靠它自身还不够，需要在外围补齐鸿蒙的权限、路径、网络策略和服务端的合并协议。
我拿它做底座，再在外面包了一层自己的上传管理器，原因后面会展开。但必须承认：没有它把“文件分块”和“逐块请求”这件事抽象好，我这次适配要写的底层代码会多得多。
1.3 鸿蒙环境带来的额外复杂度
鸿蒙设备上跑 Flutter，底层不再是 Android 的 ART 和 Bionic，而是 OpenHarmony 体系的运行时和自绘引擎。理论上 Dart 代码跨平台没问题，但一旦代码里用到dart:io、依赖某个第三方插件的原生实现，问题就来了。
chunked_uploader 本身是纯 Dart 的，所以编译问题不大，但它依赖的http包要发网络请求，读写文件要依赖dart:io的File，这两块在鸿蒙 Flutter SDK 里虽然都有实现，实际表现却和 Android 并不完全一样。再加上获取文件路径通常要依赖file_picker这类插件，这些插件如果没有 HarmonyOS 的安装包实现，就会直接抛MissingPluginException，连编译都过不了。
我把整体适配拆成了四层：环境层（Flutter SDK 与鸿蒙工程配置）、权限层（网络权限、明文流量策略）、数据层（文件路径获取与断点记录持久化）、协议层（与服务端对接的分片上传和合并规则）。这种拆法让每个问题都有独立的排查范围，实际调试时省了很多时间。
2. 环境准备与依赖分析
2.1 鸿蒙 Flutter 开发环境怎么搭
做适配之前不要急着改代码，先把环境跑扎实。鸿蒙 Flutter 开发需要 DevEco Studio 和对应的鸿蒙 Flutter SDK，具体版本号变化很快，建议直接装官方推荐的搭配。装完后执行flutter doctor，有很大概率看到一条 “The current configured Flutter SDK is not known to be fully supported. Please...” 的警告。
这条警告别慌，它大多数时候只是版本匹配检测不到位造成的提示，只要你的 Flutter SDK 版本和 DevEco Studio 中配置的鸿蒙 SDK 版本对得上，通常可以继续开发。我的建议是把 Flutter SDK 版本固定住，不要随手升级，因为鸿蒙的适配版本往往滞后于 Flutter 官方版本，升一个新版本可能带出编译器和运行时兼容问题。
工程上还要注意：鸿蒙应用的工程结构里会有entry/src/main/module.json5这样的配置文件，Flutter 生成的ohos目录是鸿蒙侧原生工程的根。后续改权限、配网络策略都要在这里改，不是在android/目录里改了。
2.2 chunked_uploader 依赖兼容性检查
在用flutter pub add chunked_uploader之前，先查一下它的pubspec.yaml依赖了哪些包。一般来说它会依赖http、path这类常用包，如果鸿蒙 Flutter SDK 自带的 Dart SDK 版本比较老，有可能出现依赖版本不满足的情况。
遇到版本冲突时，不用急着换库，先看有没有兼容版本。我这次就遇到通过dependency_overrides把http固定到一个同时兼容 chunked_uploader 和鸿蒙 Flutter SDK 的版本后编译通过的情况。建议把你的最小 Flutter/Dart 版本约束设成和你正在用的鸿蒙 SDK 匹配，不要全局升级依赖。
另外，要确认你翻到的示例代码里没有用到 Android 专属的原生插件。chunked_uploader 的资料本来就少，网上很多 demo 是自己用FilePicker.platform.pickFiles()去拿路径，这部分在鸿蒙上最容易炸。纯上传库本身没问题，外围代码才是重灾区。
2.3 文件路径获取是第一个坎
鸿蒙应用的文件沙盒路径和 Android 不一样，第三方文件选择器在鸿蒙上也没有默认的安装包实现。如果你的代码还是照抄file_picker的调用方式，大概率会在鸿蒙上直接抛MissingPluginException。
我的处理方案是不要在一个流程里同时依赖多个原生插件，而是分两步走：第一步，先拿到一个可用的文件沙盒目录，比如应用缓存目录；第二步，把文件先复制到沙盒目录，然后交给分片上传逻辑读取。文件从哪里来可以单独走系统分享面板、深度链接或者自己的文件管理页面，这样chunked_uploader的输入就变成了一个纯文件路径，少掉一大部分插件兼容风险。
获取缓存目录如果path_provider没有鸿蒙实现，可以自己写一个极其简单的MethodChannel，用 ArkTS 在原生侧返回应用缓存目录。这个通道只做一件事，就算不用path_provider也能稳定运行。
3. 鸿蒙适配改造实操
3.1 网络权限声明与明文流量策略
鸿蒙应用默认不允许访问网络，必然要显式声明ohos.permission.INTERNET。在module.json5里加上对应的requestPermissions配置，这一步不做，后面所有网络请求都是空中楼阁。
{ "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } }权限只是第一步。如果你的上传服务端是 HTTP 明文地址，鸿蒙默认的网络安全策略大概率会拦截。不要试图在代码里绕过系统限制，最稳的做法是生产环境用 HTTPS，开发环境用本地 HTTPS 测试服务器或按鸿蒙文档显式配置网络安全策略。我这次在开发阶段就被这个坑拖了一天：Dart 层拿到的错误码是2300056，查了半天才发现是网络策略在拦截。
3.2 文件路径读取的兼容实现
如果你必须用平台通道拿路径，实际上就几个步骤。Dart 侧定义一个MethodChannel，调用原生方法获取路径：
class HarmonyPath { static const MethodChannel _channel = MethodChannel('com.example.upload/path'); static Future<String> getCacheDirectory() async { final String? path = await _channel.invokeMethod('getCacheDirectory'); if (path == null || path.isEmpty) { throw Exception('获取鸿蒙缓存目录失败'); } return path; } }鸿蒙原生侧用 ArkTS 或 Java/Kotlin 兼容层实现同名通道，返回应用沙盒目录即可。重点提醒：Dart 侧不要做任何Platform.isAndroid的假设，因为你没法保证鸿蒙 Flutter SDK 里这个值一定返回什么，很多人在这个问题上栽过跟头。更稳妥的做法是通道方法返回一个系统标识字符串，比如"HarmonyOS"，你的业务代码只认这个字符串。
3.3 断点记录持久化：别依赖 shared_preferences
断点续传最怕的是 App 被杀或用户手动退出后进度丢失。记录“哪些分片已经传成功”这件事，很多人会下意识用shared_preferences，但它在鸿蒙上如果插件没有实现，就会直接MissingPluginException。
更可靠的做法是直接落本地文件，毕竟上传记录本质是一小段 JSON。我自己维护了一个UploadPersistence类：
class UploadPersistence { Future<void> saveUploadRecord(String uploadId, Map<String, dynamic> record) async { final File file = File('${cacheDir.path}/upload_records/$uploadId.json'); await file.create(recursive: true); await file.writeAsString(jsonEncode(record)); } Future<Map<String, dynamic>?> loadUploadRecord(String uploadId) async { final File file = File('${cacheDir.path}/upload_records/$uploadId.json'); if (!await file.exists()) return null; final String content = await file.readAsString(); return jsonDecode(content) as Map<String, dynamic>; } Future<void> removeUploadRecord(String uploadId) async { final File file = File('${cacheDir.path}/upload_records/$uploadId.json'); if (await file.exists()) { await file.delete(); } } }为什么不用数据库？因为上传状态结构非常简单：文件 ID、分片大小、总分片数、已上传分片索引列表。一套 JSON 足够，数据库反而引入额外依赖。把记录文件放在应用沙盒的缓存目录里，用户清除缓存时自动清掉，逻辑上也说得通。
3.4 暂停与恢复的状态机设计
chunked_uploader本身提供了暂停和继续的底层能力，但在鸿蒙上我建议把它包装成一个任务状态机，避免 UI 和上传逻辑互相乱调。我的状态定义是：
idle：任务已创建，尚未开始。uploading：正在上传分片。paused：用户主动暂停，已上传分片列表已持久化。completed：所有分片上传完成并且服务端合并成功。failed：出现不可自动恢复的错误。
真正执行暂停时，不是暴力中断当前网络请求，而是设置一个取消标志，让当前分片发送完成后停住，然后立即保存记录。这样恢复时只需要读取本地记录，跳过已经完成的分片索引。代码上我会用一个简单的UploadTaskController来管这个状态，UI 层只调用start/pause/resume三个方法，不直接碰 http 对象。
3.5 核心改造代码：一套可落地的分片上传器
虽然 chunked_uploader 给了基础能力，但鸿蒙适配过程中我最终更依赖自己封装的分片上传器，因为它更容易处理服务端协议和本地状态记录。下面是一个精简但可直接运行的结构：
class ChunkedUploadService { ChunkedUploadService({ required this.httpClient, required this.uploadUrl, required this.initUrl, required this.completeUrl, required this.chunkSize, }); final http.Client httpClient; final String uploadUrl; final String initUrl; final String completeUrl; final int chunkSize; Future<void> uploadFile({ required String filePath, required String fileName, required UploadProgressCallback onProgress, required UploadTaskController controller, }) async { final File file = File(filePath); final int fileSize = await file.length(); final int totalChunks = (fileSize / chunkSize).ceil(); // 1. 初始化上传，获取服务端已接收的分片列表 final UploadSession session = await _initUpload(fileName, fileSize, totalChunks); for (int chunkIndex = 0; chunkIndex < totalChunks; chunkIndex++) { if (controller.isPaused || controller.shouldCancel) { // 2. 暂停：保存当前索引，停止循环 await _persistSession(session); return; } // 3. 跳过已经上传成功的分片 if (session.uploadedChunkIndexes.contains(chunkIndex)) { continue; } // 4. 读取文件块 final int start = chunkIndex * chunkSize; final int end = ((start + chunkSize) > fileSize) ? fileSize : (start + chunkSize); final Uint8List bytes = await file.readAsBytes(start: start, end: end); // 5. 上传分片，失败时做有限重试 await _uploadChunkWithRetry( session: session, chunkIndex: chunkIndex, bytes: bytes, retryCount: 3, ); onProgress((chunkIndex + 1) / totalChunks); await _persistSession(session); } // 6. 通知服务端合并文件 await _completeUpload(session, totalChunks); await _clearSession(session); } }这段代码相当于把 chunked_uploader 的“分块 + 重试”理念落地成了鸿蒙上可控的实现。关键点在于每次循环结束都持久化一次 session，让崩溃恢复也能接着传。
4. 服务端协议与断点续传的可靠性设计
4.1 分片上传协议怎么设计
客户端再怎么优化，服务端不支持分片合并也是白搭。我给这次项目设计的是三个接口：
POST /upload/init body: { fileName, fileSize, chunkSize, fileMd5 } resp: { uploadId, uploadedChunkIndexes: [], totalChunks } POST /upload/part body: { uploadId, chunkIndex, chunkData, chunkMd5 } resp: { ok } POST /upload/complete body: { uploadId, totalChunks, fileMd5 } resp: { fileUrl }init接口返回服务端已经存了哪些分片，这是续传的关键。客户端只需要把自己本地记录的 index 和服务端返回的 index 做一次并集，就能决定哪些分片不用传，避免“本地记录丢了就只能全量重传”的尴尬。这里不需要造复杂的轮子，HTTP + JSON + MultipartFile 就够用。
4.2 分片大小要综合权衡
分片大小是改造初期就要拍板的事情，我最后选的是 4MB。原因很简单：分片太大会让单次失败成本变高，比如 100MB 文件切成 8MB，一次失败要重传 8MB；分片太小会让请求数量爆炸，比如 1MB 分片一个大文件要传几百次，服务端接口压力大，网络握手开销也高。
用公式换算一下更直观：一个 200MB 文件，4MB 分片就是 50 片，断点一次最多损失 4MB；如果服务端限制单请求体不超过 8MB，4MB 分片也很安全。具体业务里你可以根据服务端网关限制和用户网络质量在 2MB 到 8MB 之间调，但要记住：这个参数必须在服务端也做同样配置，两端约定好，不能客户端自动就改。
4.3 续传不丢不进度的四个细节
第一个细节是幂等。客户端网络超时后重试，可能服务端其实已经收到这一片了，客户端却拿不到响应。所以upload/part接口必须允许对同一个uploadId + chunkIndex重复提交，服务端覆盖存储即可，不能报错。
第二个细节是分片校验。每个分片带上chunkMd5，服务端校验不通过就返回失败，客户端直接重传这一片。如果跳过校验，文件合并后损坏的概率会随着文件大小增加明显上升。
第三个细节是服务端分片过期清理。很多用户上传一半就放弃，服务端如果无限期保留所有孤儿分片，存储会越来越膨胀。我一般设置 7 天有效期，过期后由定时任务清理对应分片和元数据。
第四个细节是合并时机。complete接口触发文件合并后要校验整体文件的fileMd5，校验不通过要能让客户端重新上传损坏的分片，而不是静默成功返回一个坏文件。
4.4 断点续传和完整上传的边界
设计协议时也别做过度的东西。小文件比如 5MB 以下，我建议直接走完整上传接口，没必要初始化分片会话；文件超过设定阈值后再切到分片链路。业务层可以做一次阈值分流，这样小文件上传更快，大文件收益最大，服务端也不用为了所有文件都维护分片元数据。
这个判断在线上的感受非常明显：1MB 的文件走分片流程，光 init 和 complete 的两次请求就浪费几百毫秒，但如果整包失败重传，代价又太高。阈值放在 10MB 或者 20MB 都可以，根据你服务的真实网络环境测一下再定。
5. 常见问题与排查技巧实录
5.1 请求 2300056 的排查路径
鸿蒙开发过程中，我遇到最多的错误码就是某个网络请求报2300056，无论你怎么看 Flutter 侧的异常对象，都很难拿到更具体的底层信息。执行以下排查顺序通常能定位问题：
- 查
module.json5里有没有声明ohos.permission.INTERNET。 - 查请求 URL 是不是 HTTP 明文，鸿蒙网络安全策略是否放行。
- 查服务端地址能不能在鸿蒙设备上用浏览器或原生请求直接访问。
- 如果你开着抓包工具，先把抓包断开再测一次，确定不是调试环境干扰。
出现错误码不代表一定是代码问题，很多时候只是我在 DevEco 里配置漏了权限，或者本地服务地址写成了localhost，设备端根本访问不到开发机的服务。
5.2 抓包工具看不到鸿蒙请求
鸿蒙应用抓包和 Android 不太一样。如果你的测试环境是 HTTPS，抓包工具需要信任对应证书，而鸿蒙系统默认不信任用户安装的证书，导致你能看到 TCP 连接，却看不到明文内容。
我实际的做法是：开发阶段给本地测试服务配一个正式受信证书，或者直接使用 HTTP 在局域网内做连通性验证，上线再转向 HTTPS。抓包能看到请求头、分片序号和返回码就够了，不要为了解密密文在抓包工具上花太多时间。
5.3 Platform.isAndroid 不可靠
鸿蒙 Flutter 运行时对Platform.isAndroid的处理在不同版本可能不一致，依赖这个值做业务分支是危险的。我有一次就是因为代码里写了if (Platform.isAndroid)走 Android 路径，结果在鸿蒙上走到了完全错误的分支。
建议统一封装一个SystemPlatformUtil，通过 MethodChannel 拿真实系统标识，或者把“是否为鸿蒙”作为一种显式的运行时配置注入，而不是靠 dart:io 的Platform猜测。
5.4 插件报 MissingPluginException 的批量解法
file_picker、path_provider、shared_preferences这三个插件是最常见的报错来源。批量检查方案是：在鸿蒙工程里搜索有没有对应的.hvigor插件实现目录，没有就一律换掉。
我最终的依赖清单里，原生类插件只保留了两个：一个用于平台通道拿系统目录，一个用于拉起系统文件选择器。其余全部用纯 Dart 方案或文件落盘方案解决。这样依赖越少，鸿蒙适配的问题就越少。
5.5 hdc 日志与文件检查技巧
鸿蒙调试使用hdc命令，和 Android 的adb很像。排查上传问题时，我经常用下面几个命令：
# 查看应用缓存目录里有没有生成上传记录文件 hdc shell "ls -l /data/app/el2/100/base/{包名}/cache/upload_records/" # 抓取包含关键字的上传日志 hdc shell "hilog | grep upload"日志是解决“进度倒退”和“记录丢失”这类问题的核心手段。本地记录写了没有、服务端返回的 uploadedChunkIndexes 是什么，都在同一段时间里对照日志看，很快就能看出问题出在客户端还是服务端。
6. 实操总结与经验沉淀
这套方案做下来，我个人最大的体会是：在鸿蒙上做 Flutter 三方库适配，第一件事不是改代码，而是先判断这个库的“纯 Dart 程度”。chunked_uploader 能做到编译通过、核心逻辑能跑，是因为它没有绑定 Android/iOS 原生能力，但这种幸运不会每次都发生，遇到携带原生代码的库时，更高效的手段是找 HarmonyOS 版本实现或者用 platform channel 自己补一层。
第二个经验是把断点续传的可靠性完全押在客户端持久化上是不行的，一定要让服务端在 init 阶段返回已上传分片列表。因为用户清理缓存、重装应用、换设备登录，都会让本地记录不复存在，只有服务端的分片状态能兜底。
最后一个小建议：鸿蒙 Flutter 的版本升级一定要克制，不要看到新版本就升。把一个版本组合稳定跑通后，固定 Flutter SDK 版本和鸿蒙 SDK 版本，把升级当成一次独立的重构任务来做，而不是顺手操作。上传这种链路长、依赖多、用户感知强的功能，稳定比新潮重要得多。
