游戏引擎 / 系统课时
统一运行时日志入口
统一运行时日志入口
当存档读取失败或场景初始化顺序异常时,零散的 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 中的消息能定位关联的组件。
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):
[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 内重复记录同一事件:用事件发生时记录、合并计数或限频替代刷屏。统一入口的价值不在于打印更多,而在于每条消息都能检索、定位并判断是否需要处理。