Unity网络通信实战：基于Best HTTP/3实现稳定文件上传与动态数据流传输

原创于 2026-08-07 09:40:30 发布 · 431 阅读

本内容遵循CC 4.0 BY-SA版权协议

1. 项目概述与核心价值

最近在做一个Unity项目，需要把游戏里的截图、录屏，还有运行时动态生成的音频数据包，稳定地上传到我们自己的服务器。一开始图省事，直接用Unity自带的 UnityWebRequest ，结果在文件上传和长连接数据流传输上，踩坑踩到怀疑人生。文件稍微大点就卡顿、内存飙升，动态流传输更是难以管理，断线重连和进度反馈做得非常痛苦。后来团队里一个老司机推荐了Best HTTP/3插件，说是专门为Unity优化过的HTTP/3协议实现，能根治这些问题。我花了一周时间深度折腾了一遍，从基础的文件上传到复杂的动态数据流实时传输，都跑通了。这篇文章，我就把自己从零搭建、调试到最终稳定上线的完整过程，以及过程中那些官方文档没写的“坑”和“技巧”，毫无保留地分享出来。无论你是想实现一个稳定的资源上传功能，还是要做类似语音直播、实时日志回传这类需要持续传输动态数据的场景，这篇教程都能给你一套可直接“抄作业”的解决方案。

简单来说，Best HTTP/3（下文简称BH3）是一个第三方插件，它原生支持最新的HTTP/3协议（基于QUIC），在移动网络和高延迟环境下，比传统的HTTP/1.1或HTTP/2有显著的性能优势，连接建立更快、抗丢包能力更强。但它的价值远不止于此，其API设计对Unity开发者极其友好，封装了流式上传、下载、多部分表单、WebSocket等复杂功能，让网络通信代码写起来清晰又健壮。本教程将聚焦两个最实用的核心场景： 可靠的文件上传 和 动态数据流的持续传输 。

2. 环境准备与插件导入

2.1 插件获取与版本选择

首先，你需要获取Best HTTP/3插件。最可靠的途径是通过Unity Asset Store购买。在Asset Store中搜索“Best HTTP/3”，确保你购买的是支持HTTP/3的版本。购买后，在Unity编辑器的Package Manager中，从“My Assets”标签页找到并导入。

注意：网络上可能存在一些旧的“Best HTTP/2”或“Best HTTP”免费版本，它们功能不全且不再维护。为了获得稳定的文件上传和流传输支持，强烈建议使用正版的Best HTTP/3。

导入时，插件可能会提示你安装一些依赖项，比如用于JSON序列化的 Newtonsoft.Json 。一律点击确认安装。导入完成后，你的项目Assets文件夹下会出现 Best HTTP 、 Best HTTP.Examples 等目录。为了保持项目整洁，我建议先浏览一下 Examples 文件夹，里面有很多有用的示例，但正式开发时，可以将其移出或删除，避免与项目代码混淆。

2.2 基础配置与初始化

BH3插件需要简单的初始化才能工作。通常，你需要在游戏启动的早期（例如在首个场景的某个永不销毁的GameObject的 Awake 方法中）进行配置。

using Best.HTTP;
using UnityEngine;

public class NetworkManager : MonoBehaviour
{
    void Awake()
    {
        DontDestroyOnLoad(this.gameObject);
        
        // 1. 设置全局日志级别，开发阶段建议设为All，上线后改为Error或None
        HTTPManager.Logger.Level = Loglevels.All;
        
        // 2. （可选但推荐）设置持久化缓存路径和大小限制
        HTTPManager.CachePath = Application.persistentDataPath + "/HTTPCache";
        HTTPManager.CacheSize = 50 * 1024 * 1024; // 50MB
        
        // 3. 配置连接池和超时设置（针对文件上传和长连接优化）
        var globalOptions = HTTPManager.PerHostSettings.Get("your-api-domain.com");
        globalOptions.MaxConnectionPerServer = 4; // 每服务器最大连接数
        globalOptions.KeepAliveTime = TimeSpan.FromMinutes(2); // 保持连接时间
        globalOptions.ConnectTimeout = TimeSpan.FromSeconds(30); // 连接超时
        globalOptions.RequestTimeout = TimeSpan.FromSeconds(60); // 请求超时，上传大文件需调大
        
        Debug.Log("Best HTTP/3 初始化完成。");
    }
}

