1. 项目概述与核心价值

在Unity项目开发中，资源下载是一个绕不开的环节。无论是热更新资源包、动态加载的AB包，还是游戏内的视频、音频素材，动辄几百兆甚至上G的大小是家常便饭。如果你还在用UnityWebRequest或WWW的简单Get方法，遇到网络波动或者用户中途退出，下次只能从头再来，那种体验对玩家来说简直是灾难。更头疼的是，如果下载大文件时内存飙升，导致游戏卡顿甚至闪退，问题就更加严重了。

这个项目要解决的，就是这两个核心痛点：实现一个稳定、高效且内存友好的断点续传下载器，并附带直观的进度显示。它不仅仅是封装一个API调用，而是深入到UnityWebRequest的DownloadHandlerScript底层，通过预分配固定缓冲区的方式，彻底杜绝因下载大文件引发的GC（垃圾回收）压力和内存泄漏风险。同时，利用HTTP协议的Range头部，实现精准的断点续传逻辑。我把自己在实际项目中踩过的坑、优化过的细节，以及完整的、可运行的C#源码都整理了出来，放在了GitHub上。无论你是想在自己的项目中直接集成这个模块，还是想深入学习Unity网络请求与文件IO的高阶用法，这篇文章都能给你一份清晰的“地图”。

2. 核心原理与方案选型

2.1 为什么是断点续传 + 固定缓冲区？

在讨论实现之前，我们必须先搞清楚为什么要采用这套组合方案。普通的下载流程是“请求-接收-写入”，如果中断，本地文件可能处于不完整状态，且服务器不知道你下载了多少，只能重头开始。断点续传的精髓在于状态记录与恢复。客户端需要知道自己已经下载了多少（通过读取本地已存在文件的大小），并告诉服务器：“请从第N个字节之后的数据开始发给我”。这就是HTTP协议中Range: bytes=N-请求头的作用。

然而，仅仅实现断点续传还不够。Unity中常见的错误做法是：接收到的数据先全部缓存在内存（比如存放在downloadHandler.data这个字节数组里），等全部下载完再一次性写入文件。对于小文件没问题，但对于大文件，这意味着Unity的托管堆（Managed Heap）会瞬间分配一个和文件一样大的内存块。在移动平台，这极易触发GC，导致帧率卡顿；更糟糕的是，Mono内存一旦被撑高，即使后面释放了引用，内存占用也未必能立刻回落，存在内存泄漏的风险，多次下载大文件后很可能直接导致应用因OOM（Out of Memory）崩溃。

因此，“边下边存”和“固定缓冲区”就成了必须遵循的原则。我们需要一个固定大小的内存块（例如1MB）作为数据中转站。网络流来的数据先填充到这个缓冲区，缓冲区满了（或一次接收的数据包达到缓冲区大小）就立刻写入硬盘，然后清空缓冲区继续接收下一批数据。这样，无论下载1MB还是1GB的文件，内存占用始终是那个固定缓冲区的大小，GC压力为零，稳定性极大提升。Unity的DownloadHandlerScript类正是为这种场景设计的。

2.2 技术方案对比：为什么不选其他方法？

网上常见的Unity断点续传实现，我大致归纳为两类，通过对比你就能明白为什么我们选择继承DownloadHandlerScript。

方案A：基于downloadHandler.data的流式读取这种方法看似巧妙，它试图通过while循环和偏移量index来分批处理req.downloadHandler.data。但它的致命伤在于，downloadHandler.data这个属性内部持有的，很可能仍然是整个文件的完整数据缓存。你虽然是在分批写入，但Unity底层可能在接收过程中就已经分配了完整内存。这就像用一个巨大的水缸（完整内存）接水，虽然你用水瓢（fs.Write）一瓢瓢往外舀，但水缸本身已经占满了院子（内存）。GC问题和内存峰值风险并未根本解决。

