简述一下Unity的UnityWebRequest

原创最新推荐文章于 2026-07-09 08:30:37 发布 2.3k 阅读 AI写同款

收录于

Unity杂七杂八

枫景Maple

码龄2年墨衍会员 · AI 创作全网分发

485粉丝100篇原创

关注

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

AI摘要

本文介绍了Unity引擎中的网络请求工具UnityWebRequest。它比旧版WWW类更灵活高效，支持多种HTTP方法。文中阐述了HTTP请求与响应原理，详解了UnityWebRequest的作用、API，给出发送GET、POST请求及下载文件的示例，还提及使用时的注意事项。

UnityWebRequest是Unity引擎中用于处理网络请求的强大工具，尤其适用于与Web服务器进行交互，比如获取数据、上传文件或下载资源等。相较于旧版的WWW类，UnityWebRequest提供了更灵活、更高效的API，支持多种HTTP方法，并能处理复杂的网络操作。本文将以简单易懂的方式详细介绍UnityWebRequest的作用、基本用法、API详解以及使用注意事项，帮助你快速掌握这一重要工具。

引言

在现代游戏开发中，与服务器的交互是不可或缺的一部分。无论是获取游戏配置、上传玩家数据，还是下载资源包，网络请求都扮演着关键角色。UnityWebRequest作为Unity官方推荐的网络请求工具，提供了强大的功能来处理这些任务。相较于旧版的WWW类，UnityWebRequest不仅性能更优，还支持更多HTTP方法和自定义操作，适用于各种复杂的网络场景。

本文将从基础概念入手，逐步深入，带你全面了解UnityWebRequest的用法和优势。

基本概念

HTTP请求与响应

在介绍UnityWebRequest之前，简单了解HTTP（超文本传输协议）的工作原理是必要的。HTTP是Web上最常用的协议之一，用于客户端（如游戏）与服务器之间的通信。HTTP请求通常包括以下部分：

方法：如GET（获取数据）、POST（提交数据）、PUT（更新数据）、DELETE（删除数据）等。
URL：请求的目标地址。
请求头：包含元数据，如内容类型、认证信息等。
请求体：POST或PUT请求中附带的数据。

服务器在接收到请求后，会返回一个HTTP响应，包含：

状态码：如200（成功）、404（未找到）、500（服务器错误）等。
响应头：包含元数据。
响应体：服务器返回的数据。

UnityWebRequest的作用

UnityWebRequest是Unity封装的一个类，用于在Unity中发送HTTP请求并处理响应。它支持：

多种HTTP方法：GET、POST、PUT、DELETE等。
上传和下载文件。
自定义请求头和请求体。
处理重定向、认证和SSL证书。

相较于旧版的WWW类，UnityWebRequest提供了更细粒度的控制，支持异步操作，且在性能上有所提升。

API详解

UnityWebRequest提供了丰富的API，下面将介绍其主要类和方法。

主要类

UnityWebRequest：核心类，用于创建和管理网络请求。
DownloadHandler：用于处理下载的数据，例如：
- DownloadHandlerBuffer：将数据下载到内存。
- DownloadHandlerFile：将数据下载到文件。
UploadHandler：用于处理上传的数据，例如：
- UploadHandlerRaw：上传原始字节数据。

常用方法

UnityWebRequest.Get(string url)：创建一个GET请求。
UnityWebRequest.Post(string url, string postData)：创建一个POST请求，支持字符串或WWWForm数据。
UnityWebRequest.Put(string url, byte[] bodyData)：创建一个PUT请求。
UnityWebRequest.Delete(string url)：创建一个DELETE请求。
UnityWebRequest.SendWebRequest()：发送请求并返回一个UnityWebRequestAsyncOperation对象，用于异步操作。

属性

isDone：请求是否完成。
responseCode：HTTP响应状态码。
downloadHandler：用于获取下载的数据。
uploadHandler：用于设置上传的数据。
timeout：设置请求的超时时间（单位：秒）。

使用示例

