日志系统 · 使用说明

〇它是干什么的

先花 30 秒建立直觉，再动手写。

RevLog.Info("登录成功");                            // ① 普通信息（正式包保留）
RevLog.Warn("配置缺失，用默认值", "Config");         // ② 告警 + tag（第二个参数就是 tag）
RevLog.Error("数据库连不上", "Network");             // ③ 错误（自动带堆栈）
RevLog.Debug("仅编辑器可见，正式包零成本");              // ④ 调试（编译期删除，连拼接都不发生）

一3 分钟跑起来（可粘贴）

不用配置、不用挂脚本、不用写 Update。

// ① 随便找个 MonoBehaviour，在 Start 里写：
void Start()
{
    RevLog.Info("游戏启动");
    RevLog.Warn("配置表缺字段，用默认值", "Config");
    RevLog.Debug("这条只有编辑器和带 REVLOG_DEBUG 的包能看到");
}

// ② 打开 Unity 控制台 → 应该看到三行：
//    "HH:mm:ss.fff I [General] 游戏启动 frame:123"
//    "HH:mm:ss.fff W [Config] 配置表缺字段，用默认值 frame:123"
//    "HH:mm:ss.fff D [General] 这条只有编辑器… frame:123"

// ③ 想看现场（最近 200 行，一键复制）：
Debug.Log(RevLog.Dump(200));

二"我要做 X" 对照表（全部 API）

左边找需求，右边抄一行。所有方法签名都写在一行里，参数不用换行。

三级别就是成本契约（最该记住）

级别不只是"严重程度"，更是"调用要花多少钱"。

3.1 Debug 为什么是"零成本"

// 你写：
RevLog.Debug("坐标 = " + Heavy().ToString());      // Heavy() 很贵

// 正式包里编译出来（IL）：什么都没有 —— 连 Heavy() 都不会被调用
// 对比"运行期判断"：if (isDebug) { ... } 参数已经求值、GC 已经产生，钱已经花了

3.2 热循环里别拼字符串

for (...)
    RevLog.Info($"hp={hp} pos={pos}");

for (...)
    if (RevLog.IsEnabled(RevLogLevel.Info, "HP"))
        RevLog.Info($"hp={hp} pos={pos}", "HP");

RevLog.IsEnabled 只做两次比较（阈值 + tag 静音表），是热路径里唯一值得的守卫。

四两个开关：阈值与按模块静音

"一切有开关" —— 日志系统自己也不例外。

五出事前的现场（环形缓冲）

线上最需要的不是"从现在开始记"，而是"出事之前发生了什么"。

RevLog.Dump(200);        // 最近 200 行拼成多行文本（一键复制）
RevLog.Recent(50);      // 最近 50 条结构化条目（时间/级别/tag/消息/堆栈/帧号）
RevLog.Count;           // 当前留了多少条
RevLog.Clear();         // 清空历史（通道不动）

六落盘与上报（默认都不开）

"要不要写文件、要不要上报"是产品决策，不是框架替你决定的事。

6.1 落盘：一行，异步，不卡帧

RevLog.EnableFileLog(Application.persistentDataPath + "/revlog");

6.2 上报：接一行，不接就不报

RevLog.OnReport += (e, msg) => CrashSightAgent.ReportException(e, msg);   // 你的平台
RevLog.OnReport += (e, msg) => 自建上报.Post(e, msg);                     // 或自建

七接自己的输出通道

门面自己不写任何地方 —— 输出全靠通道（Sink）。

sealed class MySink : IRevLogSink
{
    public string Name => "MySink";
    public void Write(in RevLogEntry entry) => 你的队列.Enqueue(entry);   // 别在这里做慢活
    public void Flush()   => 你的队列.排空();
    public void Dispose() => 你的队列.收尾();
}

RevLog.AddSink(new MySink());

八全框架统一出口（接入现状）

框架从"每个模块各打一套"变成了"只有一个日志出口"。

九怎么防止日志刷屏（重复抑制）

"每帧都在刷同一句话"是日志系统最真实的头号杀手。

RevLog.Warn("每帧都在刷同一句话");   // 连刷 5 次
RevLog.Warn("换了一句话");           // 出现不同日志时，补一条汇总

// 控制台看到：
//   W [General] 每帧都在刷同一句话 frame:10
//   W [General] 每帧都在刷同一句话（重复 5 次） frame:10   ← 汇总（条目的 Repeat 字段）
//   W [General] 换了一句话 frame:10

十新手最容易踩的 6 个坑

每条都会让人白干一阵子。

十一看不到日志怎么查（3 分钟）

按顺序排除，每一步都能立刻验证。

十二附：文件清单 / 验收 / 设计来源

想深入看代码或判断可信度时读这一节。

12.1 文件都在哪（你只需要读一个）

12.2 验收情况

12.3 设计来源（参考实现日志系统）