游戏引擎 / 系统课时

读取运行日志定位异常

读取运行日志定位异常

发布包中的报错如果只有最后一句提示,往往无法确定失败发生在哪个阶段。本课给关键事件加上构建与阶段信息,用完整例程记录缺配置错误,再把日志时间与玩家操作对应,避免大量打印掩盖根因。

学习目标

  • 能为关键事件记录必要上下文
  • 能区分受控失败、脚本错误和原生崩溃证据
  • 能从第一条相关异常缩小排查范围

为启动与切换设少量事件

为启动配置、主场景加载、地图切换、存档读取和连接状态记录事件名。每条包含构建、阶段、单调时间和必要错误值,资源相关事件附实际路径。不要逐帧输出全部对象,这会增加 CPU 与 I/O 并让关键错误难以找到。

日志不应含账号令牌、密钥、完整个人路径或未经授权的存档内容。对重复失败限频,并保留首次错误和次数;记录文件设置大小与轮转规则。诊断信息需要回答发生了什么,而不是把所有内部数据倾倒给玩家。

Godot 的 Output 与 Debugger Errors 可帮助开发期查看错误,发行包则需要收集平台日志或明确日志文件。桌面可以使用 --log-file 指定路径;手机使用平台工具与应用自己的诊断记录。平台和模板设置会影响可见输出,不能保证每种包都有相同控制台。

记录一条真实的缺配置错误

下面完整例程先写启动事件,再尝试读取不存在的 res://absent-config.json,将实际错误码写入 JSONL。保存为 events.gd,在不含该文件的空项目执行 godot --headless --path . --script events.gd。

gdscript
extends SceneTree

func record_event(file: FileAccess, event: String, details: Dictionary) -> void:
    var record := {"build": "diagnostic-demo", "event": event, "tick_ms": Time.get_ticks_msec()}
    for key in details:
        record[key] = details[key] # 只传入本次诊断允许的字段。
    file.store_line(JSON.stringify(record))

func _initialize() -> void:
    var log_file := FileAccess.open("user://course-events.jsonl", FileAccess.WRITE)
    if log_file == null:
        quit(1)
        return
    record_event(log_file, "startup", {"phase": "config"})
    var config := FileAccess.open("res://absent-config.json", FileAccess.READ)
    if config != null:
        config.close()
        log_file.close()
        quit(1) # 演示前置条件是配置不存在。
        return
    var open_error := FileAccess.get_open_error()
    assert(open_error != OK)
    record_event(log_file, "config_missing", {"phase": "config", "error": open_error})
    log_file.close()
    var reader := FileAccess.open("user://course-events.jsonl", FileAccess.READ)
    if reader == null:
        quit(1)
        return
    var count := 0
    var events: Array[String] = []
    while not reader.eof_reached():
        var line := reader.get_line()
        if line.is_empty():
            continue
        var data: Variant = JSON.parse_string(line)
        assert(data is Dictionary and data.get("build") == "diagnostic-demo")
        assert(data.has("tick_ms") and data.has("event"))
        events.append(str(data["event"]))
        count += 1
    reader.close()
    assert(events == ["startup", "config_missing"])
    print("logged_events=", count)
    quit() # 完成诊断示范;不代表缺配置后业务启动成功。

预期输出(省略启动横幅):

text
logged_events=2

用户目录文件有两行合法 JSON,事件分别为 startup 与 config_missing;时间和错误码由实际接口提供。这个例程只验证捕获和记录,产品遇到必需配置缺失时应进入明确失败界面或返回失败状态,而非继续使用不存在的数据。

读回断言还检查事件顺序与构建字段,避免仅凭文件存在就判定记录成功。将配置路径换成实际存在的文件会触发本例的前置条件失败;生产日志应按成功与失败分支分别记录,而不是总输出相同错误事件。

从第一条相关异常追到阶段

先确认日志属于玩家的构建,再找到失败前最后一个业务事件和第一条相关错误。后续一连串空引用可能只是资源加载失败的后果,应先修复最早的失败。用单调时间对齐同一进程事件,不把不同设备的单调时钟直接当成统一时间。

脚本错误通常能提供调用栈和脚本位置;原生崩溃可能需要系统崩溃记录、原生符号与对应二进制。push_error 写一条错误不等于引擎必然终止,日志截断也不保证是崩溃,需要结合进程退出、系统记录与设备状态。

缩小后在正式包复测

根据阶段检查资源路径、JSON 格式、权限、版本迁移或平台插件,先形成最小复现。修复后重跑原路线,确认错误不再出现,同时验证功能已恢复。仅屏蔽输出或改成静默跳过,会让日志干净却保留故障。

诊断构建添加的日志与分析器可能改变时序,遇到低概率问题应记录这个边界。归档错误前后足够窗口和包身份,并设收集保留期限。系统工具没有拿到原生栈时就写证据缺失,不生成看起来完整的堆栈替代。

开发期面板见 Output panel,文件失败接口见 FileAccess。

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

目录与阅读设置

记录一个想法

读取运行日志定位异常

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

登录哪都通