1. 项目概述：为什么Unity开发者需要掌握断点续传？

在Unity项目开发中，尤其是涉及到资源热更新、大文件下载、或者构建一个需要持续下载内容的网络游戏时，我们经常会遇到一个头疼的问题：网络不稳定。想象一下，你的玩家正在下载一个500MB的高清资源包，进度到了99%，突然网络波动了一下，或者手机切了个Wi-Fi，下载中断了。如果从头开始，玩家体验会非常糟糕，不仅浪费流量和时间，更可能直接导致用户流失。

这就是“断点续传”技术要解决的核心痛点。它允许我们从文件已经下载完成的部分继续下载，而不是重新开始。对于Unity开发者而言，这不仅仅是提升用户体验的“加分项”，在移动网络环境复杂、用户设备存储空间宝贵的今天，它几乎是中大型网络应用或游戏的“标配”能力。无论是更新游戏补丁、下载动态资源包，还是实现一个内容分发系统，断点续传都是保障服务可靠性和用户留存率的关键技术。

我经历过不止一个项目，因为早期忽略了断点续传，在测试阶段就被网络环境模拟测试“教做人”。后来花大力气重构下载模块，才把数据挽回。所以，今天我想结合在Unity中的实际踩坑经验，把断点续传从原理到实践，再到那些容易忽略的细节，系统地梳理一遍。无论你是刚接触网络模块的新手，还是想优化现有方案的老手，希望这篇内容都能给你带来直接的帮助。

2. 核心原理与方案选型：不止是“接着下”那么简单

断点续传听起来简单，但实现一个健壮、高效的方案，需要考虑的细节远超“记住已下载的字节数”这么简单。我们先来拆解它的核心工作原理，并分析在Unity生态下的几种主流实现路径。

2.1 HTTP断点续传的工作原理

断点续传的标准实现依赖于HTTP协议规范中的两个请求头：Range和Content-Range。

• Range： 由客户端（我们的Unity应用）在请求时发送，告诉服务器：“我只需要文件从第A字节到第B字节的部分”。例如，Range: bytes=1024-2047表示请求文件的第1024到2047字节（共1024字节）。如果只想从某个点开始下载到文件末尾，可以写为Range: bytes=1024-。
• Content-Range： 由服务器在响应时返回，告诉客户端：“我这次给你的内容，属于整个文件的哪个范围”。例如，对于上面的请求，一个合法的响应头可能是Content-Range: bytes 1024-2047/123456，表示本次返回的是总大小为123456字节的文件中，1024到2047字节的部分。

整个流程可以概括为：

1. 首次或中断后： 检查本地是否存在已下载的部分文件（我们称之为“临时文件”或“缓存文件”），并获取其当前大小，假设为downloadedSize。
2. 发起续传请求： 使用UnityWebRequest或HttpClient发起一个GET请求，并在请求头中设置Range: bytes=<downloadedSize>-。
3. 服务器处理： 支持断点续传的服务器会识别Range头，并返回对应的文件片段以及Content-Range响应头。如果服务器不支持，通常会忽略Range头，返回整个文件（状态码200 OK），这时客户端需要回退到普通下载模式或报错。
4. 客户端拼接： 客户端将新下载的数据流，以追加（Append）的方式写入到本地临时文件的末尾。
5. 完成与验证： 当下载的总大小等于服务器返回的完整文件大小时（可通过Content-Range中的总量或首次请求的Content-Length得知），下载完成。最后，可以将临时文件重命名为最终文件。

注意： 一个关键前提是，服务器必须支持断点续传。大多数标准的静态文件服务器（如Nginx, Apache, CDN服务）都默认支持。但在对接一些特殊的API接口时，需要确认其支持情况。

2.2 Unity中的技术方案选型

在Unity中实现断点续传，我们主要有三种路径，各有优劣：

方案一：基于 UnityWebRequest (UWR)这是Unity官方推荐和内置的网络方案，在2017版本后逐步取代旧的WWW API。