配置解析与避坑 ：

日志级别 ：开发时设为 All 可以查看所有网络请求和响应的细节，对于调试上传失败、流中断等问题至关重要。发布版本一定要改为 Error 或 None ，否则日志输出会影响性能。
缓存设置 ：即使我们主要做上传，设置缓存也有好处。例如，如果你上传前需要先下载一个配置文件，缓存能加速这个过程。路径设为 Application.persistentDataPath 是跨平台的标准做法。
连接设置 ： MaxConnectionPerServer 不宜设置过大，通常2-4个足够，避免对服务器造成压力。 RequestTimeout 对于大文件上传至关重要，需要根据你的网络环境和文件大小估算并留足余量。一个100MB的文件在较慢的网络上上传可能需要几分钟。

3. 核心场景一：实现可靠的文件上传

文件上传是游戏开发中的高频需求，比如用户头像、游戏截图、用户生成内容（UGC）等。BH3让这个过程变得异常简单。

3.1 基础表单文件上传

最基本的场景是模拟网页表单，上传一个本地文件。假设我们有一个接口 https://api.yourgame.com/upload ，接受 POST 请求，表单字段名为 file 。

using System.IO;
using Best.HTTP;
using UnityEngine;

public class FileUploader : MonoBehaviour
{
    public void UploadFile(string localFilePath)
    {
        if (!File.Exists(localFilePath))
        {
            Debug.LogError($"文件不存在: {localFilePath}");
            return;
        }

        // 1. 创建请求对象
        var request = new HTTPRequest(new Uri("https://api.yourgame.com/upload"), HTTPMethods.Post);
        
        // 2. 设置表单数据，并添加文件字段
        var form = new HTTPRequestBase.FormData();
        form.AddBinaryData("file", File.ReadAllBytes(localFilePath), 
                           Path.GetFileName(localFilePath), 
                           "application/octet-stream"); // MIME类型可根据文件扩展名调整
        
        // 3. 将表单数据设置到请求中
        request.SetFormFields(form);
        
        // 4. 设置回调
        request.Callback = OnUploadFinished;
        
        // 5. （可选）添加上传进度回调
        request.OnUploadProgress = OnUploadProgress;
        
        // 6. 发送请求
        request.Send();
    }
    
    private void OnUploadProgress(HTTPRequest req, long downloaded, long downloadLength)
    {
        // 注意：BH3中OnUploadProgress的参数名是downloaded/downloadLength，但实际用于上传进度
        if (downloadLength > 0)
        {
            float progress = (float)downloaded / downloadLength;
            Debug.Log($"上传进度: {progress:P2}");
            // 这里可以更新UI进度条
        }
    }
    
    private void OnUploadFinished(HTTPRequest req, HTTPResponse resp)
    {
        switch (req.State)
        {
            case HTTPRequestStates.Finished:
                if (resp.IsSuccess) // 例如状态码为200-299
                {
                    Debug.Log($"上传成功! 响应: {resp.DataAsText}");
                    // 处理服务器返回的JSON，如文件URL
                }
                else
                {
                    Debug.LogError($"上传失败，状态码: {resp.StatusCode}， 响应: {resp.DataAsText}");
                }
                break;
            case HTTPRequestStates.Error:
                Debug.LogError($"请求出错: {req.Exception?.Message}");
                break;
            case HTTPRequestStates.Aborted:
                Debug.LogWarning("请求被中止。");
                break;
            case HTTPRequestStates.ConnectionTimedOut:
                Debug.LogError("连接超时。");
                break;
            case HTTPRequestStates.TimedOut:
                Debug.LogError("请求超时。");
                break;
        }
        // 释放请求资源（重要！）
        req.Dispose();
    }
}

实操要点与避坑指南 ：

文件读取 ： File.ReadAllBytes 会一次性将整个文件加载到内存中。这对于几MB的小文件（如图片）没问题，但对于上百MB的视频文件，会造成巨大的内存压力，甚至导致Unity应用崩溃。
内存优化方案 ：对于大文件，必须使用 流式上传 。BH3的 FormData 支持直接添加文件流，这才是生产环境推荐的做法。
MIME类型 ： application/octet-stream 是通用的二进制流类型。最好根据文件实际类型设置，如图片用 image/jpeg 或 image/png ，服务器端处理起来更准确。
进度回调 ： OnUploadProgress 回调非常有用，但要注意其参数名容易引起误解。它返回的是 已上传的字节数 和 总字节数 。
状态检查 ：务必在回调中检查 req.State 和 resp.IsSuccess 。 Finished 状态只代表HTTP事务完成（收到响应），不代表业务成功，业务成功需要看HTTP状态码（如200）和响应体内容。
资源释放 ：请求完成后，调用 req.Dispose() 是个好习惯，尤其是在频繁发起请求的场景下，有助于及时释放底层连接资源。