下面通过几个实际代码示例，展示UnityWebRequest的常见用法。

示例1：发送GET请求

以下是一个简单的GET请求示例，用于从服务器获取文本数据。

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

public class GetRequestExample : MonoBehaviour
{
    void Start()
    {
        StartCoroutine(GetText());
    }

    IEnumerator GetText()
    {
        using (UnityWebRequest www = UnityWebRequest.Get("https://example.com/data"))
        {
            yield return www.SendWebRequest();

            if (www.result == UnityWebRequest.Result.Success)
            {
                Debug.Log("获取数据成功: " + www.downloadHandler.text);
            }
            else
            {
                Debug.LogError("请求失败: " + www.error);
            }
        }
    }
}

说明：

使用UnityWebRequest.Get创建一个GET请求。
通过SendWebRequest发送请求，并使用yield return等待请求完成。
检查result属性判断请求是否成功，成功则输出下载的文本数据。

示例2：发送POST请求

以下是一个POST请求示例，用于向服务器提交表单数据。

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

public class PostRequestExample : MonoBehaviour
{
    void Start()
    {
        StartCoroutine(PostData());
    }

    IEnumerator PostData()
    {
        WWWForm form = new WWWForm();
        form.AddField("username", "player1");
        form.AddField("score", 100);

        using (UnityWebRequest www = UnityWebRequest.Post("https://example.com/submit", form))
        {
            yield return www.SendWebRequest();

            if (www.result == UnityWebRequest.Result.Success)
            {
                Debug.Log("提交成功: " + www.downloadHandler.text);
            }
            else
            {
                Debug.LogError("提交失败: " + www.error);
            }
        }
    }
}

说明：

使用WWWForm类创建表单数据。
使用UnityWebRequest.Post发送POST请求。
其余步骤与GET请求类似。

示例3：下载文件

UnityWebRequest还支持下载文件到本地，以下是一个下载图片的示例。

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.IO;

public class DownloadFileExample : MonoBehaviour
{
    void Start()
    {
        StartCoroutine(DownloadImage());
    }

    IEnumerator DownloadImage()
    {
        string url = "https://example.com/image.png";
        string savePath = Path.Combine(Application.persistentDataPath, "image.png");

        using (UnityWebRequest www = UnityWebRequest.Get(url))
        {
            www.downloadHandler = new DownloadHandlerFile(savePath);
            yield return www.SendWebRequest();

            if (www.result == UnityWebRequest.Result.Success)
            {
                Debug.Log("图片下载成功，保存到: " + savePath);
            }
            else
            {
                Debug.LogError("下载失败: " + www.error);
            }
        }
    }
}

说明：

使用DownloadHandlerFile将下载的数据直接保存到文件。
指定保存路径并发送请求。

注意事项

在使用UnityWebRequest时，有一些重要的事项需要注意：

永远异步: 坚持在协程中使用 yield return webRequest.SendWebRequest() 和等待循环。
必须 Dispose: 牢记使用 using 语句或在 finally 块中手动调用 webRequest.Dispose()。
健壮的错误处理: 总是检查 webRequest.result 并处理各种错误情况。考虑网络不稳定、服务器错误、数据格式错误等。
超时设置: 通过 webRequest.timeout (单位：秒) 设置合理的超时时间，防止请求无限期挂起。
HTTPS: 尽可能使用 HTTPS (即 https:// 开头的 URL) 来保证通信安全。
大文件处理: 下载大文件时，考虑使用 DownloadHandlerFile 直接写入磁盘，避免内存暴涨。上传大文件时，UploadHandlerFile 也很有用。可以检查 webRequest.downloadProgress 或 webRequest.uploadProgress 来显示进度条。
关注服务器负载: 不要在短时间内发送大量请求，尊重服务器的速率限制 (Rate Limiting)。
平台差异: 虽然 UWR 跨平台性很好，但在特定平台（如 WebGL）可能会有一些细微的行为差异或限制，需要查阅文档或进行测试。