1. 项目概述断点续传这词儿听起来挺技术但说白了就是“接着下”。想象一下你正在用手机下载一个2个G的游戏更新包进度到90%了结果地铁进隧道网络断了。要是没有断点续传你只能从头再来流量和时间都白费了。但有了它网络恢复后下载会从90%的地方继续而不是0%。在Unity开发里尤其是资源热更新、大文件下载比如高清视频、音频包、AssetBundle这些场景断点续传几乎是刚需。Unity官方提供的网络请求组件是UnityWebRequest它功能强大但原生并不直接支持断点续传。很多开发者遇到大文件下载需求时要么自己从头造轮子要么找一些不太稳定的第三方插件踩坑无数。今天我就结合自己趟过的雷带你用最核心的UnityWebRequest配合一个自定义的DownloadHandler在5分钟内实现一个稳定、高效且代码清晰的断点续传方案。这个方案不依赖任何外部插件纯C#实现你拿到代码稍作调整就能用在自己的项目里。2. 核心原理与方案选型2.1 断点续传是如何工作的要自己实现首先得明白服务器和客户端是怎么“商量”着接着下载的。这背后依赖的是HTTP协议中的一个请求头Range。首次下载客户端发起一个普通的GET请求服务器返回整个文件。中断后续传客户端检查本地是否已存在一个部分下载的文件。如果存在就获取这个文件当前的大小例如已经下载了1024字节。客户端在发起新的UnityWebRequest时在请求头中设置Range: bytes1024-。这个头信息告诉服务器“我不要从头开始请从第1024个字节之后的数据开始发给我。”如果服务器支持断点续传大部分静态文件服务器都支持它会返回状态码206 Partial Content并只发送从指定字节开始的数据流。客户端收到数据后不是新建文件而是以“追加写入”的模式打开已有的部分文件将新数据接在后面。所以技术关键点就两个正确设置Range请求头和以追加模式处理收到的数据流。2.2 为什么选择自定义 DownloadHandlerScriptUnityWebRequest的结果处理主要由DownloadHandler负责。官方提供了几个内置的DownloadHandlerBuffer 将数据下载到内存中的一个字节数组。文件大了直接内存爆炸不适合。DownloadHandlerFile 直接下载到文件。但它有个“坑”它每次都会创建新文件如果文件已存在会覆盖。这意味着它无法直接用于追加数据实现续传需要更底层的控制。DownloadHandlerScript 这是一个抽象基类它把接收数据的控制权完全交给了开发者。当数据从网络流中接收到时Unity会回调它的ReceiveData方法传入数据块。我们可以在这个回调里自由决定如何处置这些数据——比如写入一个已打开的文件流。因此要实现将数据追加到现有文件DownloadHandlerScript是我们的不二之选。它给了我们所需的精细控制能力。2.3 方案优势与潜在坑点优势轻量无依赖 完全基于Unity官方API兼容性好无需管理第三方DLL。性能可控 数据缓冲区大小自己定避免频繁的IO操作。我们可以利用Unity在2017.2.1p1补丁中对大块数据传输的优化。功能可扩展 在回调函数里我们可以轻松加入下载速度计算、进度更新、暂停/继续等逻辑。需要留意的坑文件流管理 文件流FileStream必须正确打开和关闭。如果下载中途异常退出流没关闭可能导致文件被锁定或数据损坏。一定要在CompleteContent或Dispose中确保流被关闭。进度计算 续传时总进度应该是(本地已有大小 本次下载大小) / 文件总大小。文件总大小需要从服务器的响应头Content-Length或Content-Range中正确获取。版本差异 如搜索资料中提到的在Unity 2017.3.0之前的版本ReceiveData回调存在性能瓶颈每次最多只传约64KB数据。如果你的项目受限于旧版本需要留意下载速度上限。3. 核心代码实现与逐行解析接下来我们一步步构建这个名为DownloadHandlerFileRange的自定义类。我会把完整代码贴出来并逐段解释关键部分。3.1 类定义与初始化using UnityEngine.Networking; using System.IO; using System; public class DownloadHandlerFileRange : DownloadHandlerScript { private string _savePath; private FileStream _fileStream; private UnityWebRequest _request; private long _localFileSize 0; private long _totalFileSize 0; private long _currentDownloadedSize 0; /// summary /// 构造函数 /// /summary /// param namesavePath文件完整保存路径/param /// param namerequest关联的UnityWebRequest对象用于设置请求头/param public DownloadHandlerFileRange(string savePath, UnityWebRequest request) : base(new byte[1024 * 1024]) // 分配1MB的缓冲区 { _savePath savePath; _request request; // 1. 检查本地已存在文件的大小 if (File.Exists(_savePath)) { FileInfo fileInfo new FileInfo(_savePath); _localFileSize fileInfo.Length; _currentDownloadedSize _localFileSize; // 当前大小初始化为本地已有大小 } // 2. 以追加模式打开文件流准备写入 _fileStream new FileStream(_savePath, FileMode.Append, FileAccess.Write); // 3. 关键步骤设置Range请求头告诉服务器从哪里开始传 _request.SetRequestHeader(Range, $bytes{_localFileSize}-); } }关键点解析缓冲区大小base(new byte[1024 * 1024])我们传递了一个1MB1024*1024字节的缓冲区给父类。这个缓冲区是ReceiveData回调中data数组的预分配空间。1MB是一个经验值在性能和数据块处理频率间取得平衡。太小会导致IO操作过于频繁太大可能浪费内存。根据Unity的优化说明在较新版本中这个值基本是每次回调接收数据的上限。文件模式FileMode.Append这个参数至关重要。它确保如果文件存在写入操作将从文件末尾开始。这正是“续传”的核心。Range头bytes{_localFileSize}-这是实现断点续传的魔法指令。{_localFileSize}是本地已下载的字节数。-后面不写表示直到文件结束。例如已下载1024字节则头信息为Range: bytes1024-。3.2 接收数据与写入文件这是整个下载过程的核心循环数据在这里被写入磁盘。protected override bool ReceiveData(byte[] data, int dataLength) { // 防御性编程检查数据或请求是否异常 if (data null || dataLength 0 || _request.responseCode 400) { UnityEngine.Debug.LogError(接收数据失败或请求错误。); return false; // 返回false可能使下载中止 } try { // 将接收到的数据块写入文件流 _fileStream.Write(data, 0, dataLength); // 更新当前已下载的总字节数本地原有本次下载 _currentDownloadedSize dataLength; // 这里可以触发进度更新事件供UI显示 // OnProgressUpdated?.Invoke(GetProgress()); } catch (System.Exception e) { UnityEngine.Debug.LogError($写入文件时发生错误: {e.Message}); return false; // 发生异常中止下载 } return true; // 返回true表示继续接收下一个数据块 }关键点解析数据有效性检查 首先检查data是否为空或长度为0同时检查HTTP响应码是否表示错误4xx或5xx。这是必要的健壮性处理。写入操作_fileStream.Write(data, 0, dataLength)将缓冲区data中从0开始、长度为dataLength的有效数据写入文件。注意data数组的长度可能大于dataLength所以必须使用dataLength参数。错误处理 文件IO操作必须用try-catch包裹。磁盘空间不足、文件被占用等都可能导致写入失败我们需要捕获异常并妥善处理例如停止下载、通知用户而不是让游戏崩溃。返回值 返回true告诉Unity继续下载返回false会中止下载过程。我们在错误情况下返回false。3.3 获取文件总大小与进度计算进度计算需要知道文件的总大小。这个信息来自服务器的响应头。protected override void ReceiveContentLength(int contentLength) { // Unity传入的contentLength是int对于大于2GB的文件会溢出。优先从响应头获取。 string contentLengthHeader _request.GetResponseHeader(Content-Length); // 对于断点续传服务器可能用Content-Range头格式如bytes 1024-439857/439858 string contentRangeHeader _request.GetResponseHeader(Content-Range); long thisRequestFileSize 0; // 本次请求需要下载的部分的大小 if (!string.IsNullOrEmpty(contentRangeHeader)) { // 解析Content-Range头获取文件总大小 // 格式示例bytes 1024-439857/439858 try { string totalSizePart contentRangeHeader.Split(/)[1]; _totalFileSize long.Parse(totalSizePart); // 本次请求的大小可以通过解析范围计算也可以直接用contentLength如果没溢出 thisRequestFileSize contentLength 0 ? contentLength : (_totalFileSize - _localFileSize); } catch { /* 解析失败处理 */ } } else if (!string.IsNullOrEmpty(contentLengthHeader)) { // 如果没有Content-Range尝试用Content-Length try { thisRequestFileSize long.Parse(contentLengthHeader); // 总大小 本地已有大小 本次请求的大小 _totalFileSize _localFileSize thisRequestFileSize; } catch { /* 解析失败处理 */ } } else { // 如果响应头都没有只能使用Unity传过来的参数可能有溢出风险 thisRequestFileSize contentLength; _totalFileSize _localFileSize thisRequestFileSize; if (contentLength 0) { UnityEngine.Debug.LogWarning(无法从响应头获取文件大小进度计算可能不准。); } } // 进度更新事件可以在这里首次触发因为此时知道了总大小 // OnDownloadStarted?.Invoke(_totalFileSize); } protected override float GetProgress() { if (_totalFileSize 0) return 0.0f; // 进度 当前总下载大小 / 文件总大小 return Mathf.Clamp01((float)_currentDownloadedSize / _totalFileSize); }关键点解析ReceiveContentLength回调 当服务器返回响应头后Unity会调用此方法。参数contentLength是Unity解析出的内容长度但类型是int对于超过2GB的文件这个值会溢出变成负数。因此绝对不能直接信任这个参数。优先使用响应头 我们使用_request.GetResponseHeader主动获取Content-Length或Content-Range头信息。对于断点续传服务器更可能返回Content-Range其中包含了文件的总大小这是最可靠的信息源。进度计算逻辑GetProgress方法会在查询unityWebRequest.downloadProgress时被调用。计算公式是当前总下载量 / 文件总大小。注意_currentDownloadedSize在构造函数中初始化为本地已有大小并在ReceiveData中不断增加。注意除零保护 在GetProgress中如果_totalFileSize为0比如请求失败直接返回0避免运行时异常。3.4 资源清理与事件妥善管理资源尤其是FileStream防止内存泄漏和文件锁。public new void Dispose() { Cleanup(); base.Dispose(); // 调用基类清理 } protected override void CompleteContent() { // 下载完成时调用 Cleanup(); UnityEngine.Debug.Log($文件下载完成: {_savePath}); // OnDownloadCompleted?.Invoke(); } private void Cleanup() { if (_fileStream ! null) { _fileStream.Flush(); // 确保所有缓冲数据写入磁盘 _fileStream.Close(); _fileStream.Dispose(); _fileStream null; } } ~DownloadHandlerFileRange() { // 析构函数作为最后保障 Cleanup(); }关键点解析CompleteContent 当整个下载过程正常结束时Unity会调用此方法。这是关闭文件流的理想位置。Dispose 我们暴露一个新的Dispose方法供外部调用用于主动中止下载并清理资源。注意里面也调用了base.Dispose()。Cleanup方法 集中处理文件流关闭的逻辑。先Flush()确保缓冲区数据不丢失再关闭和释放。析构函数 作为最后的安全网防止因为忘记调用Dispose而导致文件流泄漏。但不要依赖它主动管理才是好习惯。3.5 如何使用这个类实现完核心类后使用起来非常简单直观。using UnityEngine; using System.Collections; public class FileDownloader : MonoBehaviour { public string url http://your-server.com/path/to/large-file.zip; public string localFilePath D:/Downloads/myfile.zip; IEnumerator StartDownloadWithResume() { // 1. 创建UnityWebRequest UnityWebRequest request new UnityWebRequest(url); request.method UnityWebRequest.kHttpVerbGET; // 默认为GET可省略 // 2. 创建我们的自定义DownloadHandler并关联request DownloadHandlerFileRange downloadHandler new DownloadHandlerFileRange(localFilePath, request); request.downloadHandler downloadHandler; // 3. (可选) 添加进度监控 // StartCoroutine(MonitorProgress(downloadHandler)); // 4. 发送请求 yield return request.SendWebRequest(); // 5. 处理结果 if (request.result UnityWebRequest.Result.Success) { Debug.Log(下载成功); } else { Debug.LogError($下载失败: {request.error}); // 失败后文件会保留已下载的部分。下次用相同路径创建DownloadHandlerFileRange时会自动续传。 } // 6. 清理请求自定义的handler会在CompleteContent中自动清理流 request.Dispose(); } IEnumerator MonitorProgress(DownloadHandlerFileRange handler) { while(!handler.isDone) // 可以添加一个isDone属性到handler中 { Debug.Log($下载进度: {handler.GetProgress():P2}); yield return new WaitForSeconds(0.5f); // 每0.5秒更新一次 } } }4. 高级功能与性能优化基础功能完成后我们可以让它更强大、更好用。4.1 下载速度计算在ReceiveData回调中我们可以加入简单的速度计算逻辑。private float _lastUpdateTime; private long _lastDataSize; public float DownloadSpeedKBps { get; private set; } protected override bool ReceiveData(byte[] data, int dataLength) { // ... 原有的数据写入逻辑 ... _currentDownloadedSize dataLength; // 计算下载速度每秒 float currentTime Time.time; if (currentTime - _lastUpdateTime 0.5f) // 每0.5秒计算一次避免UI更新太频繁 { float deltaTime currentTime - _lastUpdateTime; long deltaData _currentDownloadedSize - _lastDataSize; DownloadSpeedKBps (deltaData / 1024f) / deltaTime; // 计算KB/s _lastUpdateTime currentTime; _lastDataSize _currentDownloadedSize; // 触发速度更新事件 // OnSpeedUpdated?.Invoke(DownloadSpeedKBps); } // ... 返回true ... }4.2 实现暂停与继续UnityWebRequest本身没有暂停API但我们可以通过Dispose来中止利用断点续传机制来实现“暂停”。public class PausableDownloader : MonoBehaviour { private UnityWebRequest _currentRequest; private DownloadHandlerFileRange _currentHandler; private string _url; private string _savePath; private Coroutine _downloadCoroutine; public void StartOrResumeDownload(string url, string path) { _url url; _savePath path; if (_downloadCoroutine ! null) StopCoroutine(_downloadCoroutine); _downloadCoroutine StartCoroutine(DownloadCoroutine()); } public void PauseDownload() { if (_currentRequest ! null) { // 中止请求。DownloadHandlerFileRange的CompleteContent不会被调用 // 但它的析构函数或我们主动Dispose会关闭文件流确保数据已写入。 _currentRequest.Dispose(); _currentRequest null; _currentHandler null; Debug.Log(下载已暂停。); } } IEnumerator DownloadCoroutine() { // 每次启动协程都会基于现有的_partial文件创建新的请求实现续传 _currentRequest new UnityWebRequest(_url); _currentHandler new DownloadHandlerFileRange(_savePath, _currentRequest); _currentRequest.downloadHandler _currentHandler; yield return _currentRequest.SendWebRequest(); // ... 处理完成 ... } }注意 暂停后文件流必须被正确关闭否则已下载的数据可能还在缓冲区未写入磁盘。我们的Cleanup逻辑在Dispose或析构中调用保证了这一点。4.3 多线程与主线程回调ReceiveData回调可能在非主线程执行。如果我们需要在其中更新UI如进度条、速度显示必须将数据派发到主线程。// 在自定义Handler中定义事件 public event Actionlong, float OnProgressAndSpeedUpdated; // 总大小进度 protected override bool ReceiveData(byte[] data, int dataLength) { // ... 写入数据和计算速度 ... // 触发事件传递数据 OnProgressAndSpeedUpdated?.Invoke(_totalFileSize, GetProgress()); return true; } // 在MonoBehaviour中使用时 void SetupHandler(DownloadHandlerFileRange handler) { handler.OnProgressAndSpeedUpdated (totalSize, progress) { // 使用MainThreadDispatcher或直接检查是否在主线程 #if UNITY_EDITOR || !UNITY_WEBGL // WebGL是单线程 if (!UnityEngine.Object.FindObjectOfTypeUnityEngine.EventSystems.EventSystem()) return; // 简单判断 #endif // 更新UI Text或Slider progressText.text ${progress:P2}; speedText.text ${handler.DownloadSpeedKBps:F2} KB/s; }; }对于复杂的项目建议使用一个专门的MainThreadDispatcher单例来安全地排队和执行主线程任务。5. 常见问题排查与实战技巧在实际项目中集成时你可能会遇到下面这些问题。这里我整理了排查思路和解决方案。5.1 服务器返回状态码416或200而不是206问题现象 设置了Range头但服务器返回416 Range Not Satisfiable或200 OK返回了整个文件。排查思路检查URL和文件 确保你请求的资源支持断点续传。不是所有服务器或所有类型的资源都支持。检查Range头格式 使用浏览器的开发者工具或Postman等工具模拟你的请求查看发送的Range头是否正确。格式必须是bytesstart-或bytesstart-end。检查本地文件大小 在设置Range头前打印_localFileSize的值。如果文件不存在或大小为0Range: bytes0-是有效的但有些服务器可能对0点开始的处理不同。服务器配置 对于自己搭建的服务器如Nginx, Apache需要确保配置了支持断点续传。例如Nginx默认是支持的但某些自定义的CDN或后端服务可能需要额外配置。解决方案如果服务器返回416通常意味着请求的范围无效比如请求的起始点超过了文件大小。这时应该删除本地残破文件重新开始下载。如果服务器总是返回200说明它不支持或不理会Range头。你的代码依然能工作但会变成覆盖式下载无法实现续传。你需要为这类资源准备一个降级方案比如提示用户或使用普通下载方式。5.2 下载进度条“回退”或卡在某个点问题现象 进度条在下载过程中突然跳回较低百分比或者长时间不动。排查思路进度计算逻辑 检查GetProgress()方法。确保_totalFileSize在ReceiveContentLength中被正确赋值且_currentDownloadedSize是从_localFileSize开始累加的。文件总大小获取错误 如果_totalFileSize获取错误例如解析响应头失败使用了溢出的contentLength会导致进度分母错误。添加日志打印出从响应头解析出的_totalFileSize值。网络波动与重连 网络中断后UnityWebRequest可能会自动重试或进入错误状态。如果重连后创建了新的请求但进度回调没更新可能导致UI“卡住”。确保每次创建新的下载器时UI进度监听都绑定到新的实例。解决方案在ReceiveContentLength中加强错误处理如果解析失败可以尝试发起一个HEAD请求先获取文件总大小。进度更新事件传递_currentDownloadedSize和_totalFileSize两个原始值让UI层自己计算百分比避免因_totalFileSize为0导致除零错误。5.3 大文件下载2GB异常问题现象 下载大文件时进度异常、文件损坏或直接崩溃。排查思路int32溢出 这是最常见的问题。回顾ReceiveContentLength(int contentLength)Unity传入的contentLength是int类型最大值约21亿2.14GB。超过这个值会溢出变成负数。我们的代码已经通过优先读取响应头Content-Length(long) 来规避此问题这是关键。文件流位置 确保FileStream始终以FileMode.Append模式打开这样Position会自动指向文件末尾无需手动设置。内存与缓冲区 1MB的缓冲区对于大文件下载是合适的。避免在ReceiveData中分配新的字节数组或进行耗时的非IO操作。解决方案务必使用我们提供的、从响应头获取long类型文件大小的逻辑。在写入文件后可以定期调用_fileStream.Flush()以确保数据落盘但频繁刷新会影响性能通常在下载完成或暂停时刷新一次即可。5.4 文件下载完成后校验MD5/SHA1为了保证下载文件的完整性尤其是在不稳定的网络环境下添加校验是很有必要的。public IEnumerator VerifyFile(string filePath, string expectedHash) { // 注意计算大文件哈希是CPU密集型操作应在后台线程进行 yield return new WaitForBackgroundThread(); // 需要使用Unity的特定方式或线程池 string calculatedHash CalculateFileHash(filePath, MD5); // 实现你的哈希计算函数 bool isValid string.Equals(calculatedHash, expectedHash, StringComparison.OrdinalIgnoreCase); yield return new WaitForMainThread(); // 回到主线程更新结果 if (isValid) { Debug.Log(文件校验通过); } else { Debug.LogError(文件校验失败可能已损坏。); File.Delete(filePath); // 删除损坏文件 } }技巧 服务器端应在提供文件下载链接时同时提供文件的哈希值如MD5、SHA1。客户端下载完成后进行比对。5.5 实战技巧小结日志是救星 在ReceiveContentLength、ReceiveData开始和结束、CompleteContent、Dispose等关键节点添加详细的日志Debug.Log记录文件大小、进度、速度、响应码。出问题时这些日志是第一时间定位的关键。异常处理要周全 网络请求、文件IO处处是坑。用try-catch包裹所有可能出错的操作并在catch块中提供有意义的错误信息和恢复逻辑如清理资源、通知用户。提供取消接口 除了暂停还应该提供一个彻底的取消接口用于删除未完成的残破文件。考虑电量与性能 在移动设备上长时间大文件下载是耗电大户。可以考虑在应用进入后台或锁屏时暂停下载回到前台时再续传。测试测试再测试 在各种网络条件下测试Wi-Fi、4G、弱网模拟。测试正常中断用户暂停、异常中断杀进程、断网后的恢复情况。测试不同大小文件小文件、大文件、超过2G文件的下载。这个基于UnityWebRequest和自定义DownloadHandlerScript的断点续传方案核心代码不到200行但涵盖了从原理到实践从基础功能到异常处理的大部分要点。它足够轻量可以方便地集成到任何Unity项目中也足够健壮能够应对真实环境中的各种挑战。希望这份详细的拆解和代码能帮你彻底搞定Unity中的大文件下载难题。