方案B：继承DownloadHandlerScript，使用预分配缓冲区这是我们采用的方案。其核心优势在DownloadHandlerScript的构造函数：public DownloadHandlerScript (byte[] preallocatedBuffer)。你传入一个预先创建好的字节数组（比如new byte[1024 * 1024]），Unity的网络模块在接收数据时，就会复用这个缓冲区来调用你的ReceiveData回调。这意味着在整个下载生命周期内，除了这个1MB的缓冲区，没有额外的字节数组被分配。内存曲线是一条平稳的直线，没有任何GC Alloc产生的波动。这是官方推荐的、用于高性能、避免GC的网络数据处理方式。

所以，选型结论很明确：为了实现稳定、零额外GC的大文件下载，继承DownloadHandlerScript是唯一的生产环境可靠选择。我们的下载器也将围绕这个核心类来构建。

3. 核心模块设计与实现细节

3.1 下载器核心类：DownloadHandlerFileRange

这是整个系统的发动机。它的任务是接管UnityWebRequest的数据接收过程，并将数据流安全地写入指定文件。

using System.IO; using UnityEngine; using UnityEngine.Networking; public class DownloadHandlerFileRange : DownloadHandlerScript { private FileStream fileStream; private string downloadPath; private long alreadyDownloadedBytes; // 已写入文件的字节数 private UnityWebRequest request; // 关联的请求，用于错误处理 public DownloadHandlerFileRange(string filePath, UnityWebRequest webRequest) : base(new byte[1024 * 1024]) // 预分配1MB缓冲区 { downloadPath = filePath; request = webRequest; alreadyDownloadedBytes = 0; // 确保目录存在 string directory = Path.GetDirectoryName(filePath); if (!Directory.Exists(directory)) { Directory.CreateDirectory(directory); } // 以追加模式打开文件流，如果文件不存在则创建 // FileMode.Append 会在文件末尾开始写入，这正是断点续传需要的 fileStream = new FileStream(filePath, FileMode.Append, FileAccess.Write, FileShare.Read); // 记录当前文件长度，作为已下载量（用于后续进度计算） alreadyDownloadedBytes = fileStream.Length; } // 核心回调：当有数据从网络到达时触发 protected override bool ReceiveData(byte[] data, int dataLength) { if (data == null || dataLength == 0 || request.isNetworkError || request.isHttpError) { return false; // 返回false会中止下载 } try { // 将缓冲区中的数据写入文件流 fileStream.Write(data, 0, dataLength); fileStream.Flush(); // 建议立即刷新，确保数据写入磁盘，避免程序崩溃丢失 alreadyDownloadedBytes += dataLength; return true; } catch (System.Exception e) { Debug.LogError($"写入文件失败: {e.Message}"); return false; } } // 下载完成时调用，进行清理工作 protected override void CompleteContent() { base.CompleteContent(); Dispose(); } // 获取当前已下载的字节数（用于进度计算） protected override byte[] GetData() { // 我们不返回实际数据，因为数据已直接写入文件 return null; } // 获取下载的文本内容（本例中不需要） protected override string GetText() { return string.Empty; } // 释放文件流资源 public new void Dispose() { if (fileStream != null) { fileStream.Close(); fileStream.Dispose(); fileStream = null; } base.Dispose(); } // 提供一个属性，方便外部获取已下载大小 public long DownloadedBytes => alreadyDownloadedBytes; }

关键点解析：

1. 构造函数传参：base(new byte[1024 * 1024])是灵魂所在。这个1MB的缓冲区将在整个下载过程中被循环使用。
2. FileMode.Append：使用追加模式打开文件流，这是实现断点续传的关键。如果文件已存在，新数据会自动写在文件末尾；如果不存在，则创建新文件。
3. ReceiveData回调：data参数就是那个预分配的缓冲区，dataLength是本次回调中缓冲区里有效数据的长度。切记：不能假设data.Length就是有效长度，必须使用dataLength。
4. 及时Flush：调用fileStream.Flush()可以将缓冲区数据强制写入物理磁盘。虽然会带来少量IO性能损耗，但能极大增强数据安全性，避免应用意外崩溃时丢失已接收但还在内存缓冲区中的数据。

3.2 下载管理器：ResumableDownloader

这个类负责组织整个下载流程，包括创建请求、设置请求头、处理进度、管理状态和错误重试。

using System; using System.Collections; using System.IO; using UnityEngine; using UnityEngine.Networking; using UnityEngine.Events; [System.Serializable] public class DownloadProgressEvent : UnityEvent<long, long, float> { } // 当前大小，总大小，进度 public class ResumableDownloader : MonoBehaviour { public string fileUrl; public string localFilePath; public bool deleteTempFileOnStart = true; // 是否在开始前删除临时文件（用于重新下载） public DownloadProgressEvent onProgressUpdated; // 进度更新事件 public UnityEvent onDownloadComplete; public UnityEvent<string> onDownloadError; private UnityWebRequest webRequest; private DownloadHandlerFileRange downloadHandler; private Coroutine downloadCoroutine; private long totalFileSize = -1; // 服务器文件总大小，-1表示未知 public void StartDownload() { if (downloadCoroutine != null) { StopCoroutine(downloadCoroutine); } downloadCoroutine = StartCoroutine(DownloadCoroutine()); } public void StopDownload() { if (downloadCoroutine != null) { StopCoroutine(downloadCoroutine); downloadCoroutine = null; } if (webRequest != null && !webRequest.isDone) { webRequest.Abort(); } Cleanup(); } private IEnumerator DownloadCoroutine() { // 1. 准备本地路径（支持使用临时文件） string finalPath = localFilePath; string tempPath = localFilePath + ".tmp"; // 使用.tmp作为临时文件后缀 string actualDownloadPath = tempPath; // 实际下载到临时文件 // 如果需要重新下载，则删除临时文件 if (deleteTempFileOnStart && File.Exists(tempPath)) { File.Delete(tempPath); } // 2. 获取本地已下载大小（即临时文件大小） long localFileSize = 0; if (File.Exists(actualDownloadPath)) { FileInfo fileInfo = new FileInfo(actualDownloadPath); localFileSize = fileInfo.Length; Debug.Log($"检测到已下载部分，大小: {localFileSize} bytes"); } // 3. 创建UnityWebRequest并设置Range头 webRequest = UnityWebRequest.Get(fileUrl); // 关键：设置Range请求头，告诉服务器从哪里开始发送数据 if (localFileSize > 0) { webRequest.SetRequestHeader("Range", $"bytes={localFileSize}-"); } // 4. 创建自定义的DownloadHandler downloadHandler = new DownloadHandlerFileRange(actualDownloadPath, webRequest); webRequest.downloadHandler = downloadHandler; // 5. 发送请求 var operation = webRequest.SendWebRequest(); // 6. 循环等待并更新进度 while (!operation.isDone) { yield return null; // 获取总大小（可能需要在收到响应头后） if (totalFileSize <= 0 && webRequest.responseCode == 206) // 206是部分内容的状态码 { string contentRange = webRequest.GetResponseHeader("Content-Range"); if (!string.IsNullOrEmpty(contentRange)) { // Content-Range格式: bytes 0-999/2000， 最后一部分是总大小 int slashIndex = contentRange.LastIndexOf('/'); if (slashIndex > 0) { string totalSizeStr = contentRange.Substring(slashIndex + 1); if (long.TryParse(totalSizeStr, out long total)) { totalFileSize = total; } } } } // 如果无法从Content-Range获取，尝试Content-Length（对于非断点请求） if (totalFileSize <= 0) { string contentLength = webRequest.GetResponseHeader("Content-Length"); if (!string.IsNullOrEmpty(contentLength) && long.TryParse(contentLength, out long cl)) { // 注意：对于断点请求，Content-Length是本次返回的数据长度，不是总长度 // 所以这里需要加上本地已下载的部分 totalFileSize = cl + localFileSize; } } // 计算当前总下载量 = 本地原有大小 + 本次已下载大小 long currentDownloaded = localFileSize + downloadHandler.DownloadedBytes; float progress = totalFileSize > 0 ? Mathf.Clamp01((float)currentDownloaded / totalFileSize) : 0f; // 触发进度更新事件 onProgressUpdated?.Invoke(currentDownloaded, totalFileSize, progress); } // 7. 请求完成，处理结果 if (webRequest.isNetworkError || webRequest.isHttpError) { // 特别注意：HTTP 416 状态码表示请求的范围无效，可能文件已下载完成 if (webRequest.responseCode == 416) // Range Not Satisfiable { Debug.LogWarning("HTTP 416: 请求的Range可能超出文件范围，可能文件已完整下载。"); // 检查临时文件大小是否合理，然后重命名为最终文件 HandleDownloadComplete(tempPath, finalPath); } else { onDownloadError?.Invoke($"下载失败: {webRequest.error} (HTTP {webRequest.responseCode})"); Debug.LogError($"下载失败: {webRequest.error}, URL: {fileUrl}"); } } else { // 下载成功 HandleDownloadComplete(tempPath, finalPath); } // 8. 清理 Cleanup(); downloadCoroutine = null; } private void HandleDownloadComplete(string tempPath, string finalPath) { try { if (File.Exists(tempPath)) { // 可选：验证文件完整性（例如对比MD5，这里省略） // ... // 将临时文件重命名为最终文件 if (File.Exists(finalPath)) { File.Delete(finalPath); // 删除可能存在的旧文件 } File.Move(tempPath, finalPath); Debug.Log($"下载完成，文件已保存至: {finalPath}"); onDownloadComplete?.Invoke(); } else { onDownloadError?.Invoke("错误：临时文件不存在。"); } } catch (System.Exception e) { onDownloadError?.Invoke($"文件重命名失败: {e.Message}"); } } private void Cleanup() { if (downloadHandler != null) { downloadHandler.Dispose(); downloadHandler = null; } if (webRequest != null) { webRequest.Dispose(); webRequest = null; } } void OnDestroy() { StopDownload(); } }

设计要点与避坑指南：

1. 临时文件策略：直接下载到最终文件名（如gameAsset.bundle）进行断点续传有一个隐患。如果下载中途程序崩溃，一个不完整的、损坏的最终文件已经存在。下次启动时，程序会读取这个损坏文件的大小作为localFileSize，并向服务器请求从这个偏移量继续下载，这很可能导致数据错乱。因此，最佳实践是下载到临时文件（如gameAsset.bundle.tmp），只有完整下载并校验后，才重命名为最终文件。这样，最终路径要么不存在，要么就是一个完整可用的文件。

2. 进度计算逻辑：进度 = (本地已有文件大小 + 本次下载器已写入大小) / 文件总大小。文件总大小需要从HTTP响应头中获取。对于断点续传请求（状态码206 Partial Content），服务器会在Content-Range头部中返回bytes start-end/total，其中的total就是总大小。这是最准确的来源。如果获取不到，再尝试用Content-Length（本次传输的数据长度）加上本地已有大小来估算。切记：对于非断点请求（从头下载），Content-Length就是总大小。

3. HTTP 416状态码处理：这是断点续传中的一个边界情况。当你请求的Range起始值（localFileSize）大于或等于服务器文件的总大小时，服务器会返回416。这通常意味着本地文件已经下载完成了。例如，一个100MB的文件，你本地临时文件刚好100MB，但你再次启动下载器，它读取到100MB并发送Range: bytes=100000000-，服务器就会返回416。在代码中，我们将其视为一个警告而非错误，并尝试完成重命名操作。

4. 进度条UI与用户交互集成

一个没有反馈的下载过程是令人焦虑的。我们需要将后台的下载进度实时、平滑地反映到UI上。

4.1 创建灵活的进度显示UI

在Unity UGUI中创建一个简单的进度显示面板：

• 一个Slider组件作为进度条。
• 两个Text组件，分别显示当前进度百分比和已下载/总大小的文本信息（如“125.6 MB / 500.0 MB”）。
• 一个Button用于开始/暂停下载（本例暂停功能需扩展，核心是停止并保存状态）。

4.2 将下载管理器与UI绑定

我们可以编写一个简单的UI控制器，监听下载管理器的事件，并更新UI元素。

using UnityEngine; using UnityEngine.UI; using System.Text; public class DownloadUI : MonoBehaviour { public ResumableDownloader downloader; // 拖拽赋值 public Slider progressSlider; public Text progressText; public Text statusText; public Button startButton; public Button pauseButton; // 暂停功能需扩展下载器以保存状态，此处略复杂 void Start() { if (downloader != null) { downloader.onProgressUpdated.AddListener(OnProgressUpdated); downloader.onDownloadComplete.AddListener(OnDownloadComplete); downloader.onDownloadError.AddListener(OnDownloadError); } startButton.onClick.AddListener(() => downloader.StartDownload()); // pauseButton.onClick.AddListener(() => downloader.PauseDownload()); // 暂停功能示例 UpdateStatus("准备就绪"); } void OnProgressUpdated(long current, long total, float progress) { // 更新Slider progressSlider.value = progress; // 格式化大小文本 string currentStr = FormatBytes(current); string totalStr = total > 0 ? FormatBytes(total) : "未知"; string percent = (progress * 100).ToString("F1"); progressText.text = $"{currentStr} / {totalStr} ({percent}%)"; // 更新状态文本，可以显示下载速度（需要额外计算） // statusText.text = $"下载中... {currentStr}/{totalStr}"; } void OnDownloadComplete() { progressSlider.value = 1.0f; progressText.text = "下载完成！"; UpdateStatus("下载成功"); startButton.interactable = false; } void OnDownloadError(string error) { UpdateStatus($"错误: {error}"); progressText.text = "下载失败"; // 可以设置Slider颜色变红等视觉反馈 } void UpdateStatus(string message) { if (statusText != null) statusText.text = message; } // 辅助函数：将字节数格式化为易读的字符串 (B, KB, MB, GB) private string FormatBytes(long bytes) { string[] suffixes = { "B", "KB", "MB", "GB", "TB" }; int order = 0; double len = bytes; while (len >= 1024 && order < suffixes.Length - 1) { order++; len = len / 1024; } return string.Format("{0:0.##} {1}", len, suffixes[order]); } void OnDestroy() { // 记得移除监听，防止内存泄漏 if (downloader != null) { downloader.onProgressUpdated.RemoveListener(OnProgressUpdated); downloader.onDownloadComplete.RemoveListener(OnDownloadComplete); downloader.onDownloadError.RemoveListener(OnDownloadError); } } }

UI优化技巧：

• 平滑进度：直接使用Slider.value = progress可能会因为网络波动导致进度条跳变。可以增加一个平滑插值（Lerp），让进度条动画更柔和。
• 下载速度显示：在OnProgressUpdated中，记录每次回调的时间Time.time和下载量current，计算差值即可得到瞬时速度。可以做一个移动平均来平滑速度显示。
• 多任务队列：实际项目中往往需要同时管理多个下载任务。你可以扩展ResumableDownloader，使其不继承MonoBehaviour，然后创建一个DownloadManager单例来管理多个下载器的实例、队列和全局UI更新。

5. 实战部署与疑难问题排查

5.1 在真实项目中的集成步骤

1. 导入核心脚本：将DownloadHandlerFileRange.cs和ResumableDownloader.cs放入项目的Scripts目录。
2. 创建下载管理器GameObject：在场景中创建一个空对象，挂载ResumableDownloader组件。配置好fileUrl和localFilePath。localFilePath建议使用Application.persistentDataPath作为根目录，这是跨平台可写的目录。
3. 构建UI：按4.1节创建UI，并将UI控制器脚本挂载到Canvas下的合适位置，将UI元素和下载管理器组件拖拽关联。
4. 处理平台差异：确保文件路径使用Path.Combine来拼接，以兼容Windows（\）和Unix（/）系统。

5.2 必知的坑与解决方案

坑1：Android真机上回调失灵（收不到ReceiveData）这是Unity IL2CPP代码裁剪（Code Stripping）导致的一个经典问题。为了减小包体，Unity在构建时会裁剪未使用的代码。DownloadHandlerScript的子类可能被误判为未使用而被裁剪掉。

解决方案：在项目Assets文件夹下创建或编辑link.xml文件，添加以下内容，告诉Unity不要裁剪UnityWebRequestModule相关的代码。

<?xml version="1.0" encoding="utf-8"?> <linker> <assembly fullname="UnityEngine.UnityWebRequestModule" preserve="all"/> </linker>

这个文件必须放在Assets根目录或Assets下的任何子目录，Unity构建时会自动识别。

坑2：文件写入权限问题（尤其是在Windows或某些移动平台）如果文件正在被其他进程（如资源管理器预览、杀毒软件扫描）占用，或者应用没有写入目标目录的权限，FileStream构造函数或Write操作会抛出UnauthorizedAccessException或IOException。

解决方案：

• 使用try-catch包裹文件操作，并给用户明确的错误提示。
• 确保目标目录存在且有写入权限。对于移动平台，优先使用Application.persistentDataPath。
• 考虑在写入文件时使用FileShare.Read模式，允许其他进程读取但不写入，这能在一定程度上避免冲突。

坑3：断点续传时服务器不支持Range请求不是所有HTTP服务器都支持Range头部。如果服务器不支持，它可能会忽略这个头部，直接返回整个文件（状态码200），或者返回错误。

解决方案：

• 在发送请求前，可以先发送一个HEAD请求来检查服务器是否支持Range（通过响应头中是否包含Accept-Ranges: bytes来判断）。
• 如果不支持，则回退到普通下载模式，并提示用户无法断点续传。我们的代码框架兼容这种回退，因为当localFileSize为0时，即使不设置Range头，也能正常从头下载。

坑4：进度条在编辑器中正常，打包后卡住不动这可能是因为在后台线程中频繁更新UI导致的。Unity的UI操作必须在主线程执行。虽然UnityWebRequest的回调一般是在主线程，但如果你在复杂的协程中做了阻塞操作，或者在某些情况下回调线程不一致，就可能出问题。

解决方案：确保所有更新UI的代码（如onProgressUpdated?.Invoke）都在主线程执行。可以使用MainThreadDispatcher这样的工具类来确保安全，或者简单地将进度值存储在一个 volatile 变量中，在Update方法里读取并更新UI。

坑5：下载大文件到后期，速度变慢或内存缓慢上升虽然我们使用了固定缓冲区，但如果你在ReceiveData回调中进行了复杂的处理（比如实时计算MD5），或者FileStream没有及时释放，仍可能导致问题。

解决方案：

• 保持ReceiveData回调内的逻辑尽可能简单，只做必要的写入操作。校验等工作可以放到下载完成后进行。
• 确保DownloadHandlerFileRange的Dispose方法被正确调用，以关闭文件流。ResumableDownloader中的Cleanup方法负责了这一点。

5.3 进阶优化方向

1. 多线程分片下载：对于超大型文件，可以创建多个UnityWebRequest，每个请求文件的不同片段（Range: bytes=0-999999,Range: bytes=1000000-1999999...），并行下载后再合并。这能极大利用带宽，但复杂度也剧增，需要处理分片、合并、错误重试等。
2. 下载队列与优先级：实现一个DownloadQueue，管理等待、进行中、已完成的任务，并允许设置优先级（如优先下载关键资源）。
3. 完整性校验：下载完成后，计算文件的MD5或SHA1哈希值，与服务器提供的哈希值对比，确保文件在传输过程中没有损坏。
4. 后台下载与通知：对于移动平台，研究如何结合UnityMobile插件或平台原生代码，实现应用切换到后台时仍能继续下载，并在完成后发送本地通知。

这个带进度条的断点续传下载器，是我经过多个项目打磨后的稳定方案。它解决了大文件下载中最核心的稳定性和用户体验问题。代码已经开源，你可以根据项目需求进行裁剪和扩展。网络模块是游戏与外界沟通的血管，一个健壮的下载器就是确保血液顺畅流动的心脏。希望这套方案和这些经验，能帮你构建出更强大的资源管理系统。