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

push_error

定义

push_error() 用于向 Godot 编辑器的调试器推送一条错误信息。和 printerr() 不同的是，push_error() 会在编辑器底部的"调试器"面板中生成一条可点击的错误条目，点击后可以直接跳转到对应的代码行。

打个比方：printerr() 像是在纸上写下错误信息，你看到了但不知道问题出在哪里。push_error() 像是在纸上写错误信息的同时，还附上了一个"定位器"——点击就能直接跳到出错的位置，告诉你"就是这行代码出了问题"。

此外，push_error() 还会在消息前自动加上出错的脚本名和行号，让调试更方便。

函数签名

C#

// C# 中使用 GD.PushError
GD.PushError(string message);

GDScript

func push_error(message: String) -> void

参数说明

参数	类型	必需	说明
message	String	是	错误信息的内容。建议写清楚"什么出错了"以及"期望的正确值是什么"

返回值

无返回值（void）。此函数仅用于在编辑器调试器中推送错误信息。

代码示例

基础用法：推送错误信息

C#

using Godot;

public partial class PushErrorExample : Node
{
    public override void _Ready()
    {
        // 推送一条错误信息到调试器
        GD.PushError("配置文件加载失败：文件路径无效");
        // 在编辑器调试器面板中会显示一条红色错误
        // 点击可跳转到这行代码
    }
}

GDScript

extends Node

func _ready():
    # 推送一条错误信息到调试器
    push_error("配置文件加载失败：文件路径无效")
    # 在编辑器调试器面板中会显示一条红色错误
    # 点击可跳转到这行代码

实际场景：参数校验

C#

using Godot;

public partial class DamageCalculator : Node
{
    public int CalculateDamage(int baseDamage, float multiplier)
    {
        // 参数校验：如果传入无效值，推送错误
        if (baseDamage < 0)
        {
            GD.PushError($"基础伤害不能为负数，当前值: {baseDamage}");
            return 0;
        }

        if (multiplier < 0f)
        {
            GD.PushError($"伤害倍率不能为负数，当前值: {multiplier}");
            return 0;
        }

        return (int)(baseDamage * multiplier);
    }

    public override void _Ready()
    {
        // 正常调用
        GD.Print($"伤害: {CalculateDamage(50, 1.5f)}");
        // 运行结果: 伤害: 75

        // 异常调用：触发错误
        GD.Print($"伤害: {CalculateDamage(-10, 2.0f)}");
        // 调试器面板显示: 基础伤害不能为负数，当前值: -10
        // 运行结果: 伤害: 0
    }
}

GDScript

extends Node

func calculate_damage(base_damage: int, multiplier: float) -> int:
    # 参数校验：如果传入无效值，推送错误
    if base_damage < 0:
        push_error("基础伤害不能为负数，当前值: %d" % base_damage)
        return 0

    if multiplier < 0.0:
        push_error("伤害倍率不能为负数，当前值: %f" % multiplier)
        return 0

    return int(base_damage * multiplier)

func _ready():
    # 正常调用
    print("伤害: ", calculate_damage(50, 1.5))
    # 运行结果: 伤害: 75

    # 异常调用：触发错误
    print("伤害: ", calculate_damage(-10, 2.0))
    # 调试器面板显示: 基础伤害不能为负数，当前值: -10
    # 运行结果: 伤害: 0

进阶用法：完整的错误处理框架

C#

using Godot;

public static class Guard
{
    // 断言工具：条件不满足时推送错误
    public static bool Assert(bool condition, string message)
    {
        if (!condition)
        {
            GD.PushError($"断言失败: {message}");
        }
        return condition;
    }

    // 空值检查：为空时推送错误
    public static bool NotNull(object obj, string paramName)
    {
        if (obj == null)
        {
            GD.PushError($"参数 '{paramName}' 不能为 null");
            return false;
        }
        return true;
    }

    // 范围检查：超出范围时推送错误
    public static bool InRange(float value, float min, float max, string paramName)
    {
        if (value < min || value > max)
        {
            GD.PushError($"参数 '{paramName}' 的值 {value} 不在有效范围 [{min}, {max}] 内");
            return false;
        }
        return true;
    }
}

public partial class Player : CharacterBody2D
{
    [Export] public float ExMoveSpeed = 200f;
    [Export] public float ExMaxHealth = 100f;

    private float _currentHealth;

    public override void _Ready()
    {
        Guard.InRange(ExMoveSpeed, 0f, 1000f, "ExMoveSpeed");
        Guard.InRange(ExMaxHealth, 1f, 99999f, "ExMaxHealth");

        _currentHealth = ExMaxHealth;
    }
}

GDScript

extends CharacterBody2D

@export var ex_move_speed: float = 200.0
@export var ex_max_health: float = 100.0

var _current_health: float

# 断言工具：条件不满足时推送错误
func _assert(condition: bool, message: String) -> bool:
    if not condition:
        push_error("断言失败: " + message)
    return condition

# 范围检查：超出范围时推送错误
func _check_range(value: float, min_val: float, max_val: float, param_name: String) -> bool:
    if value < min_val or value > max_val:
        push_error("参数 '%s' 的值 %s 不在有效范围 [%s, %s] 内" % [param_name, value, min_val, max_val])
        return false
    return true

func _ready():
    _check_range(ex_move_speed, 0.0, 1000.0, "ex_move_speed")
    _check_range(ex_max_health, 1.0, 99999.0, "ex_max_health")

    _current_health = ex_max_health

注意事项

1. 与 printerr() 的区别：printerr() 只是输出错误文本到控制台；push_error() 不仅输出到控制台，还在编辑器的"调试器"面板中生成一条可点击、可追溯的错误记录。在开发阶段，推荐使用 push_error() 来报告错误。

2. 自动附加位置信息：push_error() 会自动在错误消息前附加当前脚本名和行号，比如 player.gd:25: 基础伤害不能为负数，方便快速定位问题。

3. C# 中使用 GD.PushError()：C# 中对应的函数是 GD.PushError()，行为一致。

4. 发布版中仍然生效：与 print_debug() 不同，push_error() 在发布版中仍然会执行。如果不想在发布版中触发，请自行添加条件判断。