3.2 流式上传大文件与多部分表单

为了解决大文件内存问题，并支持更复杂的表单（如同时上传文件和其他参数），我们需要使用流式上传和多部分表单。

public void StreamUploadLargeFile(string localFilePath, string description)
{
    FileStream fileStream = null;
    try
    {
        fileStream = new FileStream(localFilePath, FileMode.Open, FileAccess.Read);
        
        var request = new HTTPRequest(new Uri("https://api.yourgame.com/upload"), HTTPMethods.Post);
        
        // 使用多部分表单（Multipart Form）
        var multiPartForm = new HTTPRequestBase.MultipartForm();
        
        // 添加普通文本字段
        multiPartForm.AddField("description", description);
        multiPartForm.AddField("userId", "player_12345");
        
        // 添加文件字段 - 关键！使用Stream方式，避免全量读入内存
        multiPartForm.AddStreamField("file", 
                                     fileStream, 
                                     Path.GetFileName(localFilePath), 
                                     GetMimeType(Path.GetExtension(localFilePath)));
        
        request.SetFormFields(multiPartForm);
        request.Callback = (req, resp) => 
        {
            // 在回调中确保流被关闭
            fileStream?.Close();
            OnUploadFinished(req, resp);
        };
        request.OnUploadProgress = OnUploadProgress;
        
        request.Send();
    }
    catch (System.Exception e)
    {
        Debug.LogError($"打开文件流失败: {e.Message}");
        fileStream?.Close();
    }
}

private string GetMimeType(string extension)
{
    switch (extension.ToLower())
    {
        case ".jpg": case ".jpeg": return "image/jpeg";
        case ".png": return "image/png";
        case ".mp3": return "audio/mpeg";
        case ".mp4": return "video/mp4";
        case ".txt": return "text/plain";
        case ".json": return "application/json";
        default: return "application/octet-stream";
    }
}

核心优势解析 ：

内存友好 ： AddStreamField 方法并不会立即读取整个文件，而是会在上传过程中，按需从文件流中读取数据块并发送。这意味着上传一个1GB的文件，内存占用也只会是几十KB的缓冲区大小。
支持复杂数据 ：多部分表单允许你混合发送二进制文件和文本字段，非常适用于需要附带元数据（如描述、用户ID、时间戳）的上传场景。
异常处理 ：使用 try-catch 包裹文件流操作是必须的，确保即使在请求创建失败时，文件流也能被正确关闭，避免资源泄漏。

3.3 添加上传暂停、恢复与取消功能

对于移动端或网络不稳定的环境，支持断点续传是提升用户体验的关键。BH3本身不直接提供断点续传的HTTP协议支持（这需要服务器端配合），但我们可以利用其请求取消机制，并结合服务器支持的分片上传API，来实现类似功能。这里先展示如何取消一个正在进行的上传请求，这是实现更高级控制的基础。

private HTTPRequest _currentUploadRequest;

public void StartUpload(string path)
{
    if (_currentUploadRequest != null)
    {
        Debug.LogWarning("已有上传任务在进行中。");
        return;
    }
    // ... 创建request的代码同上 ...
    _currentUploadRequest = request;
    request.Send();
}

public void PauseOrCancelUpload()
{
    if (_currentUploadRequest != null)
    {
        // 中止请求。如果是可恢复的上传，这里应该先记录已上传的字节位置。
        _currentUploadRequest.Abort();
        _currentUploadRequest = null;
        Debug.Log("上传已中止。");
    }
}

// 在请求的回调中，记得清理引用
private void OnUploadFinished(HTTPRequest req, HTTPResponse resp)
{
    if (req == _currentUploadRequest)
    {
        _currentUploadRequest = null;
    }
    // ... 其他处理逻辑 ...
}

重要提示 ：简单的 Abort() 会直接断开连接，如果服务器不支持断点续传，下次上传需要重头开始。真正的断点续传需要：