• 优点： 与Unity引擎集成度高，在主线程上使用方便，自动处理了一些平台差异（如WebGL）。可以直接设置请求头。
• 缺点： 在下载大文件时，如果全部数据先存入内存再写入磁盘，有内存压力。虽然可以通过DownloadHandlerFile流式写入文件，但断点续传时需要自己管理文件指针和Range头，且DownloadHandlerFile在续传时覆盖而非追加写入，需要额外处理。
• 适用场景： 中小型文件下载，或对跨平台（尤其是WebGL）兼容性要求极高的项目。

方案二：基于 .NET 的 HttpClient (或 WebClient)在支持 .NET 4.x 或 .NET Standard 2.0/2.1 的Unity版本中，可以直接使用System.Net.Http.HttpClient。

• 优点： 功能强大、控制粒度细，是标准的C#网络库。可以非常方便地设置请求头、读取响应头，并利用Stream实现高效的流式下载和文件追加写入。
• 缺点： 在部分平台（如较旧的WebGL、某些游戏主机平台）上可能受限或行为不一致。需要开发者处理更多底层细节，如异步任务（Task）与Unity协程（Coroutine）的协作。
• 适用场景： PC、移动端（iOS/Android）项目，需要精细控制下载过程、实现多线程下载或复杂重试逻辑的中大型项目。

方案三：使用第三方插件或库市面上有一些成熟的Unity资源管理或网络插件，如Best HTTP/2,ETNetwork等，它们通常封装了更完善的断点续传、多线程下载、队列管理等功能。

• 优点： 开箱即用，节省开发时间，通常经过优化和大量测试。
• 缺点： 引入额外依赖和成本（如果是付费插件），自定义程度可能受限。
• 适用场景： 追求快速开发，且项目预算允许；或者对网络模块的稳定性和功能丰富度有极高要求。

我的选择与建议：对于大多数自研项目，我倾向于方案二（HttpClient）为主，方案一（UnityWebRequest）为辅的策略。核心下载逻辑使用HttpClient，因为它对断点续传的支持最直接、性能最好。而对于WebGL平台，则回退到使用UnityWebRequest的特殊处理。这种混合方案能兼顾性能、控制力和平台兼容性。下文也将以HttpClient为核心进行实践讲解。

3. 核心实现细节与实操要点

理解了原理和选型，我们开始动手实现。一个完整的断点续传模块，不仅仅是下载，还包括文件状态管理、错误重试、进度计算等。我们分步拆解。

3.1 文件状态管理与临时文件策略

在开始下载前，我们必须能准确地知道“已经下载了多少”。这涉及到本地文件系统的操作。

1. 临时文件与最终文件不要直接下载到最终目标文件。正确的做法是：

• 临时文件： 下载过程中的文件，例如[file_name].download或[file_name].tmp。所有下载的数据都写入此文件。
• 最终文件： 下载完成并验证后，将临时文件重命名（Move）得到的目标文件，如[file_name].dat。

这样做的好处是：

• 原子性操作： 重命名操作在大多数操作系统中是原子的。即使应用在重命名过程中崩溃，也只会存在一个完整的临时文件或不完整的临时文件，不会损坏最终文件。
• 防止脏读： 其他线程或进程在下载过程中读取最终文件时，不会读到不完整的半成品。

2. 记录下载状态我们需要一个轻量级的方式来记录某个文件的下载状态。通常有两种方式：

• 隐式记录： 直接检查临时文件的大小（FileInfo.Length），将其视为已下载的字节数。这是最简单的方式，前提是临时文件只由本下载进程写入。
• 显式记录： 额外使用一个状态文件（如[file_name].info或统一的数据库）来记录文件的URL、总大小、已下载大小、MD5校验值等。这种方式更强大，可以记录更多元数据，便于管理复杂的下载队列和校验，但实现也更复杂。

对于大多数单任务或简单队列的场景，隐式记录（检查临时文件大小）已经足够。我们采用这种方式。

实操心得：文件路径处理Unity中获取可读写路径要使用Application.persistentDataPath。不同平台这个路径差异很大。构建临时文件路径时，要确保目录存在。

string persistentPath = Application.persistentDataPath; string tempDirectory = Path.Combine(persistentPath, "Downloads/Temp"); // 确保目录存在 if (!Directory.Exists(tempDirectory)) { Directory.CreateDirectory(tempDirectory); } string tempFilePath = Path.Combine(tempDirectory, $"{fileName}.download");

