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

var_to_bytes

定义

var_to_bytes() 把任意类型的值序列化为一串字节数据（PackedByteArray）。

想象你要寄一件毛衣给远方的朋友。毛衣是立体的，直接塞不进信封里。你需要把它叠好、压缩、装进扁平的快递袋里，才能寄出去。var_to_bytes() 就是这个"折叠打包"的过程：不管你的数据是数字、字符串、数组还是字典，它都能压缩成一段字节数据，方便你保存到文件或者通过网络发送给其他电脑。

寄出去之后，收件人可以用 bytes_to_var() 把快递袋拆开，还原出原来的毛衣。

函数签名

C#

// C# 中可使用 GodotObject 的静态方法
public static byte[] VarToBytes(Variant variable)

// 也可通过 GD 全局访问
byte[] bytes = GD.VarToBytes(myVariant);

GDScript

func var_to_bytes(variable: Variant) -> PackedByteArray

参数说明

参数	类型	必需	说明
variable	Variant	是	要序列化的值，支持数字、字符串、数组、字典等基本数据类型

返回值

PackedByteArray（字节数组）—— 将输入值压缩编码后得到的二进制数据。你可以把它理解为一段"打包好的快递包裹"。

代码示例

C#

using Godot;

public partial class VarToBytesExample : Node
{
    public override void _Ready()
    {
        // 把一个整数打包成字节数组
        int _score = 42;
        byte[] _scoreBytes = GD.VarToBytes(Variant.From(_score));
        GD.Print($"整数 42 打包后字节长度: {_scoreBytes.Length}");

        // 把一个字符串打包
        string _name = "Godot";
        byte[] _nameBytes = GD.VarToBytes(Variant.From(_name));
        GD.Print($"字符串 \"Godot\" 打包后字节长度: {_nameBytes.Length}");

        // 把一个字典打包（最常见的用途：保存游戏数据）
        var _saveData = new Godot.Collections.Dictionary
        {
            ["player_name"] = "勇者",
            ["level"] = 5,
            ["hp"] = 100
        };
        byte[] _dataBytes = GD.VarToBytes(Variant.From(_saveData));
        GD.Print($"存档数据打包后字节长度: {_dataBytes.Length}");

        // 实际使用：保存到文件
        SaveToFile("user://save.dat", _dataBytes);

        // 读取并用 bytes_to_var 还原
        byte[] _loadedBytes = LoadFromFile("user://save.dat");
        var _restored = GD.BytesToVar(Variant.From(_loadedBytes));
        GD.Print($"还原后的存档: {_restored}");
    }

    private void SaveToFile(string path, byte[] data)
    {
        using var file = FileAccess.Open(path, FileAccess.ModeFlags.Write);
        if (file != null)
        {
            file.StoreBuffer(data);
        }
    }

    private byte[] LoadFromFile(string path)
    {
        using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read);
        if (file != null)
        {
            return file.GetBuffer((long)file.GetLength());
        }
        return System.Array.Empty<byte>();
    }
}

GDScript

extends Node

func _ready():
	# 把一个整数打包成字节数组
	var _score = 42
	var _score_bytes = var_to_bytes(_score)
	print("整数 42 打包后字节长度: ", _score_bytes.size())

	# 把一个字符串打包
	var _name = "Godot"
	var _name_bytes = var_to_bytes(_name)
	print("字符串 \"Godot\" 打包后字节长度: ", _name_bytes.size())

	# 把一个字典打包（最常见的用途：保存游戏数据）
	var _save_data = {
		"player_name": "勇者",
		"level": 5,
		"hp": 100
	}
	var _data_bytes = var_to_bytes(_save_data)
	print("存档数据打包后字节长度: ", _data_bytes.size())

	# 实际使用：保存到文件
	_save_to_file("user://save.dat", _data_bytes)

	# 读取并用 bytes_to_var 还原
	var _loaded_bytes = _load_from_file("user://save.dat")
	var _restored = bytes_to_var(_loaded_bytes)
	print("还原后的存档: ", _restored)

func _save_to_file(path: String, data: PackedByteArray) -> void:
	var file = FileAccess.open(path, FileAccess.WRITE)
	if file:
		file.store_buffer(data)
		file.close()

func _load_from_file(path: String) -> PackedByteArray:
	var file = FileAccess.open(path, FileAccess.READ)
	if file:
		var data = file.get_buffer(file.get_length())
		file.close()
		return data
	return PackedByteArray()

注意事项

• var_to_bytes() 只能序列化基本数据类型（数字、字符串、数组、字典等纯数据）。如果你的数据中包含对象引用（比如一个节点实例），序列化时会丢失对象信息。需要序列化包含对象引用的数据时，请使用 var_to_bytes_with_objects()。
• 序列化后的字节数据需要使用对应的 bytes_to_var() 来还原。这两个函数是成对使用的，不能混用其他序列化方式的结果。
• 打包后的字节数据是二进制格式，不适合直接以文本方式查看或编辑。如果需要人类可读的文本格式，请使用 var_to_str() 代替。
• 在 C# 中，调用 GD.VarToBytes() 时需要先将值转换为 Variant 类型，可以使用 Variant.From(value) 来完成转换。