最后同步日期：2026-04-15 | Godot 官方原文 — HTTPRequest

HTTPRequest

节点继承关系

继承链：Node → HTTPRequest

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

让游戏能和互联网上的 Web 服务器对话的"快递员"——你告诉它地址和要送的东西，它跑一趟把结果带回来。

打个比方：你想在游戏里做一个排行榜功能。玩家打完一局，游戏需要把分数"寄"给一个服务器，服务器计算好排名后再把排行榜"寄"回来。HTTPRequest 就是那个帮你跑腿的"快递员"。

什么是 HTTP？

HTTP 是互联网通信的"语言"。你在浏览器里打开一个网页，浏览器就是用 HTTP 协议和服务器对话的。HTTPRequest 节点让你的游戏也能说这种"语言"，从而和 Web 服务器交流。

使用频率：★★★★ 维度专用常用——需要联网功能的游戏（排行榜、云存档、登录验证等）都会用到。

节点用途

• 调用 REST API：获取排行榜数据、查询玩家信息、验证登录
• 下载文件：下载资源包、更新补丁、加载远程图片
• 上传数据：上传分数、提交游戏日志、保存存档到云服务器
• 与后端服务交互：与 Spring Boot、Node.js 等 Web 后端通信

使用场景

典型场景

• 排行榜：上传玩家分数，获取全球排名
• 账号系统：注册、登录、获取用户信息
• 热更新：检查新版本、下载资源补丁
• 云存档：将游戏进度保存到服务器，换设备也能继续玩

不适用场景

• 需要实时多人同步（延迟敏感） → 使用 MultiplayerSpawner + MultiplayerSynchronizer
• 需要和游戏服务器实时通信 → 使用 ENetMultiplayerPeer

常用节点搭配

搭配节点	用途	必需？
JSON 解析（Json 类）	解析服务器返回的 JSON 数据	推荐
Label / RichTextLabel	显示请求结果（排行榜文本等）	可选
TextureRect	显示从服务器下载的图片	可选

典型节点树：

LeaderboardUI (Control)
├── HTTPRequest（负责发送和接收网络请求）
├── VBoxContainer
│   ├── Label（显示"排行榜"标题）
│   └── ItemList（显示排名列表）
└── Timer（定时刷新排行榜）

生效必备素材/资源

资源	类型	说明
目标 API 地址	URL 字符串	请求的服务器地址，如 https://api.example.com/leaderboard
JSON 数据格式说明	文档	需要知道服务器期望接收和返回的数据格式

节点属性与信号

请求配置

属性	类型	默认值	继承自	说明
Timeout	float	0.0	—	超时时间（秒），0 = 使用 ProjectSettings 中的默认值。超过这个时间还没响应就算失败
BodySizeLimit	int	-1	—	响应体大小上限（字节），-1 = 无限制。防止下载太大的数据撑爆内存
MaxRedirects	int	8	—	最大重定向次数
UseTls	bool	true	—	是否使用 TLS 加密（HTTPS）。生产环境强烈建议开启

下载配置

属性	类型	默认值	继承自	说明
DownloadChunkSize	int	65536	—	下载时的分块大小（字节），影响下载进度回调的触发频率
DownloadFile	String	""	—	下载文件的保存路径。设置后，响应体会直接写入文件而非内存

请求头

属性	类型	默认值	继承自	说明
RequestHeaders	PackedStringArray	[]	—	自定义请求头列表，如 ["Content-Type: application/json"]

信号

信号	触发时机	继承自	说明
request_completed(result, response_code, headers, body)	请求完成时（无论成功还是失败）	—	核心信号。result 是请求结果枚举，response_code 是 HTTP 状态码（如 200），headers 是响应头，body 是响应体（字节数组）
request_failed()	请求失败时（如连接超时、DNS 解析失败）	—	比 request_completed 更早触发，专门处理底层网络错误

常用方法

方法	返回值	说明
Request(url)	Error	发送 GET 请求（最简形式，只传网址）
Request(url, customHeaders, method, requestData)	Error	发送完整请求（网址、请求头、请求方法、请求体）
RequestRaw(url, customHeaders, method, rawData)	Error	发送原始数据请求（requestData 是字符串，rawData 是字节数组）
CancelRequest()	void	取消正在进行的请求
GetHttpClientStatus()	枚举	获取当前 HTTP 客户端状态（连接中、请求中、已断开等）

代码示例

C

using Godot;
using System.Text.Json;

/// <summary>
/// 排行榜管理器——演示 HTTPRequest 的 GET 和 POST 请求
/// 节点结构：LeaderboardManager (Node) + HTTPRequest（子节点）
/// </summary>
public partial class LeaderboardManager : Node
{
    private HTTPRequest _httpRequest;
    private string _apiUrl = "https://api.example.com/leaderboard";

