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

push_warning

定义

push_warning() 用于向 Godot 编辑器的调试器推送一条警告信息。它的用法和 push_error() 完全一样，唯一的区别是严重程度不同：

• push_error() 表示错误（红色），通常是代码有 bug 或数据有问题
• push_warning() 表示警告（黄色），通常是可能存在隐患但不一定出错的情况

打个比方：push_error() 是消防警报（"着火了，立刻处理！"），push_warning() 是天气预警（"可能下雨，带把伞吧"）。警告不需要立刻处理，但值得注意。

函数签名

C#

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

GDScript

func push_warning(message: String) -> void

参数说明

参数	类型	必需	说明
message	String	是	警告信息的内容。建议写清楚"可能出现什么问题"以及"建议的改进方式"

返回值

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

代码示例

基础用法：推送警告信息

C#

using Godot;

public partial class PushWarningExample : Node
{
    public override void _Ready()
    {
        // 推送一条警告信息到调试器
        GD.PushWarning("音频文件未找到，将使用默认音效");
        // 在编辑器调试器面板中会显示一条黄色警告
    }
}

GDScript

extends Node

func _ready():
    # 推送一条警告信息到调试器
    push_warning("音频文件未找到，将使用默认音效")
    # 在编辑器调试器面板中会显示一条黄色警告

实际场景：弃用 API 和兼容性警告

C#

using Godot;

public partial class AudioManager : Node
{
    private float _volume = 1.0f;

    // 旧版本的音量设置方法（已弃用）
    public void SetVolumeLegacy(float volume)
    {
        GD.PushWarning("SetVolumeLegacy() 已弃用，请改用 SetVolume()");
        _volume = Mathf.Clamp(volume, 0f, 1f);
    }

    // 新版本的音量设置方法
    public void SetVolume(float volume)
    {
        _volume = Mathf.Clamp(volume, 0f, 1f);
    }

    // 检查资源是否过大
    public void LoadTexture(string path)
    {
        var texture = GD.Load<Texture2D>(path);
        if (texture != null && texture.GetWidth() > 4096)
        {
            GD.PushWarning($"纹理 {path} 尺寸过大 ({texture.GetWidth()}x{texture.GetHeight()})，可能影响性能");
        }
    }
}

GDScript

extends Node

var _volume: float = 1.0

# 旧版本的音量设置方法（已弃用）
func set_volume_legacy(volume: float) -> void:
    push_warning("set_volume_legacy() 已弃用，请改用 set_volume()")
    _volume = clampf(volume, 0.0, 1.0)

# 新版本的音量设置方法
func set_volume(volume: float) -> void:
    _volume = clampf(volume, 0.0, 1.0)

# 检查资源是否过大
func load_texture(path: String) -> void:
    var texture = load(path)
    if texture and texture.get_width() > 4096:
        push_warning("纹理 %s 尺寸过大 (%dx%d)，可能影响性能" % [path, texture.get_width(), texture.get_height()])

进阶用法：运行时性能监控警告

C#

using Godot;

public partial class PerformanceMonitor : Node
{
    [Export] public int ExWarningFpsThreshold = 30;

    private double _fpsAccumulator;
    private int _fpsFrameCount;

    public override void _Process(double delta)
    {
        _fpsAccumulator += 1.0 / delta;
        _fpsFrameCount++;

        // 每 60 帧检查一次平均 FPS
        if (_fpsFrameCount >= 60)
        {
            double avgFps = _fpsAccumulator / _fpsFrameCount;

            if (avgFps < ExWarningFpsThreshold)
            {
                GD.PushWarning($"FPS 过低: 平均 {avgFps:F1} FPS（最近 {_fpsFrameCount} 帧），可能存在性能问题");
            }

            _fpsAccumulator = 0;
            _fpsFrameCount = 0;
        }
    }
}

GDScript

extends Node

@export var ex_warning_fps_threshold: int = 30

var _fps_accumulator: float = 0.0
var _fps_frame_count: int = 0

func _process(delta: float) -> void:
    _fps_accumulator += 1.0 / delta
    _fps_frame_count += 1

    # 每 60 帧检查一次平均 FPS
    if _fps_frame_count >= 60:
        var avg_fps = _fps_accumulator / _fps_frame_count

        if avg_fps < ex_warning_fps_threshold:
            push_warning("FPS 过低: 平均 %.1f FPS（最近 %d 帧），可能存在性能问题" % [avg_fps, _fps_frame_count])

        _fps_accumulator = 0.0
        _fps_frame_count = 0

注意事项

1. 与 push_error() 的区别：push_error() 推送红色错误，表示必须修复的问题；push_warning() 推送黄色警告，表示需要注意但不一定会导致程序崩溃的问题。选择哪个取决于问题的严重程度。

2. 在编辑器调试器面板中显示：push_warning() 的输出会在编辑器底部的"调试器"面板中以黄色显示，并且会自动附带脚本名和行号。点击警告条目可以跳转到对应的代码位置。

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

4. 发布版中仍然生效：与 push_error() 一样，push_warning() 在发布版中仍然会执行。