3.2 使用HttpClient实现核心下载

这是最关键的环节。我们将实现一个支持暂停、继续、进度报告和错误处理的核心下载方法。

using System; using System.IO; using System.Net.Http; using System.Threading; using System.Threading.Tasks; using UnityEngine; public class ResumableDownloader { private HttpClient _httpClient; private CancellationTokenSource _cancellationTokenSource; public ResumableDownloader() { _httpClient = new HttpClient(); // 设置一个合理的超时时间，或者根据网络类型动态设置 _httpClient.Timeout = TimeSpan.FromMinutes(30); } public async Task DownloadFileAsync( string url, string localFilePath, string tempFilePath, IProgress<DownloadProgress> progressReporter, CancellationToken cancellationToken = default) { long existingLength = 0; FileStream fileStream = null; // 1. 检查并打开临时文件 if (File.Exists(tempFilePath)) { FileInfo fileInfo = new FileInfo(tempFilePath); existingLength = fileInfo.Length; // 以追加模式打开文件流 fileStream = new FileStream(tempFilePath, FileMode.OpenOrCreate, FileAccess.Write, FileShare.None); fileStream.Seek(existingLength, SeekOrigin.Begin); // 将指针移动到文件末尾 } else { // 确保目录存在 Directory.CreateDirectory(Path.GetDirectoryName(tempFilePath)); fileStream = new FileStream(tempFilePath, FileMode.Create, FileAccess.Write, FileShare.None); } try { using (var request = new HttpRequestMessage(HttpMethod.Get, url)) { // 2. 如果已有部分文件，设置Range请求头 if (existingLength > 0) { request.Headers.Range = new System.Net.Http.Headers.RangeHeaderValue(existingLength, null); } using (var response = await _httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken)) { response.EnsureSuccessStatusCode(); // 确保2xx状态码 // 3. 处理响应 long? totalBytes = response.Content.Headers.ContentLength; // 注意：续传时，这是剩余部分的大小 long totalBytesToRead = totalBytes ?? -1; long totalBytesRead = existingLength; // 如果是续传且服务器支持，响应状态码应为206（Partial Content），而不是200 if (existingLength > 0 && response.StatusCode != System.Net.HttpStatusCode.PartialContent) { // 服务器可能不支持断点续传，这里可以抛出异常或回退到普通下载（需先清空文件） Debug.LogWarning($"服务器可能不支持断点续传于 {url}。状态码：{response.StatusCode}"); // 简单处理：关闭流，删除临时文件，重新开始（非最佳实践，仅示例） fileStream.Close(); File.Delete(tempFilePath); await DownloadFileAsync(url, localFilePath, tempFilePath, progressReporter, cancellationToken); return; } // 4. 计算完整文件总大小（用于进度计算） long fullFileLength = existingLength; if (response.Headers.AcceptRanges != null && response.Content.Headers.ContentRange != null) { // 从Content-Range头获取完整大小，例如 "bytes 1024-2047/123456" if (response.Content.Headers.ContentRange.Length.HasValue) { fullFileLength = response.Content.Headers.ContentRange.Length.Value; } } else if (existingLength == 0 && totalBytesToRead > 0) { // 首次下载，总大小就是Content-Length fullFileLength = totalBytesToRead; } // 5. 从响应流读取并写入文件流 using (var contentStream = await response.Content.ReadAsStreamAsync()) { var buffer = new byte[81920]; // 80KB缓冲区，可根据情况调整 int bytesRead; while ((bytesRead = await contentStream.ReadAsync(buffer, 0, buffer.Length, cancellationToken)) > 0) { await fileStream.WriteAsync(buffer, 0, bytesRead, cancellationToken); totalBytesRead += bytesRead; // 6. 报告进度 if (progressReporter != null && fullFileLength > 0) { var progress = new DownloadProgress { BytesDownloaded = totalBytesRead, TotalBytes = fullFileLength, ProgressPercentage = (float)totalBytesRead / fullFileLength }; progressReporter.Report(progress); } } } } } // 7. 下载完成，关闭流，重命名文件 fileStream.Close(); if (File.Exists(localFilePath)) { File.Delete(localFilePath); // 如果目标文件已存在，先删除 } File.Move(tempFilePath, localFilePath); Debug.Log($"文件下载并保存至: {localFilePath}"); } catch (Exception ex) { fileStream?.Close(); // 这里可以记录异常，或者将临时文件保留以供下次续传 Debug.LogError($"下载失败: {ex.Message}"); throw; // 或者返回一个失败状态 } } } // 进度报告结构体 public struct DownloadProgress { public long BytesDownloaded; public long TotalBytes; public float ProgressPercentage; }

代码关键点解析：

1. 文件流模式： 使用FileMode.OpenOrCreate和FileStream.Seek来实现追加写入，这是续传的核心。
2. Range头设置：request.Headers.Range = new RangeHeaderValue(existingLength, null);设置了从existingLength到结尾的请求范围。
3. 状态码检查： 对于续传请求，成功的响应状态码应该是206 Partial Content，而不是200 OK。收到200可能意味着服务器不支持断点续传，我们的代码给出了一个简单的回退策略（删除重下），但在生产环境中，你可能需要更优雅的处理，比如转为普通下载模式并通知用户。
4. 进度计算： 进度计算的分母应该是完整文件的总大小，而不是本次响应体的大小。总大小可以从首次请求的Content-Length或续传响应中的Content-Range头里解析出来。
5. 缓冲区大小：buffer大小设置为80KB是一个经验值，过小会增加I/O次数，过大会占用更多内存。可以根据目标平台（如移动端内存敏感）进行调整。
6. 异步与取消： 全程使用async/await和CancellationToken，使得下载可以被随时取消，并且不会阻塞主线程。这对于Unity中保持游戏流畅响应至关重要。

3.3 与Unity引擎的集成：进度更新与生命周期

上面的DownloadFileAsync是一个纯粹的 .NET 异步方法。我们需要将它安全地集成到Unity的 MonoBehaviour 生命周期中，并更新UI进度条。

关键问题：Unity主线程与多线程HttpClient的异步操作默认会在线程池线程上执行。而Unity中几乎所有引擎API（如设置UI Text、操作GameObject）都必须在主线程调用。因此，我们不能在异步方法中直接更新UI。

解决方案：使用IProgress<T>回调与UnityMainThreadDispatcher我们上面代码中已经使用了IProgress<DownloadProgress>接口。我们需要在主线程创建一个Progress<T>实例，并将其传入下载方法。

using System; using UnityEngine; using UnityEngine.UI; public class DownloadManager : MonoBehaviour { public string downloadUrl = "http://your-server.com/largefile.zip"; public string localFileName = "downloadedFile.zip"; public Slider progressSlider; public Text progressText; public Button startButton; public Button pauseButton; private ResumableDownloader _downloader; private CancellationTokenSource _cancellationTokenSource; private string _tempFilePath; void Start() { _downloader = new ResumableDownloader(); string persistentPath = Application.persistentDataPath; _tempFilePath = Path.Combine(persistentPath, "TempDownloads", localFileName + ".download"); startButton.onClick.AddListener(StartDownload); pauseButton.onClick.AddListener(PauseDownload); pauseButton.interactable = false; } private async void StartDownload() { startButton.interactable = false; pauseButton.interactable = true; _cancellationTokenSource = new CancellationTokenSource(); // 创建一个Progress实例，其回调会在创建它的同步上下文（这里是主线程）执行 var progress = new Progress<DownloadProgress>(ReportProgress); string finalPath = Path.Combine(Application.persistentDataPath, localFileName); try { await _downloader.DownloadFileAsync( downloadUrl, finalPath, _tempFilePath, progress, _cancellationTokenSource.Token); Debug.Log("下载完成！"); } catch (OperationCanceledException) { Debug.Log("下载已被取消。"); // 临时文件 _tempFilePath 已被保留，下次点击开始会自动续传 } catch (Exception ex) { Debug.LogError($"下载出错: {ex.Message}"); // 处理其他错误，如网络错误、文件写入错误等 } finally { ResetUI(); } } private void ReportProgress(DownloadProgress progress) { // 这个回调是在Unity主线程执行的，可以安全操作UI if (progressSlider != null) { progressSlider.value = progress.ProgressPercentage; } if (progressText != null) { progressText.text = $"{(progress.ProgressPercentage * 100):F1}% ({progress.BytesDownloaded}/{progress.TotalBytes} bytes)"; } } private void PauseDownload() { _cancellationTokenSource?.Cancel(); pauseButton.interactable = false; Debug.Log("已发送取消请求，正在暂停..."); // 注意：Cancel()是请求取消，下载循环会在下一个ReadAsync/WriteAsync时收到取消信号并退出。 } private void ResetUI() { startButton.interactable = true; pauseButton.interactable = false; // 可以选择不清空进度条，以显示最后的状态 } void OnDestroy() { _cancellationTokenSource?.Cancel(); // 组件销毁时取消正在进行的下载 _downloader?.Dispose(); // 清理HttpClient } }

实操心得：异步方法与Unity生命周期

• async void方法： 在Unity中，只有事件处理程序（如按钮点击）可以使用async void。要小心处理这类方法中的异常，因为未捕获的异常会导致应用崩溃。我们使用try-catch将其包裹。
• 资源清理：HttpClient和CancellationTokenSource都实现了IDisposable。务必在OnDestroy或合适的时机进行清理，防止内存泄漏。
• 临时文件管理： 在应用启动时，可以考虑清理过期的临时文件（例如创建时间超过一周的），避免占用用户磁盘空间。

4. 高级话题与性能优化

实现基础功能后，我们可以进一步探讨如何让它更健壮、更高效。

4.1 分块下载与多线程加速

对于超大型文件（比如数GB的高清视频资源），单线程下载可能速度达到瓶颈。我们可以将文件分成多个块（Chunk），每个块独立进行断点续传，最后合并。这不仅能利用多线程加速，还能提高对不稳定网络的容错性（一个块失败只需重试该块）。

基本思路：

1. 首次请求获取文件总大小（Content-Length）。
2. 将文件分成N个大小相近的块（例如，每个块5MB）。
3. 为每个块创建独立的临时文件（如file.part0,file.part1）或在一个文件中记录各块的偏移量。
4. 使用多个HttpClient（或复用同一个）并发下载不同的块，每个块都使用自己的Range头。
5. 所有块下载完成后，按顺序将它们合并成最终文件。

挑战与注意事项：

• 服务器支持： 需要服务器支持Range请求。
• 连接数限制： 并发连接数不宜过高，以免被服务器拒绝或对服务器造成压力。通常4-8个并发是合理的。
• 磁盘I/O： 多线程写入可能会造成磁盘I/O竞争，在机械硬盘上可能成为瓶颈。需要测试和权衡。
• 复杂性： 分块下载大大增加了状态管理、错误处理和文件合并的复杂度。
• 进度计算： 总进度需要汇总所有分块的进度。

除非你的应用场景确实有下载超大文件的强需求，否则单线程断点续传在大多数情况下已经足够。引入分块下载会带来显著的实现和维护成本。

4.2 下载完整性校验（MD5/SHA）

网络传输可能出错，磁盘写入也可能出错。为了确保下载的文件百分百正确，必须在下载完成后进行校验。

常见做法：

1. 服务器在提供文件下载链接时，同时提供该文件的哈希值（通常是MD5或SHA256）。
2. 客户端下载完成后，计算本地文件的哈希值。
3. 比对两个哈希值。如果一致，则文件完整；如果不一致，则删除损坏的文件，重新下载或仅重下载出错的部分（需要更复杂的校验机制，如分块哈希）。

在Unity中计算文件哈希：

using System.IO; using System.Security.Cryptography; using System.Text; public string CalculateFileMD5(string filePath) { using (var md5 = MD5.Create()) { using (var stream = File.OpenRead(filePath)) { var hashBytes = md5.ComputeHash(stream); return BitConverter.ToString(hashBytes).Replace("-", "").ToLowerInvariant(); } } } // 使用 string localFileHash = CalculateFileMD5(finalFilePath); if (localFileHash == serverProvidedMD5) { Debug.Log("文件校验通过！"); } else { Debug.LogError("文件校验失败，可能已损坏！"); File.Delete(finalFilePath); }

实操心得：校验的时机校验计算是CPU和I/O密集型操作，对于大文件可能耗时数秒。建议在后台线程进行，避免卡住主线程。可以在下载完成的回调中启动一个Task.Run来计算哈希，然后通过主线程调度器回调UI。

4.3 网络状态监听与自动重试

移动设备的网络环境变幻莫测。一个健壮的下载器需要能感知网络变化并做出响应。

• 网络状态检查： 在开始下载或重试前，可以使用Application.internetReachability（Unity API）或NetworkReachability来粗略判断网络是否可用。但注意，这只能判断潜在连接性，不能判断实际可达性。
• 自动重试机制： 当下载过程中抛出异常（如HttpRequestException,IOException）时，不应立即失败。可以实现一个带指数退避的重试逻辑。

  int maxRetries = 3; int retryDelay = 2; // 秒 for (int i = 0; i < maxRetries; i++) { try { await DownloadFileAsync(...); break; // 成功则跳出循环 } catch (Exception ex) when (IsTransientError(ex)) // 判断是否为可重试的临时错误 { if (i == maxRetries - 1) throw; // 最后一次重试后仍失败，抛出异常 Debug.LogWarning($"下载失败，{retryDelay}秒后重试 ({i+1}/{maxRetries})。错误: {ex.Message}"); await Task.Delay(retryDelay * 1000); retryDelay *= 2; // 指数退避 } }

• 暂停与恢复的联动： 当网络从无到有恢复时，可以尝试自动恢复被暂停的下载任务。这需要你将下载任务（URL、本地路径、临时路径等）和管理状态（是否暂停、已下载大小等）持久化存储起来。

5. 常见问题、排查技巧与实战避坑指南

在实际项目中，我踩过不少坑。这里总结一些典型问题和解决方法。

5.1 问题排查速查表

5.2 实战避坑心得

1. 关于HttpClient的单例使用： 通常建议将HttpClient实例化为单例并重复使用，而不是每次请求都new一个。因为HttpClient内部会管理连接池，复用可以提高性能。但在Unity中，如果游戏生命周期很长，需要注意HttpClient的默认DNS刷新时间等问题。一个折中的方案是为下载管理器创建一个长期存在的HttpClient实例。

2. 异步与Unity协程的抉择： 在新的Unity版本（支持C# async/await）中，对于纯粹的I/O密集型操作如下载，优先使用async/await，代码更清晰，性能也更好。避免在下载循环中使用yield return null或UnityWebRequest.SendWebRequest()的协程方式，它们会产生大量的帧调度开销。协程更适合需要每帧更新的游戏逻辑。

3. 后台下载与应用焦点： 在移动平台，当应用切换到后台时，操作系统可能会限制或挂起网络活动。对于希望支持后台下载的应用，需要研究各平台的后台任务机制（如iOS的Background Tasks， Android的Foreground Service或WorkManager），这超出了标准Unity网络API的范围，通常需要平台原生插件。

4. 流量与电量考虑： 频繁的网络请求和重试会消耗用户流量和电量。在设计重试策略和分块大小时要有所权衡。对于移动端，可以在Wi-Fi环境下才允许下载大文件，或者提供“仅Wi-Fi下载”的选项。

5. 测试，测试，再测试： 断点续传的复杂性在于其状态性。必须进行大量测试：

   • 模拟网络中断： 在下载过程中手动切换飞行模式、切换Wi-Fi/4G。
   • 模拟应用退出： 在下载过程中强制关闭应用，再重新启动，检查是否能续传。
   • 模拟服务器错误： 使用Mock服务器或工具模拟服务器返回404、500、206、200等不同状态码。
   • 边界测试： 测试空文件、极小文件、超大文件的下载和续传。

断点续传是一个典型的“细节决定成败”的功能。它本身不复杂，但要把所有边界情况都处理好，需要严谨的设计和充分的测试。从我的经验来看，在项目早期就引入一个健壮的下载管理模块，远比后期在用户投诉的压力下匆忙修补要划算得多。希望这篇近万字的详解，能帮你构建起属于自己的、稳定可靠的Unity断点续传方案。