游戏引擎 / 系统课时

统一运行时日志入口

统一运行时日志入口

当存档读取失败或场景初始化顺序异常时,零散的 Debug.Log 往往缺少定位线索。本课把运行时日志收敛到一个入口,统一严重级别、模块、事件编号、场景和对象上下文,并验证哪些消息应该出现在开发版与正式发布版。

学习目标

  • 为信息、警告和错误制定可执行的分级规则。
  • 编写带事件编号与 Unity 对象上下文的日志封装。
  • 在 Console 验证输出,并避免日志泄露与刷屏。

先确定日志必须回答什么

一条有用的运行时日志,至少要回答「哪个模块、发生什么事件、在哪个场景、影响哪个对象」。建议把字段固定为 level、module、eventId、scene、detail,另用 Unity 的 context 参数关联场景对象。事件编号应稳定,例如 save.read.failed,不要把会变化的错误句子当作编号。

级别 使用条件 典型事件
Info 正常流程的开发诊断 场景初始化完毕
Warning 出现异常但已有回退方案 缺少自定义设置,使用默认值
Error 核心操作失败,需要排查 存档解析失败且无法恢复

警告并不等于每条提示都要升级。首次进入游戏没有旧存档往往属于正常分支;只有这种缺失会影响预期行为,或确实发生回退时,才有必要记录警告。

封装统一入口

在 Assets/Scripts/RuntimeLogDemo.cs 创建下列完整脚本,并挂到当前场景中的一个 GameObject。GameLog 只负责格式化与分级,调用方提供业务事件;传入 this 作为上下文后,点击 Console 中的消息能定位关联的组件。

csharp
using UnityEngine;
using UnityEngine.SceneManagement;

public static class GameLog
{
    private static string Describe(string level, string module, string eventId, string detail)
    {
        string scene = SceneManager.GetActiveScene().name;
        return $"[{level}][{module}][{eventId}] scene={scene} {detail}";
    }

    public static void Info(string module, string eventId, string detail, Object context = null)
    {
#if UNITY_EDITOR || DEVELOPMENT_BUILD
        // 普通诊断仅保留在编辑器与开发构建中
        Debug.Log(Describe("INFO", module, eventId, detail), context);
#endif
    }

    public static void Warn(string module, string eventId, string detail, Object context = null)
    {
        Debug.LogWarning(Describe("WARN", module, eventId, detail), context);
    }

    public static void Error(string module, string eventId, string detail, Object context = null)
    {
        Debug.LogError(Describe("ERROR", module, eventId, detail), context);
    }
}

public sealed class RuntimeLogDemo : MonoBehaviour
{
    private void Start()
    {
        GameLog.Info("Boot", "boot.ready", "初始化完成", this);

        // 设置不存在时仍可运行,但需使用默认画质
        if (!PlayerPrefs.HasKey("demo.quality"))
            GameLog.Warn("Config", "config.default", "没有画质设置,使用默认值", this);
    }
}

预期输出(编辑器运行、尚未设置 demo.quality):

text
[INFO][Boot][boot.ready] scene=<SCENE> 初始化完成
[WARN][Config][config.default] scene=<SCENE> 没有画质设置,使用默认值

<SCENE> 代表实际场景名;Unity Console 还会显示自己的调用栈和消息图标。打开 Window > General > Console,观察信息与黄色警告两类消息,点击任意一条检查对象关联。若已经保存 demo.quality,第二条不会出现。

错误信息与发布边界

当读取失败且没有可用恢复路径时,才调用 GameLog.Error("Save", "save.read.failed", "存档无法解析", this)。真实异常还应通过 Debug.LogException(exception, this) 保留堆栈,避免只打印异常文案而丢失发生位置。

Info 使用编译条件限制在编辑器和 Development Build;Warn、Error 则由 Unity 正常日志通道输出。此示例读取场景名和 Unity 对象,只应在主线程调用。后台任务应先传递纯数据,再由主线程写入日志,不能直接从工作线程访问场景 API。

不要把密码、令牌、玩家个人信息或完整存档内容放入 detail。也不要在每帧 Update 内重复记录同一事件:用事件发生时记录、合并计数或限频替代刷屏。统一入口的价值不在于打印更多,而在于每条消息都能检索、定位并判断是否需要处理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一运行时日志入口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通