服务器提供分片上传接口（如七牛云、阿里云OSS的API）。
客户端将大文件分片，记录每片的上传状态。
上传中断后，只上传未完成的片段。这超出了BH3基础功能的范畴，需要你根据具体的云存储服务API来实现。BH3在这里的角色是稳定地执行每一个分片的上传HTTP请求。

4. 核心场景二：动态数据流传输

动态数据流传输指的是持续、单向或双向地发送非预先存在的、在运行时生成的数据。典型场景包括：游戏内语音聊天（发送音频采样）、实时屏幕共享（发送视频帧）、游戏操作同步、或运行时日志/分析数据的上报。这不再是上传一个完整的文件，而是建立一个“数据管道”。

4.1 使用HTTP Streaming（分块传输编码）

对于单向的、客户端持续向服务器发送数据的场景，可以使用HTTP Streaming，即利用HTTP/1.1的Chunked Transfer Encoding或HTTP/2/3的流特性。BH3的流式上传功能天然支持这一点。

假设服务器有一个长连接端点，可以持续接收我们发送的JSON数据包。

using System.Collections.Generic;
using System.Text;
using Best.HTTP;

public class DataStreamSender : MonoBehaviour
{
    private HTTPRequest _streamingRequest;
    private bool _isStreamingActive = false;
    private Queue<string> _dataQueue = new Queue<string>();
    
    public void StartStreamingToServer(string serverUrl)
    {
        if (_isStreamingActive) return;
        
        _streamingRequest = new HTTPRequest(new Uri(serverUrl), HTTPMethods.Post);
        // 关键：设置UseStreaming标志，告诉插件我们将使用流式主体
        _streamingRequest.UseStreaming = true;
        // 设置一个较长的超时，因为这是长连接
        _streamingRequest.Timeout = TimeSpan.FromMinutes(10);
        
        _streamingRequest.Callback = OnStreamingFinished;
        _streamingRequest.OnUploadProgress = OnStreamingProgress;
        
        // 开始请求，此时连接已建立，可以开始写入数据
        _streamingRequest.Send();
        _isStreamingActive = true;
        
        Debug.Log("数据流通道已启动。");
        
        // 启动一个协程，持续从队列中取出数据并发送
        StartCoroutine(StreamingDataCoroutine());
    }
    
    private System.Collections.IEnumerator StreamingDataCoroutine()
    {
        while (_isStreamingActive && _streamingRequest != null)
        {
            if (_dataQueue.Count > 0)
            {
                string dataPacket = _dataQueue.Dequeue();
                byte[] bytes = Encoding.UTF8.GetBytes(dataPacket + "\n"); // 加换行符作为分隔符
                
                try
                {
                    // 将数据写入请求的流中
                    _streamingRequest.Stream.Write(bytes, 0, bytes.Length);
                    _streamingRequest.Stream.Flush(); // 确保数据被推送出去
                    Debug.Log($"已发送数据包: {dataPacket}");
                }
                catch (System.Exception e)
                {
                    Debug.LogError($"写入流失败: {e.Message}");
                    StopStreaming();
                    yield break;
                }
            }
            // 每帧处理，避免阻塞。如果数据产生很慢，可以适当增加yield时间。
            yield return null; 
        }
    }
    
    // 外部调用此方法，将产生的数据加入发送队列
    public void EnqueueStreamData(string jsonData)
    {
        if (_isStreamingActive)
        {
            _dataQueue.Enqueue(jsonData);
        }
    }
    
    private void OnStreamingProgress(HTTPRequest req, long uploaded, long total)
    {
        // 对于持续流，total可能为-1（未知），主要看uploaded的增长
    }
    
    private void OnStreamingFinished(HTTPRequest req, HTTPResponse resp)
    {
        _isStreamingActive = false;
        _streamingRequest = null;
        Debug.Log($"数据流传输结束。状态: {req.State}, HTTP状态码: {resp?.StatusCode}");
        // 处理结束逻辑，如重连尝试
    }
    
    public void StopStreaming()
    {
        if (_streamingRequest != null)
        {
            _isStreamingActive = false;
            _streamingRequest.Abort(); // 或等待其自然结束
            _streamingRequest = null;
            _dataQueue.Clear();
        }
    }
}

实现原理与注意事项 ：

