游戏引擎 / 系统课时
读取运行日志定位异常
读取运行日志定位异常
发布包中的报错如果只有最后一句提示,往往无法确定失败发生在哪个阶段。本课给关键事件加上构建与阶段信息,用完整例程记录缺配置错误,再把日志时间与玩家操作对应,避免大量打印掩盖根因。
学习目标
- 能为关键事件记录必要上下文
- 能区分受控失败、脚本错误和原生崩溃证据
- 能从第一条相关异常缩小排查范围
为启动与切换设少量事件
为启动配置、主场景加载、地图切换、存档读取和连接状态记录事件名。每条包含构建、阶段、单调时间和必要错误值,资源相关事件附实际路径。不要逐帧输出全部对象,这会增加 CPU 与 I/O 并让关键错误难以找到。
日志不应含账号令牌、密钥、完整个人路径或未经授权的存档内容。对重复失败限频,并保留首次错误和次数;记录文件设置大小与轮转规则。诊断信息需要回答发生了什么,而不是把所有内部数据倾倒给玩家。
Godot 的 Output 与 Debugger Errors 可帮助开发期查看错误,发行包则需要收集平台日志或明确日志文件。桌面可以使用 --log-file 指定路径;手机使用平台工具与应用自己的诊断记录。平台和模板设置会影响可见输出,不能保证每种包都有相同控制台。
记录一条真实的缺配置错误
下面完整例程先写启动事件,再尝试读取不存在的 res://absent-config.json,将实际错误码写入 JSONL。保存为 events.gd,在不含该文件的空项目执行 godot --headless --path . --script events.gd。
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() # 完成诊断示范;不代表缺配置后业务启动成功。预期输出(省略启动横幅):
logged_events=2用户目录文件有两行合法 JSON,事件分别为 startup 与 config_missing;时间和错误码由实际接口提供。这个例程只验证捕获和记录,产品遇到必需配置缺失时应进入明确失败界面或返回失败状态,而非继续使用不存在的数据。
读回断言还检查事件顺序与构建字段,避免仅凭文件存在就判定记录成功。将配置路径换成实际存在的文件会触发本例的前置条件失败;生产日志应按成功与失败分支分别记录,而不是总输出相同错误事件。
从第一条相关异常追到阶段
先确认日志属于玩家的构建,再找到失败前最后一个业务事件和第一条相关错误。后续一连串空引用可能只是资源加载失败的后果,应先修复最早的失败。用单调时间对齐同一进程事件,不把不同设备的单调时钟直接当成统一时间。
脚本错误通常能提供调用栈和脚本位置;原生崩溃可能需要系统崩溃记录、原生符号与对应二进制。push_error 写一条错误不等于引擎必然终止,日志截断也不保证是崩溃,需要结合进程退出、系统记录与设备状态。
缩小后在正式包复测
根据阶段检查资源路径、JSON 格式、权限、版本迁移或平台插件,先形成最小复现。修复后重跑原路线,确认错误不再出现,同时验证功能已恢复。仅屏蔽输出或改成静默跳过,会让日志干净却保留故障。
诊断构建添加的日志与分析器可能改变时序,遇到低概率问题应记录这个边界。归档错误前后足够窗口和包身份,并设收集保留期限。系统工具没有拿到原生栈时就写证据缺失,不生成看起来完整的堆栈替代。
开发期面板见 Output panel,文件失败接口见 FileAccess。