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

error_string

定义

error_string() 用于把一个错误代码（数字）转换成人类能看懂的错误描述（文字）。

Godot 中的很多函数在出错时会返回一个错误代码（比如 13 表示文件找不到），但光看数字很难理解具体是什么问题。error_string() 就像一个翻译器，把数字 13 翻译成 "File not found" 这样的文字。

函数签名

C#

// C# 中没有直接等价函数
// 请使用 Error 枚举的 ToString() 方法
string desc = Error.FileNotFound.ToString();

GDScript

func error_string(error: int) -> String

参数说明

参数	类型	必需	说明
error	int	是	错误代码编号，通常由 Godot 内置函数返回（如 FileAccess.get_open_error()）

返回值

String —— 错误代码对应的人类可读描述字符串。如果错误代码无效，返回空字符串。

代码示例

基础用法：查看错误代码的含义

C#

using Godot;

public partial class ErrorStringExample : Node
{
    public override void _Ready()
    {
        // C# 中直接使用 Error 枚举
        GD.Print(Error.Ok);                    // 运行结果: Ok
        GD.Print(Error.Failed);                // 运行结果: Failed
        GD.Print(Error.FileNotFound);          // 运行结果: FileNotFound
        GD.Print(Error.FileBadPath);           // 运行结果: FileBadPath
    }
}

GDScript

extends Node

func _ready():
    # 常见的错误代码描述
    print(error_string(OK))              # 运行结果: OK
    print(error_string(ERR_FILE_NOT_FOUND))  # 运行结果: File not found
    print(error_string(ERR_CANT_CREATE))     # 运行结果: Can't create
    print(error_string(ERR_BUSY))            # 运行结果: Busy

实际场景：文件操作错误处理

C#

using Godot;

public partial class FileManager : Node
{
    public void LoadConfig(string path)
    {
        using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read);
        if (file == null)
        {
            Error err = FileAccess.GetOpenError();
            GD.PrintErr($"无法打开文件: {path}");
            GD.PrintErr($"错误代码: {(int)err}");
            GD.PrintErr($"错误描述: {err}");
        }
        else
        {
            GD.Print("文件加载成功");
        }
    }

    public override void _Ready()
    {
        LoadConfig("res://nonexistent_file.cfg");
        // 运行结果:
        // 无法打开文件: res://nonexistent_file.cfg
        // 错误代码: 13
        // 错误描述: FileNotFound
    }
}

GDScript

extends Node

func load_config(path: String) -> void:
    var file = FileAccess.open(path, FileAccess.READ)
    if file == null:
        var err = FileAccess.get_open_error()
        push_error("无法打开文件: " + path)
        push_error("错误代码: " + str(err) + "，描述: " + error_string(err))
    else:
        print("文件加载成功")
        file.close()

func _ready():
    load_config("res://nonexistent_file.cfg")
    # 运行结果:
    # 错误: 无法打开文件: res://nonexistent_file.cfg
    # 错误: 错误代码: 13，描述: File not found

进阶用法：通用的错误报告工具

C#

using Godot;

public static class ErrorReporter
{
    public static void ReportError(Error error, string context)
    {
        if (error == Error.Ok) return;

        string severity = error < Error.Failed ? "警告" : "错误";
        GD.PrintErr($"[{severity}] {context}: {error} (代码: {(int)error})");
    }
}

public partial class NetworkClient : Node
{
    public void ConnectToServer()
    {
        // 模拟连接操作
        Error result = Error.ConnectionRefused;

        ErrorReporter.ReportError(result, "连接服务器失败");
        // 运行结果: [错误] 连接服务器失败: ConnectionRefused (代码: 19)
    }

    public override void _Ready()
    {
        ConnectToServer();
    }
}

GDScript

extends Node

func report_error(error: int, context: String) -> void:
    if error == OK:
        return

    var severity = "警告" if error < ERR_FAILED else "错误"
    push_error("[%s] %s: %s (代码: %d)" % [severity, context, error_string(error), error])

func connect_to_server() -> void:
    # 模拟连接操作
    var result = ERR_CONNECTION_REFUSED

    report_error(result, "连接服务器失败")

func _ready():
    connect_to_server()
    # 运行结果: [错误] 连接服务器失败: Connection refused (代码: 19)

注意事项

1. C# 中使用 Error 枚举：C# 中没有 error_string() 函数，但可以使用 Error 枚举值的 .ToString() 方法来获取错误名称，或配合自定义的描述映射来获取详细信息。

2. GDScript 错误常量：GDScript 中可以直接使用错误常量名（如 ERR_FILE_NOT_FOUND），不需要记忆数字代码。error_string() 主要在你收到一个动态的错误代码（比如从某个函数的返回值）时使用。

3. 常见的错误代码：OK（0，成功）、ERR_FAILED（1，通用失败）、ERR_FILE_NOT_FOUND（13，文件未找到）、ERR_FILE_BAD_PATH（14，路径无效）、ERR_CANT_OPEN（16，无法打开）。