UseStreaming = true ：这是核心设置。它告诉BH3不要缓存整个请求体，而是允许你通过 request.Stream 属性获取一个可写的流，并随时向其中写入数据。底层协议会自动处理分块编码。
数据分隔 ：由于是持续的数据流，服务器需要知道一个数据包的边界。常见的做法是在每个数据包末尾添加一个特定的分隔符，如换行符 \n 。这样服务器端可以按行读取。更复杂的方案可以使用长度前缀（先发送4字节表示后续数据长度）。
生产者-消费者模式 ：这里使用了队列（ Queue ）来解耦数据生产（如音频采集线程）和网络发送（主线程协程）。生产数据的方法 EnqueueStreamData 可以来自任何线程，但发送协程在主线程运行，通过 yield return null 避免阻塞。
错误处理与重连 ：流传输对网络稳定性要求高。一旦 Stream.Write 抛出异常或回调中 req.State 为 Error ，应该关闭当前连接，并可能根据业务逻辑实现指数退避的重连机制。
服务器端兼容性 ：你的服务器端必须能够处理这种“永不结束”的HTTP POST请求，并能够从输入流中持续读取数据。使用Node.js的Express、Go的net/http或Python的Flask等框架都可以实现。

4.2 动态二进制流传输（以音频为例）

上面的例子传输的是文本JSON。对于二进制数据（如原始的音频PCM采样、视频帧），原理相同，只是写入流的数据是 byte[] 。

// 假设有一个方法在实时采集音频数据
public void OnAudioFilterRead(float[] data, int channels)
{
    // 这是Unity音频线程的回调，不能直接操作Unity对象或进行网络请求
    // 1. 将float[]音频数据转换为byte[] (例如16位PCM)
    byte[] pcmData = ConvertAudioToByteArray(data);
    
    // 2. 将byte[]加入队列。注意：这里需要线程安全的队列！
    // System.Collections.Concurrent.ConcurrentQueue<T> 是一个好选择
    _audioDataQueue.Enqueue(pcmData);
}

// 在StreamingDataCoroutine中，发送二进制数据
private System.Collections.IEnumerator StreamingBinaryDataCoroutine()
{
    while (_isStreamingActive)
    {
        if (_audioDataQueue.TryDequeue(out byte[] dataPacket))
        {
            // 可以先写入一个4字节的包头，表示后续数据长度
            byte[] lengthPrefix = System.BitConverter.GetBytes(dataPacket.Length);
            _streamingRequest.Stream.Write(lengthPrefix, 0, lengthPrefix.Length);
            // 再写入实际音频数据
            _streamingRequest.Stream.Write(dataPacket, 0, dataPacket.Length);
            _streamingRequest.Stream.Flush();
        }
        yield return null;
    }
}

关键技巧 ：

线程安全 ：音频采集回调 OnAudioFilterRead 运行在独立的音频线程，不能直接访问 _streamingRequest.Stream 。必须使用线程安全的队列（如 ConcurrentQueue ）进行跨线程数据传递。
数据包格式 ：对于二进制流，定义清晰的数据包格式至关重要。**“长度前缀法”**是最可靠的方式：先发送一个固定大小的整数（如4字节）表示后续有效数据的长度，再发送数据本身。这样服务器端可以准确无误地解析出每一个完整的数据包。
缓冲区与性能 ：如果数据产生速度极快（如高采样率音频），要小心队列积压导致内存增长。可以设置一个队列最大长度，当队列满时丢弃最旧的数据包，或者暂停采集，这取决于你的应用对实时性和完整性的要求。

5. 高级配置、调试与性能优化

5.1 连接池与HTTP/3优化

BH3的强大之处在于其对HTTP/3的原生支持。HTTP/3基于QUIC协议，在移动网络和多路复用方面表现优异。

void ConfigureHTTP3()
{
    // 全局启用HTTP/3（如果服务器支持，插件会自动协商使用）
    HTTPManager.HTTP3Settings.EnableHTTP3 = true;
    
    // 针对特定主机配置HTTP/3参数
    var hostSettings = HTTPManager.PerHostSettings.Get("api.yourgame.com");
    hostSettings.HTTP3Settings.EnableHTTP3 = true;
    hostSettings.HTTP3Settings.MaxServerPushStreams = 10; // 服务器推送流最大数量
    // QUIC连接空闲超时时间，对于长连接流传输可以设置长一些
    hostSettings.HTTP3Settings.ConnectionIdleTimeout = TimeSpan.FromMinutes(5);
}

