Unity UnityWebRequest常用操作

心疼你的一切

发布于 2026-01-20 14:48:10

1440

前言

UnityWebRequest 提供了一个模块化系统，用于构成 HTTP 请求和处理 HTTP 响应。UnityWebRequest 系统的主要目标是让 Unity 游戏与 Web 浏览器后端进行交互。该系统还支持高需求功能，例如分块 HTTP 请求、流式 POST/PUT 操作以及对 HTTP 标头和动词的完全控制。

该系统由两层组成：

高级 API (HLAPI) 封装了低级 API，并提供方便的界面来执行常见操作
低级 API (LLAPI) 为更高级的用户提供了最大的灵活性

博客将会介绍UnityWebRequest常用操作。希望这篇博客对Unity的开发者有所帮助。大家好，我是心疼你的一切，不定时更新Unity开发技巧，觉得有用记得一键三连哦。欢迎点赞评论哦.下面就让我们进入正文吧。

提示：以下是本篇文章正文内容，下面案例可供参考

一、UnityWebRequest支持的平台

UnityWebRequest 系统支持大多数 Unity 平台：

所有版本的 Editor 和独立平台播放器
WebGL
移动平台：iOS 和 Android
通用 Windows 平台

二、架构

UnityWebRequest 生态系统将 HTTP 事务分解为三个不同的操作：

向服务器提供数据
从服务器接收数据
HTTP 流量控制（例如，重定向和错误处理）

为了给高级用户提供更好的界面，这些操作均由自己的对象进行管理：

UploadHandler 对象处理数据到服务器的传输
DownloadHandler 对象处理从服务器接收的数据的接收、缓冲和后处理
UnityWebRequest 对象管理其他两个对象，还处理 HTTP 流量控制。此对象是定义自定义标头和 URL 的位置，也是存储错误和重定向信息的位置。

对于任何 HTTP 事务，正常的代码流程如下：

创建 Web 请求对象
配置 Web 请求对象
设置自定义标头
设置 HTTP 动词（例如 GET、POST 和 HEAD - 除 Android 之外的所有平台都允许使用自定义动词）
设置 URL *（可选）创建上传处理程序并将其附加到 Web 请求
提供要上传的数据
提供要上传的 HTTP 表单 *（可选）创建下载处理程序并将其附加到 Web 请求
发送 Web 请求
如果在协程中，可获得 Send() 调用的结果以等待请求完成（可选）读取从下载处理程序接收的数据（可选）从 UnityWebRequest 对象中读取错误信息、HTTP 状态码和响应标头

三、常用操作：使用 HLAPI

3-1、从 HTTP 服务器检索文本或二进制数据 (GET)

要从标准 HTTP 或 HTTPS Web 服务器检索简单数据（比如文本数据或二进制数据），请使用 UnityWebRequest.GET 调用。此函数将单个字符串作为参数，字符串用于指定从中检索数据的 URL。

此函数类似于标准 WWW 构造函数：

WWW myWww = new WWW("https://www.myserver.com/foo.txt");
// ... 类似于 ...
UnityWebRequest myWr = UnityWebRequest.Get("https://www.myserver.com/foo.txt");

详细信息

此函数将创建 UnityWebRequest 并将目标 URL 设置为字符串参数。此函数不会设置任何其他自定义标志或标头。
默认情况下，此函数将标准 DownloadHandlerBuffer 附加到 UnityWebRequest。此处理程序可缓冲从服务器接收的数据，并在请求完成时将数据提供给脚本。
默认情况下，此函数不会将任何 UploadHandler 附加到 UnityWebRequest。如果需要，可以手动附加。

示例：

using UnityEngine;
using System.Collections;
using UnityEngine.Networking;
 
public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetText());
    }
 
    IEnumerator GetText() {
        UnityWebRequest www = UnityWebRequest.Get("https://www.my-server.com");
        yield return www.SendWebRequest();
 
        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            // 以文本形式显示结果
            Debug.Log(www.downloadHandler.text);
 
            // 或者获取二进制数据形式的结果
            byte[] results = www.downloadHandler.data;
        }
    }
}

3-2、从 HTTP 服务器检索纹理 (GET)

要从远程服务器检索纹理文件，可使用 UnityWebRequest.Texture.。此函数与 UnityWebRequest.GET 非常类似，但进行了优化，可高效下载和存储纹理。