    public override void _Ready()
    {
        // 创建 HTTPRequest 节点（也可以在编辑器中添加）
        _httpRequest = new HTTPRequest();
        _httpRequest.Timeout = 10.0f; // 10 秒超时
        _httpRequest.RequestCompleted += OnRequestCompleted;
        AddChild(_httpRequest);
    }

    /// <summary>
    /// 获取排行榜数据（GET 请求）
    /// </summary>
    public void FetchLeaderboard()
    {
        // 发送 GET 请求——就像打开一个网页获取数据
        Error err = _httpRequest.Request(_apiUrl);
        if (err != Error.Ok)
        {
            GD.Print("请求发送失败！");
        }
    }

    /// <summary>
    /// 上传玩家分数（POST 请求）
    /// </summary>
    public void UploadScore(string playerName, int score)
    {
        // 构造要发送的 JSON 数据
        string jsonBody = Json.Stringify(new Godot.Collections.Dictionary
        {
            { "name", playerName },
            { "score", score }
        });

        // 设置请求头：告诉服务器我们发送的是 JSON
        string[] headers = { "Content-Type: application/json" };

        // 发送 POST 请求
        _httpRequest.Request(_apiUrl + "/submit", headers, HTTPClient.Method.Post, jsonBody);
    }

    /// <summary>
    /// 请求完成后的回调——无论成功还是失败都会触发
    /// </summary>
    private void OnRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
    {
        // 检查底层网络请求是否成功
        if (result != (long)HTTPRequest.Result.Success)
        {
            GD.Print($"请求失败！错误码: {result}");
            return;
        }

        // 检查服务器返回的 HTTP 状态码
        // 200 = 成功，404 = 找不到，500 = 服务器内部错误
        if (responseCode != 200)
        {
            GD.Print($"服务器返回错误: {responseCode}");
            return;
        }

        // 把返回的二进制数据转成字符串
        string responseText = System.Text.Encoding.UTF8.GetString(body);
        GD.Print($"收到数据: {responseText}");

        // 解析 JSON
        var json = Json.ParseString(responseText);
        if (json.Variant is Godot.Collections.Array players)
        {
            foreach (var entry in players)
            {
                var player = (Godot.Collections.Dictionary)entry;
                GD.Print($"{player["name"]}: {player["score"]} 分");
            }
        }
    }
}

GDScript

# 排行榜管理器——演示 HTTPRequest 的 GET 和 POST 请求
# 节点结构：LeaderboardManager (Node) + HTTPRequest（子节点）
extends Node

var http_request: HTTPRequest
var api_url: String = "https://api.example.com/leaderboard"

func _ready() -> void:
    # 创建 HTTPRequest 节点（也可以在编辑器中添加）
    http_request = HTTPRequest.new()
    http_request.timeout = 10.0  # 10 秒超时
    http_request.request_completed.connect(_on_request_completed)
    add_child(http_request)

## 获取排行榜数据（GET 请求）
func fetch_leaderboard() -> void:
    # 发送 GET 请求——就像打开一个网页获取数据
    var err = http_request.request(api_url)
    if err != OK:
        print("请求发送失败！")

## 上传玩家分数（POST 请求）
func upload_score(player_name: String, score: int) -> void:
    # 构造要发送的 JSON 数据
    var body = JSON.stringify({
        "name": player_name,
        "score": score
    })

    # 设置请求头：告诉服务器我们发送的是 JSON
    var headers = ["Content-Type: application/json"]

    # 发送 POST 请求
    http_request.request(api_url + "/submit", headers, HTTPClient.METHOD_POST, body)

## 请求完成后的回调——无论成功还是失败都会触发
func _on_request_completed(result: int, response_code: int, _headers: PackedStringArray, body: PackedByteArray) -> void:
    # 检查底层网络请求是否成功
    if result != HTTPRequest.RESULT_SUCCESS:
        print("请求失败！错误码: ", result)
        return

    # 检查服务器返回的 HTTP 状态码
    # 200 = 成功，404 = 找不到，500 = 服务器内部错误
    if response_code != 200:
        print("服务器返回错误: ", response_code)
        return

    # 把返回的二进制数据转成字符串
    var response_text = body.get_string_from_utf8()
    print("收到数据: ", response_text)

    # 解析 JSON
    var json = JSON.parse_string(response_text)
    if json is Array:
        for player in json:
            print(player["name"], ": ", player["score"], " 分")

HTTP 请求方法速查

方法	用途	比喻
GET	获取数据	去图书馆"查"一本书
POST	提交数据	往意见箱里"投"一封信
PUT	更新数据（全量替换）	把旧笔记本"换"成新的
DELETE	删除数据	把废纸"扔"进垃圾桶
PATCH	更新数据（部分修改）	在笔记本上"改"几个字

最常用的是 GET（获取排行榜）和 POST（提交分数）。