何时使用HTTP/3 ：如果你的服务器（例如使用了Cloudflare、Google Cloud等现代边缘网络）支持HTTP/3，那么在高延迟、高丢包的网络环境下（如移动4G/5G），开启HTTP/3通常会获得更快的连接建立速度和更稳定的传输体验，尤其对于需要发起多个并行请求或流式传输的场景。

5.2 调试与日志分析

网络问题难以复现，完善的日志是排查问题的生命线。

void EnableDetailedLogging()
{
    HTTPManager.Logger.Level = Loglevels.All;
    
    // 可以将日志写入文件，方便离线分析
    HTTPManager.Logger.AddLogger(new FileLogger(Application.persistentDataPath + "/network.log"));
    
    // 监听所有请求和响应的事件，进行自定义监控
    HTTPManager.OnRequestFinished += (req, resp) => {
        Debug.Log($"[NetworkTrace] {req.Method} {req.Uri} -> {resp.StatusCode} in {resp.Timing.TotalMilliseconds}ms");
    };
}

解读日志 ：BH3的详细日志会输出每个请求的URL、方法、请求头、响应头、状态码、时间线（DNS查询、连接、TLS握手、发送、接收等各阶段耗时）。当上传慢或流中断时，首先查看日志：

如果卡在 Connecting 阶段，可能是DNS或TCP连接问题。
如果 Sending 阶段很长，可能是网络上行带宽不足或数据包太大。
如果收到 4xx 状态码，检查请求格式、认证信息。
如果收到 5xx 状态码，是服务器内部错误。

5.3 移动平台适配与后台传输

在iOS和Android上，应用切换到后台时，网络活动可能会被系统挂起。

// 在Unity的OnApplicationPause回调中处理
void OnApplicationPause(bool pauseStatus)
{
    if (pauseStatus)
    {
        // 应用进入后台
        // 对于文件上传，如果没完成，可以考虑暂停或记录状态
        if (_currentUploadRequest != null && _currentUploadRequest.State == HTTPRequestStates.Processing)
        {
            Debug.Log("应用进入后台，正在处理的上传任务可能会被中断。");
            // 对于重要的上传，可以尝试请求后台任务时间（iOS）或使用Foreground Service（Android）
        }
        // 对于数据流，通常需要主动关闭，因为后台保活策略复杂
        StopStreaming();
    }
    else
    {
        // 应用回到前台
        // 检查并恢复网络任务
        CheckAndResumeNetworkTasks();
    }
}

平台特定要求 ：

iOS ：如果需要在后台进行长时间网络传输，必须启用 Background Modes 中的 Background fetch 或 Background processing ，并且使用 URLSession 的background configuration。BH3作为高层封装，可能无法直接满足所有后台传输场景，对于关键任务，可能需要考虑原生插件。
Android ：类似地，如果需要长时间后台上传，可能需要启动一个 ForegroundService ，并在通知栏显示进度，否则进程容易被系统回收。
通用建议 ：对于游戏来说，最稳妥的方式是在应用即将进入后台时，暂停非关键的网络传输，并在回到前台时恢复或重新开始。对于必须后台完成的任务（如保存游戏进度上传），设计成小数据包、快速完成，并处理好中断重试。

6. 常见问题排查与解决方案实录

在实际开发中，我遇到了不少问题，这里总结几个最有代表性的。

6.1 文件上传失败，服务器返回413 Request Entity Too Large

问题现象 ：上传一个较大的视频文件时，请求很快失败，服务器返回413错误。

原因分析 ：413错误表示请求体过大，超过了服务器（如Nginx、Apache）配置的 client_max_body_size 限制。

解决方案 ：

客户端分片 ：将大文件在客户端切割成多个小块（例如每片5MB），依次上传。这需要服务器端提供支持分片上传和合并的接口（很多云存储服务如S3、OSS都有此API）。
联系后端调整配置 ：如果是自己的服务器，可以修改Nginx的 client_max_body_size 配置，或者修改应用服务器（如Node.js、Tomcat）的相应限制。
压缩文件 ：在上传前对文件进行压缩（例如，将PNG图片转换为JPG，或使用更高压缩率的视频编码）。

