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

print_debug

定义

print_debug() 和 print() 的作用几乎一样，都是把信息打印到控制台。但它有一个特殊能力：只有在调试模式下运行时才会输出信息。

打个比方：print() 像是一个永远开着的大喇叭，不管什么场合都在喊；print_debug() 像是一个只有在排练时才响的对讲机——正式演出（发布版）时自动静音。这样你就不用在发布游戏前手动删除调试输出了。

具体来说，当你从编辑器运行游戏（F5/F6）时，print_debug() 会正常输出；当你导出游戏给玩家时，print_debug() 的所有输出都会被自动忽略。

函数签名

C#

// C# 中没有直接等价的 print_debug 函数
// 可用条件编译实现类似效果：
#if DEBUG
    GD.Print(values);
#endif

GDScript

func print_debug(...) -> void

参数说明

参数	类型	必需	说明
...（可变参数）	Variant（任意类型）	否	可以传入任意数量、任意类型的值，行为与 print() 完全相同，但仅在调试模式下输出

返回值

无返回值（void）。此函数仅用于在控制台输出信息。

代码示例

基础用法：调试模式下输出

C#

using Godot;
using System.Diagnostics;

public partial class PrintDebugExample : Node
{
    public override void _Ready()
    {
        // 普通输出：无论什么模式都会打印
        GD.Print("这条消息总会显示");

        // 调试输出：仅在 DEBUG 模式下打印
#if DEBUG
        GD.Print("这条消息仅在调试模式下显示");
#endif
        // 运行结果（编辑器中运行）:
        // 这条消息总会显示
        // 这条消息仅在调试模式下显示
        //
        // 运行结果（导出发布版）:
        // 这条消息总会显示
    }
}

GDScript

extends Node

func _ready():
    # 普通输出：无论什么模式都会打印
    print("这条消息总会显示")

    # 调试输出：仅在调试模式下打印
    print_debug("这条消息仅在调试模式下显示")

    # 运行结果（编辑器中运行）:
    # 这条消息总会显示
    # 这条消息仅在调试模式下显示
    #
    # 运行结果（导出发布版）:
    # 这条消息总会显示

实际场景：安全的调试输出

C#

using Godot;
using System.Diagnostics;

public partial class Enemy : CharacterBody2D
{
    [Export] public int ExMaxHealth = 50;

    private int _currentHealth;

    public override void _Ready()
    {
        _currentHealth = ExMaxHealth;
    }

    public void TakeDamage(int amount)
    {
        _currentHealth -= amount;

        // 使用条件编译的调试输出，发布版自动移除
#if DEBUG
        GD.Print($"[DEBUG] 敌人受到 {amount} 点伤害，剩余生命: {_currentHealth}");
#endif

        if (_currentHealth <= 0)
        {
            Die();
        }
    }

    private void Die()
    {
#if DEBUG
        GD.Print("[DEBUG] 敌人已死亡");
#endif
        QueueFree();
    }
}

GDScript

extends CharacterBody2D

@export var ex_max_health: int = 50

var _current_health: int

func _ready():
    _current_health = ex_max_health

func take_damage(amount: int) -> void:
    _current_health -= amount

    # 使用 print_debug，导出发布版时自动静音
    print_debug("[DEBUG] 敌人受到 %d 点伤害，剩余生命: %d" % [amount, _current_health])

    if _current_health <= 0:
        die()

func die() -> void:
    print_debug("[DEBUG] 敌人已死亡")
    queue_free()

进阶用法：封装调试日志工具

C#

using Godot;
using System.Diagnostics;

public static class DebugLog
{
    // 封装一个带标签的调试日志方法
    [Conditional("DEBUG")]
    public static void Info(string tag, string message)
    {
        GD.Print($"[{tag}] {message}");
    }

    [Conditional("DEBUG")]
    public static void Warn(string tag, string message)
    {
        GD.Print($"[{tag}] [警告] {message}");
    }
}

public partial class GameManager : Node
{
    public override void _Ready()
    {
        DebugLog.Info("GameManager", "游戏初始化开始");
        DebugLog.Info("GameManager", "加载关卡数据...");
        DebugLog.Warn("GameManager", "缺少音效配置，使用默认值");
    }
}

GDScript

extends Node

# 封装一个带标签的调试日志方法
func debug_log(tag: String, message: String) -> void:
    print_debug("[%s] %s" % [tag, message])

func debug_warn(tag: String, message: String) -> void:
    print_debug("[%s] [警告] %s" % [tag, message])

func _ready():
    debug_log("GameManager", "游戏初始化开始")
    debug_log("GameManager", "加载关卡数据...")
    debug_warn("GameManager", "缺少音效配置，使用默认值")

注意事项

1. "调试模式"是什么意思：从 Godot 编辑器按 F5 或 F6 运行游戏时就是调试模式。导出游戏（Project > Export）生成的发布版本不是调试模式，print_debug() 的输出会被自动跳过。

2. C# 使用条件编译：C# 中没有 print_debug() 的直接等价。推荐使用 #if DEBUG ... #endif 条件编译指令或 [Conditional("DEBUG")] 特性来实现相同效果。

3. 发布版性能优势：使用 print_debug() 而非 print() 的好处是，你不需要在发布前手动删除调试代码，发布版中这些调用会被完全跳过，不会消耗任何性能。