此函数采用单个字符串作为参数。此字符串指定要下载图像文件（以用作纹理）的 URL。

详细信息

此函数将创建 UnityWebRequest 并将目标 URL 设置为字符串参数。此函数不会设置任何其他标志或自定义标头。
此函数将 DownloadHandlerTexture 对象附加到 UnityWebRequest。DownloadHandlerTexture 是一个进行了优化的专用下载处理程序，用于存储要在 Unity 引擎中用作纹理的图像。与下载原始字节并在脚本中手动创建纹理相比，使用此类可显著减少内存重新分配。
默认情况下，此函数不会附加上传处理程序。如果需要，可以手动添加。

示例：

using UnityEngine;
using System.Collections;
using UnityEngine.Networking;
 
public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetTexture());
    }
 
    IEnumerator GetTexture() {
        UnityWebRequest www = UnityWebRequestTexture.GetTexture("https://www.my-server.com/image.png");
        yield return www.SendWebRequest();

        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            Texture myTexture = ((DownloadHandlerTexture)www.downloadHandler).texture;
        }
    }
}

或者也可以使用 helper getter 来实现 GetTexture：

 IEnumerator GetTexture() {
            UnityWebRequest www = UnityWebRequestTexture.GetTexture("https://www.my-server.com/image.png");
            yield return www.SendWebRequest();

            Texture myTexture = DownloadHandlerTexture.GetContent(www);
        }

3-3、从 HTTP 服务器下载 AssetBundle (GET)

要从远程服务器下载 AssetBundle，可使用 UnityWebRequest.GetAssetBundle。此功能将数据串流到内部缓冲区，后者负责在工作线程上解码和解压缩 AssetBundle 的数据。

此函数的参数有多种形式。最简单的形式仅采用一个参数：下载 AssetBundle 时应使用的 URL。您可以选择提供校验和来验证下载数据的完整性。

或者，如果希望使用 AssetBundle 缓存系统，可提供版本号或 Hash128 数据结构。这些值与通过 WWW.LoadFromCacheOrDownload 为旧系统提供的版本号或 Hash128 objects 相同。

详细信息 此函数将创建 UnityWebRequest 并将目标 URL 设置为提供的 URL 参数。此函数还会将 HTTP 动词设置为 GET，但不会设置任何其他标志或自定义标头。此函数将 DownloadHandlerAssetBundle 附加到 UnityWebRequest。此下载处理程序有一个特殊的 assetBundle 属性，一旦下载和解码了足够的数据，便可使用该属性来提取 AssetBundle，从而允许访问 AssetBundle 中的资源。如果提供版本号或 Hash128 对象作为参数，也会将这些参数传递给 DownloadHandlerAssetBundle。下载处理程序随后将采用缓存系统。

示例：

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
 
public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetAssetBundle());
    }
 
    IEnumerator GetAssetBundle() {
        UnityWebRequest www = UnityWebRequestAssetBundle.GetAssetBundle("https://www.my-server.com/myData.unity3d");
        yield return www.SendWebRequest();
 
        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            AssetBundle bundle = DownloadHandlerAssetBundle.GetContent(www);
        }
    }
}

3-4、将表单发送到 HTTP 服务器 (POST)

有两个主要函数可用于将数据作为 HTML 表单格式发送到服务器。如果是从 WWW 系统进行迁移，请参阅下文中的使用 WWWForm。使用 IMultipartFormSection 为了在更大程度上控制表单数据的指定方式，UnityWebRequest 系统包含了一个可由用户实现的 IMultipartFormSection 接口。对于标准应用程序，Unity 还提供了数据和文件部分的默认实现：MultipartFormDataSection 和 MultipartFormFileSection。

UnityWebRequest.POST 的重载可接受成员必须全部是 IMultipartFormSections 的列表参数（作为第二个参数）。函数签名为：

UnityWebRequest.Post(string url, List<IMultipartFormSection> formSections);

详细信息

