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

hash

定义

hash() 用于计算任意值的哈希值。哈希值就像数据的"指纹"——不同的数据几乎总会产生不同的指纹，而相同的数据总会产生相同的指纹。

想象你有一台特殊的扫描仪：你把任何东西放进去（数字、文字、列表等），它都会吐出一串数字。相同的东西放进去两次，吐出来的数字完全一样；不同的东西放进去，吐出来的数字几乎不可能一样。

哈希值的典型用途：

• 快速比较：先比较哈希值（一个数字），比逐项比较整个数据快得多
• 数据校验：检测数据是否被修改（哈希值变了说明数据变了）
• 字典键：Godot 内部用哈希值来实现字典的快速查找

函数签名

C#

// C# 中没有直接等价的全局 hash 函数
// 可使用 Variant 的 Hash 方法
uint hash = someVariant.Hash();
// 或使用 .NET 的 GetHashCode()
int hash = someObject.GetHashCode();

GDScript

func hash(variable: Variant) -> int

参数说明

参数	类型	必需	说明
variable	Variant	是	要计算哈希值的任意值，支持所有 Godot 数据类型

返回值

int —— 一个整数哈希值。相同的数据总是返回相同的哈希值；不同的数据通常返回不同的哈希值（但极小概率会冲突）。

代码示例

基础用法：计算哈希值

C#

using Godot;

public partial class HashExample : Node
{
    public override void _Ready()
    {
        // 相同的值产生相同的哈希
        int hash1 = "Hello".GetHashCode();
        int hash2 = "Hello".GetHashCode();
        GD.Print($"\"Hello\" 的哈希: {hash1}");
        GD.Print($"再次 \"Hello\" 的哈希: {hash2}");
        GD.Print($"相同? {hash1 == hash2}");
        // 运行结果: 相同? True

        // 不同的值产生不同的哈希
        int hash3 = "World".GetHashCode();
        GD.Print($"\"World\" 的哈希: {hash3}");
        GD.Print($"与 \"Hello\" 相同? {hash1 == hash3}");
        // 运行结果: 与 "Hello" 相同? False
    }
}

GDScript

extends Node

func _ready():
    # 相同的值产生相同的哈希
    var hash1 = hash("Hello")
    var hash2 = hash("Hello")
    print("\"Hello\" 的哈希: ", hash1)
    print("再次 \"Hello\" 的哈希: ", hash2)
    print("相同? ", hash1 == hash2)
    # 运行结果: 相同? True

    # 不同的值产生不同的哈希
    var hash3 = hash("World")
    print("\"World\" 的哈希: ", hash3)
    print("与 \"Hello\" 相同? ", hash1 == hash3)
    # 运行结果: 与 "Hello" 相同? False

实际场景：检测存档是否被修改

C#

using Godot;

public partial class SaveValidator : Node
{
    private int ComputeSaveHash(Godot.Collections.Dictionary saveData)
    {
        // 计算存档数据的哈希值
        return saveData.ToString().GetHashCode();
    }

    public void SaveWithChecksum()
    {
        var saveData = new Godot.Collections.Dictionary
        {
            ["player_name"] = "勇者",
            ["level"] = 5,
            ["gold"] = 999
        };

        int checksum = ComputeSaveHash(saveData);
        saveData["checksum"] = checksum;

        GD.Print($"存档保存完毕，校验值: {checksum}");
    }

    public void LoadAndVerify(Godot.Collections.Dictionary loadedData)
    {
        int savedChecksum = (int)loadedData["checksum"];
        loadedData.Remove("checksum");

        int currentChecksum = ComputeSaveHash(loadedData);

        if (currentChecksum == savedChecksum)
        {
            GD.Print("存档校验通过，数据未被篡改");
        }
        else
        {
            GD.PrintErr("存档校验失败！数据可能被篡改");
        }
    }
}

GDScript

extends Node

func compute_save_hash(save_data: Dictionary) -> int:
    # 计算存档数据的哈希值
    return hash(save_data)

func save_with_checksum() -> void:
    var save_data = {
        "player_name": "勇者",
        "level": 5,
        "gold": 999
    }

    var checksum = compute_save_hash(save_data)
    save_data["checksum"] = checksum

    print("存档保存完毕，校验值: ", checksum)

func load_and_verify(loaded_data: Dictionary) -> void:
    var saved_checksum = loaded_data["checksum"]
    loaded_data.erase("checksum")

    var current_checksum = compute_save_hash(loaded_data)

    if current_checksum == saved_checksum:
        print("存档校验通过，数据未被篡改")
    else:
        push_error("存档校验失败！数据可能被篡改")

进阶用法：快速比较复杂对象

C#

using Godot;

public partial class FastCompare : Node
{
    public override void _Ready()
    {
        var config1 = new Godot.Collections.Dictionary
        {
            ["resolution_x"] = 1920,
            ["resolution_y"] = 1080,
            ["fullscreen"] = true,
            ["volume"] = 0.8f
        };

        var config2 = new Godot.Collections.Dictionary
        {
            ["resolution_x"] = 1920,
            ["resolution_y"] = 1080,
            ["fullscreen"] = true,
            ["volume"] = 0.8f
        };

        var config3 = new Godot.Collections.Dictionary
        {
            ["resolution_x"] = 1280,
            ["resolution_y"] = 720,
            ["fullscreen"] = false,
            ["volume"] = 0.5f
        };

        // 用哈希值快速判断两个配置是否相同
        int hash1 = config1.ToString().GetHashCode();
        int hash2 = config2.ToString().GetHashCode();
        int hash3 = config3.ToString().GetHashCode();

        GD.Print($"config1 == config2 (哈希): {hash1 == hash2}");   // True
        GD.Print($"config1 == config3 (哈希): {hash1 == hash3}");   // False
    }
}

GDScript

extends Node

func _ready():
    var config1 = {
        "resolution_x": 1920,
        "resolution_y": 1080,
        "fullscreen": true,
        "volume": 0.8
    }

    var config2 = {
        "resolution_x": 1920,
        "resolution_y": 1080,
        "fullscreen": true,
        "volume": 0.8
    }

    var config3 = {
        "resolution_x": 1280,
        "resolution_y": 720,
        "fullscreen": false,
        "volume": 0.5
    }

    # 用哈希值快速判断两个配置是否相同
    var hash1 = hash(config1)
    var hash2 = hash(config2)
    var hash3 = hash(config3)

    print("config1 == config2 (哈希): ", hash1 == hash2)   # True
    print("config1 == config3 (哈希): ", hash1 == hash3)   # False

注意事项

1. 哈希冲突：虽然不同的数据几乎总是产生不同的哈希值，但理论上存在极小概率的"冲突"——两个不同的数据碰巧产生相同的哈希值。因此，哈希值适合用于快速筛选和辅助判断，但不能完全替代精确比较。

2. 不适合加密：hash() 使用的是非加密哈希算法，速度快但不安全。如果需要安全地存储密码或验证数据完整性（防篡改），请使用加密哈希函数（如 SHA-256）。

3. C# 中的替代：C# 中可以使用对象的 .GetHashCode() 方法或 Variant.Hash() 来计算哈希值。

4. 对象类型的哈希：对于对象（如节点、资源），哈希值基于对象的引用而非内容。两个内容相同但不同的对象实例，哈希值可能不同。