最后更新日期：2026-04-16

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

JSON.parse

定义

JSON.parse 把一段 JSON 格式的文本字符串"翻译"成 Godot 可以直接使用的数据——比如字典、数组、数字等。

打个比方：你收到一封用密码写的信。JSON 字符串就是那封"密码信"，而 Parse() 就是帮你解码翻译的人。比如收到 '{"name": "小明", "age": 18}' 这样的字符串，经过 Parse() 后，你就得到了一个可以直接用 data["name"] 访问的字典。

在游戏开发中，这个功能常用于：读取保存的配置文件、解析服务器返回的数据、加载关卡描述文件等。

函数签名

C#

// Json.ParseString 将 JSON 字符串解析为 Godot 数据（静态方法）
public static Variant ParseString(string jsonString)

GDScript

static func parse_string(json_string: String) -> Variant

参数说明

参数	类型	必需	说明
jsonString	String	是	要解析的 JSON 格式字符串

返回值

Variant —— 解析成功时返回对应的 Godot 数据类型：

• JSON 对象 {} → Dictionary
• JSON 数组 [] → Array
• JSON 字符串 → String
• JSON 数字（整数）→ int
• JSON 数字（小数）→ float
• JSON true/false → bool
• JSON null → Variant(null)

解析失败时返回 null。

代码示例

基础用法：解析简单的 JSON 对象

C#

using Godot;

public partial class MyScene : Node
{
    public override void _Ready()
    {
        string jsonText = "{\"name\": \"小明\", \"age\": 18, \"score\": 95.5}";

        var result = Json.ParseString(jsonText);

        if (result.VariantType == Variant.Type.Dictionary)
        {
            var data = result.AsGodotDictionary();
            GD.Print($"姓名: {data["name"]}");
            // 运行结果: 姓名: 小明
            GD.Print($"年龄: {data["age"]}");
            // 运行结果: 年龄: 18
            GD.Print($"分数: {data["score"]}");
            // 运行结果: 分数: 95.5
        }
    }
}

GDScript

extends Node

func _ready():
    var json_text = '{"name": "小明", "age": 18, "score": 95.5}'

    var result = JSON.parse_string(json_text)

    if result != null:
        print("姓名: ", result["name"])
        # 运行结果: 姓名: 小明
        print("年龄: ", result["age"])
        # 运行结果: 年龄: 18
        print("分数: ", result["score"])
        # 运行结果: 分数: 95.5

实际场景：读取存档文件

C#

using Godot;

public partial class SaveManager : Node
{
    public void LoadSave(string filePath)
    {
        if (!FileAccess.FileExists(filePath))
        {
            GD.Print("存档文件不存在");
            return;
        }

        var file = FileAccess.Open(filePath, FileAccess.ModeFlags.Read);
        string jsonText = file.GetAsText();
        file.Close();

        var result = Json.ParseString(jsonText);

        if (result.VariantType == Variant.Type.Dictionary)
        {
            var saveData = result.AsGodotDictionary();

            string playerName = (string)saveData["player_name"];
            int level = (int)saveData["level"];
            float health = (float)saveData["health"];

            GD.Print($"读取存档: {playerName}, 等级 {level}, 血量 {health}");
            // 运行结果: 读取存档: 勇者, 等级 12, 血量 85
        }
        else
        {
            GD.PrintErr("存档数据格式错误");
            // 运行结果: 存档数据格式错误
        }
    }
}

GDScript

extends Node

func load_save(file_path: String):
    if not FileAccess.file_exists(file_path):
        print("存档文件不存在")
        return

    var file = FileAccess.open(file_path, FileAccess.READ)
    var json_text = file.get_as_text()
    file.close()

    var result = JSON.parse_string(json_text)

    if result != null:
        var player_name = result["player_name"]
        var level = result["level"]
        var health = result["health"]

        print("读取存档: %s, 等级 %d, 血量 %.0f" % [player_name, level, health])
        # 运行结果: 读取存档: 勇者, 等级 12, 血量 85
    else:
        push_error("存档数据格式错误")
        # 运行结果: 存档数据格式错误

进阶用法：解析嵌套 JSON 和数组

C#

using Godot;

public partial class LevelLoader : Node
{
    public override void _Ready()
    {
        string jsonText = @"{
            ""level_name"": ""第一关"",
            ""enemies"": [
                {""type"": ""skeleton"", ""hp"": 30},
                {""type"": ""goblin"", ""hp"": 20},
                {""type"": ""dragon"", ""hp"": 200}
            ],
            ""rewards"": {""gold"": 500, ""exp"": 100}
        }";

        var result = Json.ParseString(jsonText);
        var data = result.AsGodotDictionary();

        GD.Print($"关卡: {data["level_name"]}");
        // 运行结果: 关卡: 第一关

        // 遍历敌人列表
        var enemies = data["enemies"].AsGodotArray();
        foreach (var enemy in enemies)
        {
            var enemyData = enemy.AsGodotDictionary();
            GD.Print($"  敌人: {enemyData["type"]}, 血量: {enemyData["hp"]}");
        }
        // 运行结果:
        //   敌人: skeleton, 血量: 30
        //   敌人: goblin, 血量: 20
        //   敌人: dragon, 血量: 200

        // 获取嵌套的奖励信息
        var rewards = data["rewards"].AsGodotDictionary();
        GD.Print($"奖励: {rewards["gold"]} 金币, {rewards["exp"]} 经验");
        // 运行结果: 奖励: 500 金币, 100 经验
    }
}

GDScript

extends Node

func _ready():
    var json_text = """{
        "level_name": "第一关",
        "enemies": [
            {"type": "skeleton", "hp": 30},
            {"type": "goblin", "hp": 20},
            {"type": "dragon", "hp": 200}
        ],
        "rewards": {"gold": 500, "exp": 100}
    }"""

    var data = JSON.parse_string(json_text)

    print("关卡: ", data["level_name"])
    # 运行结果: 关卡: 第一关

    # 遍历敌人列表
    for enemy in data["enemies"]:
        print("  敌人: %s, 血量: %d" % [enemy["type"], enemy["hp"]])
    # 运行结果:
    #   敌人: skeleton, 血量: 30
    #   敌人: goblin, 血量: 20
    #   敌人: dragon, 血量: 200

    # 获取嵌套的奖励信息
    var rewards = data["rewards"]
    print("奖励: %d 金币, %d 经验" % [rewards["gold"], rewards["exp"]])
    # 运行结果: 奖励: 500 金币, 100 经验

注意事项

• 解析失败返回 null：如果 JSON 字符串格式不正确（比如少了引号、多了逗号），ParseString() 会返回 null。记得检查返回值。
• JSON 的键必须用双引号：JSON 标准要求键名用双引号包裹，不能用单引号。{'name': 'test'} 是无效的 JSON，必须是 {"name": "test"}。
• Godot 4.x 使用 ParseString 静态方法：不同于 Godot 3.x，Godot 4.x 中推荐使用 JSON.ParseString() 静态方法，不需要先创建 JSON 对象。
• 数字类型区分：JSON 中没有整数和浮点数的区分，Godot 会自动判断。如果数字没有小数点就是 int，有小数点就是 float。