6.2 动态数据流传输一段时间后自动断开

问题现象 ：语音流传输几分钟后，连接无故断开，回调进入 Error 或 TimedOut 状态。

原因分析 ：

网络中间件超时 ：服务器前方的负载均衡器（如Nginx）或云服务商的网关，对于长时间没有数据传输的连接，会设置一个 keepalive_timeout 或 proxy_read_timeout ，超时后会主动断开连接。
服务器应用超时 ：服务器端应用框架（如Express、Spring）也有请求超时设置。
客户端超时 ：BH3请求本身的 Timeout 设置。

排查与解决 ：

添加心跳包 ：在数据流传输的间隙，定期（例如每15秒）向服务器发送一个小的、无业务意义的数据包（如 {"ping":1} ），以保持连接活跃。
```
IEnumerator SendHeartbeat()
{
    while (_isStreamingActive)
    {
        yield return new WaitForSeconds(15f);
        EnqueueStreamData("{\"ping\":1}");
    }
}
```
协调超时时间 ：与后端工程师沟通，将服务器端和网络中间件的超时时间调至一个合理的值（例如10-30分钟），并确保客户端的 request.Timeout 设置更长。
实现断线重连 ：在 OnStreamingFinished 回调中，如果断开是非主动的（如超时、错误），启动一个带有指数退避策略的重连机制。

6.3 在Unity Editor中正常，打包到iOS/Android后上传失败

问题现象 ：在编辑器里测试文件上传一切正常，但发布到真机后，请求无法发出或立即失败。

原因分析 ：

网络权限 ：移动平台需要显式声明网络权限。
ATS/SSL问题 （iOS特有）：iOS强制要求使用HTTPS，且证书必须符合ATS（App Transport Security）标准。使用自签名证书或过时的TLS版本会导致连接失败。
URL格式或域名解析 ：真机环境可能与开发机的网络环境（如代理、DNS）不同。

解决方案 ：

检查权限 ：
- Android ：确保 AndroidManifest.xml 中包含 <uses-permission android:name="android.permission.INTERNET" /> 。
- iOS ：通常不需要额外配置，但若使用非标准端口，可能需要在 Info.plist 中配置ATS例外。
处理SSL证书 ：
- 对于开发测试，可以在iOS的 Info.plist 中临时禁用ATS（生产环境不推荐）。
- 更好的方式是让服务器部署有效的、受信任的SSL证书（如Let's Encrypt免费证书）。
- 如果必须使用自签名证书，BH3提供了自定义证书验证的回调，但极其不推荐用于生产环境。
使用绝对URL与日志 ：确保请求使用的是完整的、正确的URL（如 https://api.yourgame.com ）。在真机上开启BH3的详细日志，并将日志输出到文件或网络控制台，查看具体的错误信息。

6.4 上传过程中内存持续增长直至崩溃

问题现象 ：上传大文件时，Unity进程的内存占用肉眼可见地快速增长，最终导致应用崩溃（尤其在移动设备上）。

原因分析 ：这是最经典的陷阱。虽然我们使用了 AddStreamField ，但如果在回调中不当持有对请求或响应数据的引用，或者插件内部有缓存，可能导致内存无法释放。

解决方案 ：

确保使用流式上传 ：如3.2节所述，对大文件务必使用 AddStreamField 。
及时释放资源 ：在请求的 Callback 中，处理完响应数据后，调用 req.Dispose() 。虽然BH3有自动垃圾回收，但显式释放可以更及时。
检查回调中的引用 ：不要在回调方法外长期持有 resp.Data 或 resp.DataAsText 这类可能包含大量数据的对象。如果需要，及时将其拷贝到业务需要的数据结构中，然后让请求对象被回收。
监控Unity Profiler ：在开发阶段，使用Unity Profiler的Memory模块，在上传操作前后抓取快照，对比 Managed Heap 的变化，定位是哪个部分导致了内存泄漏。

经过以上这些步骤的实践和优化，我们项目中的文件上传和动态数据流功能已经稳定运行了数月。BH3插件提供的稳定性和易用性，确实让Unity网络编程的复杂度降低了一个数量级。最后一个小建议是，对于任何网络操作，尤其是上传和长连接，一定要在弱网环境下（可以使用网络模拟工具）进行充分的测试，模拟丢包、高延迟、网络切换等场景，才能确保最终用户的体验。

标签