此函数将创建 UnityWebRequest 并将目标 URL 设置为第一个字符串参数。此函数还会为 IMultipartFormSection 对象列表中所指定的表单数据相应设置 UnityWebRequest 的 Content-Type 标头。
默认情况下，此函数将 DownloadHandlerBuffer 附加到 UnityWebRequest。这是为了方便起见，可用于检查服务器的应答。
类似于 WWWForm POST 函数，此 HLAPI 函数依次调用每个提供的 IMultipartFormSection，然后将它们的格式设置为标准多部分表单（符合 RFC 2616 中的规定）。
已预先设置格式的表单数据存储在标准 UploadHandlerRaw 对象中，此对象随后附加到 UnityWebRequest。因此，在 UnityWebRequest.POST 调用之后对 IMultipartFormSection 对象执行的更改不会反映在发送到服务器的数据中。示例：

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.Collections.Generic;

public class MyBehavior : MonoBehaviour
{
    void Start()
    {
        StartCoroutine(Upload());
    }

    IEnumerator Upload()
    {
        List<IMultipartFormSection> formData = new List<IMultipartFormSection>();
        formData.Add(new MultipartFormDataSection("field1=foo&field2=bar"));
        formData.Add(new MultipartFormFileSection("my file data", "myfile.txt"));

        UnityWebRequest www = UnityWebRequest.Post("https://www.my-server.com/myform", formData);
        yield return www.SendWebRequest();

        if (www.result != UnityWebRequest.Result.Success)
        {
            Debug.Log(www.error);
        }
        else
        {
            Debug.Log("Form upload complete!");
        }
    }
}

3-4-1、使用 WWWForm（旧版函数）

为了帮助从 WWW 系统进行迁移，UnityWebRequest 系统允许使用旧的 WWWForm 对象来提供表单数据。

在这种情况下，函数签名为：

UnityWebRequest.Post(string url, WWWForm formData);

详细信息

此函数创建新的 UnityWebRequest 并将目标 URL 设置为第一个字符串参数的值。此函数还读取由 WWWForm 参数生成的所有自定义标头（比如 Content-Type），然后将这些标头复制到 UnityWebRequest 中。
默认情况下，此函数将 DownloadHandlerBuffer 附加到 UnityWebRequest。这是为了方便起见，可用于检查服务器的应答。
此函数读取由 WWWForm object 生成的原始数据，然后将其缓冲在 UploadHandlerRaw 对象中，此对象附加到 UnityWebRequest。因此，调用 UnityWebRequest.POST 之后对 WWWForm 对象进行的更改不会改变 UnityWebRequest 的内容。

示例：

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
 
public class MyBehavior : MonoBehaviour {
    void Start() {
        StartCoroutine(Upload());
    }
     
    IEnumerator Upload() {
        WWWForm form = new WWWForm();
        form.AddField("myField", "myData");
     
        UnityWebRequest www = UnityWebRequest.Post("https://www.my-server.com/myform", form);
        yield return www.SendWebRequest();
     
        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            Debug.Log("Form upload complete!");
        }
    }
}

3-5、将原始数据上传到 HTTP 服务器 (PUT)

一些现代 Web 应用程序更喜欢通过 HTTP PUT 动词上传文件。针对这种情况，Unity 提供了 UnityWebRequest.PUT 函数。

此函数采用两个参数。第一个参数是一个字符串，用于指定请求的目标 URL。第二个参数是字符串或字节数组，用于指定要发送到服务器的有效负载数据。

函数签名：

WebRequest.Put(string url, string data);
WebRequest.Put(string url, byte[] data);

详细信息

此函数创建 UnityWebRequest 并将内容类型设置为 application/octet-stream。
此函数将标准 DownloadHandlerBuffer 附加到 UnityWebRequest。与 POST 函数一样，此函数可用于从应用程序返回结果数据。
此函数将输入的上传数据存储在标准 UploadHandlerRaw 对象中，然后将此对象附加到 UnityWebRequest。因此，如果使用 byte[] 函数，则在 UnityWebRequest.PUT 调用之后对字节数组执行的更改不会反映在上传到服务器的数据中。

示例：

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
 
public class MyBehavior : MonoBehaviour {
    void Start() {
        StartCoroutine(Upload());
    }
 
    IEnumerator Upload() {
        byte[] myData = System.Text.Encoding.UTF8.GetBytes("This is some test data");
        UnityWebRequest www = UnityWebRequest.Put("https://www.my-server.com/upload", myData);
        yield return www.SendWebRequest();
 
        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            Debug.Log("Upload complete!");
        }
    }
}