游戏开发日志09v0.1版本不只是“能跑起来”更是建立日志体系的最佳时机很多独立游戏开发者和刚组建的小团队在v0.1版本阶段最容易犯一个共同错误把所有精力都放在“把游戏跑起来”上却完全没有建立日志体系。这里的日志不是指代码里的print而是两套东西——开发日志研发过程的记录和运行日志程序运行时的输出记录。为什么要在这个阶段专门写一篇日志相关的记录因为 v0.1 是一个很特殊的版本代码量还不大Bug 还很多需求还在摇摆团队或者只有你自己对项目的理解还在变化。恰恰是这个时候日志体系的价值最大而搭建成本最低。等到了 v0.5、v0.8玩家人数变多、代码量膨胀再回头补日志体系和开发记录就要付出几倍的成本而且早期的问题已经无法追溯了。这篇文章会从 v0.1 版本的规划思路出发讲清楚开发日志和运行日志的区别然后以一个 Unity 示例项目为主线搭建一个最小可用的游戏日志系统再给出开发日志模板和常见排查清单。无论你是用 Unity、Godot 还是自研引擎核心思路都适用。1. v0.1版本为什么值得认真记录先说一个判断v0.1 版本的本质不是“功能最少的一个版本”而是“验证核心玩法和工程基线是否成立的一个版本”。很多团队把 v0.1 当成“小 demo”觉得反正功能少、代码烂一点没关系后面会重写。这个想法在纯原型验证阶段可以理解但只要确定了要做长线迭代v0.1 阶段的工程习惯就会直接影响后续版本的开发速度。尤其是日志——它决定了将来你能不能回答这样几个问题“这个 Bug 是从哪个版本开始出现的”“玩家在崩溃之前做了什么操作”“上一次改动到底改了哪些模块”“上个月说的‘手感优化’具体优化了什么参数”如果没有日志记录这些问题基本无解。而这些问题在独立游戏开发和中小团队中出现的频率比想象中高得多。另一个容易被忽略的点是v0.1 阶段是团队磨合期。如果你有队友开发日志就是团队沟通的“同步中枢”如果你是 solo 开发开发日志就是“给未来的自己留的操作手册”。游戏开发周期长、中断频繁很多项目做了一半停下来几个月后重新捡起来看到之前的代码一头雾水。这时候一份认真写的开发日志比任何代码注释都管用。本文要解决的三个核心问题很简单v0.1 版本的范围和验收标准怎么定才不会越做越失控。运行日志系统怎么搭才能在开发和测试时快速定位问题。开发日志怎么记才能让版本之间可追溯、可复盘。2. 开发日志与运行日志先分清两个概念很多新手会把“开发日志”和“运行日志”混为一谈实际上它们是两套完全不同的体系。搞清楚它们的区别后面的所有实践才不会跑偏。维度开发日志Dev Log运行日志Runtime Log记录者开发者 / 策划 / 美术游戏程序本身内容版本计划、功能进度、修复记录、设计决策运行时输出、异常堆栈、玩家操作、性能数据用途团队协作、版本复盘、经验沉淀线上/测试环境排障、问题复现、数据分析存放位置文档仓库Markdown / 在线文档本地文件 / 服务端日志系统粒度以任务、版本为单位以事件、时间为单位读者开发团队成员程序、QA、运营这里有一个常见的误区以为写了开发日志就不需要搭运行日志系统或者只搭了运行日志但从来不写开发记录。其实两者是互补的——开发日志回答“我们打算做什么、做完了什么”运行日志回答“程序实际发生了什么”。在实际项目中开发日志往往还可以再细分为三类版本规划日志记录一个版本的目标、范围、里程碑和验收标准。每日开发日志记录当天做了什么、遇到什么问题、明天计划做什么。版本发布记录记录发布内容、已知问题、回滚方案。运行日志则可以按环境分为编辑器日志、测试包日志和线上包日志。v0.1 阶段重点做好编辑器日志和测试包日志即可线上日志系统比如服务端游戏常用的 ELK 方案可以等到有联机需求时再考虑。3. v0.1版本规划范围、里程碑与验收清单在写任何代码之前先把 v0.1 版本的范围定清楚。这里最稳妥的原则是v0.1 只做核心玩法的最小闭环不做边缘功能不做系统优化不做内容堆量。以一个俯视角射击游戏为例v0.1 的范围可以是玩家角色可以移动、射击敌人有一到两种行为有基础的生命值和碰撞判定一个可以反复试玩的关卡场景基础日志系统接入。明确不属于 v0.1 的内容也要写下来例如多语言包成就系统存档系统UI 动效打磨性能优化新手引导商业化相关。把这些内容写进版本规划文档里目的是防止开发过程中被“顺手加个小功能”带偏。游戏开发最怕的不是需求多而是需求在一个版本内无序叠加。里程碑建议拆成三个里程碑目标验收方式M1核心场景跑通角色可操控在编辑器中运行角色能移动、射击M2敌人 AI 与战斗反馈完成击杀敌人有反馈玩家会受伤、死亡M3可试玩包输出日志系统生效安装到真机日志文件可正常生成并回传每个里程碑的验收清单要具体到可以直接勾选而不是“优化战斗手感”这种模糊表述。比如 M2 的清单[ ] 敌人会朝玩家移动[ ] 敌人进入攻击范围后执行攻击[ ] 玩家受击后有受击反馈[ ] 玩家生命值归零后触发失败界面[ ] 战斗相关事件写入运行日志。4. 游戏引擎环境准备与日志输出路径设计后面的示例以 Unity 为演示环境原因是 Unity 的日志 API 在编辑器、真机、PC 端表现一致比较适合讲清通用思路。如果你用的是 Godot可以用print和文件输出 API 实现同样的效果如果用自研引擎思路也一样。先约定示例环境引擎Unity推荐使用当前 LTS 版本具体以你的项目为准开发语言C#目标平台Windows 编辑器 Android 真机v0.1 可以只做主平台在 Unity 中日志输出的关键点有两个一是Debug.Log系列 API控制台和日志文件都会输出二是Application.persistentDataPath这是应用的可写目录在不同平台上会自动映射到合理的路径。日志文件的存放路径我建议固定在Application.persistentDataPath/Logs下。为什么不能直接把日志写到项目根目录在 Android 上应用没有项目根目录的写权限在 iOS 上沙盒机制只允许访问应用沙盒目录在 PC 上直接写工程目录会导致日志被版本管理工具反复追踪很麻烦。所以统一用persistentDataPath。这个路径在不同平台的真实位置如下平台persistentDataPath 示例WindowsC:/Users/用户名/AppData/LocalLow/公司名/产品名Android/storage/emulated/0/Android/data/包名/filesiOSApp沙盒/Documents真机调试时如果找不到日志文件优先去上面的路径找。5. 搭建一个最小可用的游戏日志系统v0.1 阶段不需要引入庞大的日志框架自研一个二十行左右的LogManager就足够用。这个管理器要做四件事统一封装Debug.Log方便以后扩展同时把日志写入文件带上时间戳和日志级别控制日志文件大小避免无限增长。下面是核心代码可以直接放在项目的Scripts/Framework目录下。// 文件路径Assets/Scripts/Framework/LogManager.cs using System; using System.IO; using UnityEngine; namespace GameFramework { public static class LogManager { private static string LogDirectory { get { return Path.Combine(Application.persistentDataPath, Logs); } } private static string LogFile { get { return Path.Combine(LogDirectory, game.log); } } private static StreamWriter _writer; private static long _fileSize; private const long MaxFileSize 2 * 1024 * 1024; // 2MB [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)] private static void Init() { if (!Directory.Exists(LogDirectory)) { Directory.CreateDirectory(LogDirectory); } _fileSize File.Exists(LogFile) ? new FileInfo(LogFile).Length : 0; if (_fileSize MaxFileSize) { RotateLog(); } _writer new StreamWriter(LogFile, append: true); _writer.AutoFlush true; Application.logMessageReceived OnLogMessageReceived; AppDomain.CurrentDomain.DomainUnload (sender, e) CloseWriter(); AppDomain.CurrentDomain.ProcessExit (sender, e) CloseWriter(); Debug.Log([LogManager] Log system initialized.); } private static void OnLogMessageReceived(string condition, string stackTrace, LogType type) { string level type switch { LogType.Error ERROR, LogType.Exception EXCEPTION, LogType.Warning WARN, LogType.Assert ASSERT, _ INFO }; string line string.Format([{0}][{1}] {2}, DateTime.Now.ToString(yyyy-MM-dd HH:mm:ss.fff), level, condition); if (type LogType.Error || type LogType.Exception) { line \n stackTrace; } if (_writer ! null) { _writer.WriteLine(line); } } private static void RotateLog() { string backup LogFile .old; if (File.Exists(backup)) { File.Delete(backup); } File.Copy(LogFile, backup); File.Delete(LogFile); } private static void CloseWriter() { if (_writer ! null) { Application.logMessageReceived - OnLogMessageReceived; _writer.Close(); _writer null; } } } }这段代码有几个设计点值得说明。RuntimeInitializeOnLoadMethod是 Unity 在游戏启动时自动调用的入口不需要在场景里挂任何 GameObject。Application.logMessageReceived会把Debug.Log、Debug.LogWarning、Debug.LogError全部捕获到统一写入文件。这样项目里所有使用Debug.Log的代码都自动拥有了文件输出能力不需要到处改造。2MB 的日志轮转是为了防止长时间运行把存储塞满。实际项目中可以根据机型调整大小。注意AppDomain事件用于程序退出时关闭文件流避免日志写入不完整。这在 PC 开发时尤其重要。6. 开发日志怎么记模板与实践运行日志系统解决的是“程序发生了什么”开发日志解决的是“团队做了什么决策”。我给出一套可以直接用的 Markdown 模板按“周为节奏、版本为阶段”来组织。6.1 版本规划模板在项目根目录建一个Docs/文件夹每个版本一个文件例如Docs/v0.1-version-plan.md# v0.1 版本规划 ## 版本目标 一句话说明这个版本要验证什么。 ## 功能范围 - [ ] 玩家移动与射击 - [ ] 敌人 AI 基础行为 - [ ] 生命值系统 - [ ] 日志系统接入 ## 明确不做 - 存档系统 - 新手引导 - 成就系统 - UI 动效打磨 ## 里程碑 - M1: 核心场景跑通日期 - M2: 战斗反馈完成日期 - M3: 可试玩包输出日期 ## 验收清单 - [ ] 编辑器中可运行完整流程 - [ ] 真机包可安装 - [ ] 日志文件可正常生成6.2 每日开发日志模板建议按日期命名Docs/devlog/2025-04-01.md# 2025-04-01 开发日志 ## 今日完成 1. 完成玩家移动控制手感参数暂时使用默认值。 2. 接入 LogManager确认日志文件可写入。 ## 遇到的问题 - 敌人 AI 导航时在小巷里卡住。 - 原因导航网格烘焙参数过小。 - 当前处理临时放大烘焙区域后续专项优化。 ## 明日计划 1. 修复敌人卡住问题。 2. 完成射击命中判定。 ## 备注 - 今天调试使用的 Unity 版本Unity 2022 LTS每日日志不需要写很长但“遇到的问题”一定要记录原因和处理方式。这是项目最宝贵的资产。6.3 版本发布记录模板在Docs/下维护一个CHANGELOG.md# 更新日志 ## v0.1.0 - 2025-04-10 ### 新增 - 玩家移动、射击、生命值系统 - 敌人基础 AI - 运行日志系统LogManager ### 修复 - 无首版 ### 已知问题 - 敌人卡地形 - 日志文件在部分 Android 机型上路径显示异常 ### 回滚方案 - 保留 v0.0.1 存档包确认新版本核心流程通过后再清理开发日志的关键是“持续”。v0.1 阶段可能只有几百行代码、十几个文件但每天花十分钟记录三个月后就是一笔可以复盘的完整资料。7. 运行验证与效果检查日志系统接好之后不要直接进入玩法开发先做一轮完整验证。这是很多教程不会强调的一步但在项目中必须做。7.1 编辑器内验证在游戏中故意触发一条错误日志比如在一个 GameObject 上写// 测试代码验证日志捕获 Debug.Log([Test] normal log); Debug.LogWarning([Test] warning log); Debug.LogError([Test] error log);运行游戏后打开日志文件目录# Windows 路径示例 C:/Users/你的用户名/AppData/LocalLow/DefaultCompany/YourGame/Logs/game.log打开game.log预期能看到类似内容[2025-04-01 10:15:30.123][INFO] [LogManager] Log system initialized. [2025-04-01 10:15:30.130][INFO] [Test] normal log [2025-04-01 10:15:30.131][WARN] [Test] warning log [2025-04-01 10:15:30.132][ERROR] [Test] error log如果这个文件内容和格式正确说明日志系统已经生效。7.2 真机验证打包 Android 测试包安装到手机运行并触发几条日志然后用以下方式之一获取日志连接 Android 设备使用adb logcat过滤游戏进程日志让测试包内置一个日志查看界面读取persistentDataPath下的日志文件通过局域网把日志文件上传到电脑v0.1 阶段手工拉取即可。这里有一个常见的坑手机连接电脑后persistentDataPath在 Android 上不一定直接可见有些文件管理器需要 root 权限才能查看Android/data目录。更稳妥的做法是在游戏内做一个隐藏的开发者界面用代码读取日志并显示出来或者复制到外部存储目录。// 示例在开发者界面显示日志文件内容 public string ReadLog() { string path Path.Combine(Application.persistentDataPath, Logs, game.log); return File.Exists(path) ? File.ReadAllText(path) : Log file not found.; }这一步可以提前在 v0.1 阶段做好后面调试时会节省大量时间。8. 常见问题与排查思路日志系统本身并不复杂但游戏开发中会遇到各种环境相关问题。下面整理了一份 v0.1 阶段最常遇到的问题排查表。问题现象可能原因排查方式解决方案日志文件没有生成路径错误、未初始化检查persistentDataPath路径确认Init()是否执行把头文件输出完整路径打出来确认RuntimeInitializeOnLoadMethod存在日志文件中文乱码编码格式不符确认StreamWriter编码初始化时指定编码new StreamWriter(path, true, System.Text.Encoding.UTF8)日志写入速度慢、闪退日志量过大、同步写入文件卡主线程查看 CPU 性能确认日志频率引入队列异步写入或只保留错误日志完整堆栈真机上看不到日志文件Android 文件访问权限限制用文件管理器检查目录可见性在游戏内提供日志查看界面调试阶段导出到可读目录报错但日志文件里没有记录Application.logMessageReceived事件未订阅在代码中打点确认订阅是否成功检查是否有人误调用了Debug.unityLogger.logEnabled false日志文件过大导致包体吃满存储没有轮转机制或轮转阈值过大查看文件大小增加按天分割和按大小轮转保留最近 N 份手机上只有错误没有堆栈发布模式裁剪了堆栈查看构建设置开发包开启Development Build和Script Debugging如果遇到日志系统完全不工作第一件事一定是查看 Unity 的 Console 窗口有没有输出。Console 有输出说明Debug.Log本身正常问题出在文件写入链路Console 也没有输出说明游戏在更早的阶段就崩溃了优先排查场景加载和初始化流程。9. 从v0.1到v0.2日志体系的演进方向很多文章讲完日志就结束了这里我想多说一层v0.1 搭好的日志设施在后续版本里应该往哪个方向演进。如果 v0.1 只是一款单机原型那么上面的LogManager已经够用。但游戏开发往往会走向两种方向它们对日志的要求完全不同。第一种是加入联机能力比如弱联网排行榜、多人对战。此时本地文件日志就不够用了服务端需要一套完整的日志采集、存储和检索链路。常见的方案是 ELK 套件通过 Logstash 或 Filebeat 收集日志存入 Elasticsearch再用 Kibana 做检索和可视化。很多团队也会用云厂商的日志服务来替代自建 ELK降低运维成本。第二种是大量采用 AssetBundle 等资源管理系统。资源加载失败、依赖缺失这类问题在本地日志里往往只有一串 GUID 或路径排查效率很低。这时候日志系统需要支持分层、打点、资源生命周期追踪。相关热搜里提到的“游戏开发:资源管理与 yooasset 分析(中)”就是这类场景——资源管理一旦复杂化日志内容也要跟着结构化。从 v0.1 到 v0.2建议按优先级做这几件事给日志增加“模块”字段比如UI、AI、Battle、Resource方便按模块过滤。增加日志分级开关比如发布包里只保留错误日志开发包里保留全量日志。增加关键业务流程打点比如“玩家点击开始战斗”“战斗加载完成”“玩家退出战斗”为后续数据分析打基础。如果开始有线上用户接入崩溃上报 SDK把崩溃堆栈单独上传。v0.1 阶段不要急着做这些但规划时要留好扩展点。这里指的扩展点包括日志格式不要写死成“只有字符串”建议从第一天就写成“时间戳 级别 模块 内容”的结构文件路径不要散落在多个脚本里统一通过LogManager访问。这样后续就算换日志框架改动也集中在一个类里。10. 写在最后v0.1版本的高价值习惯回到开头的判断——v0.1 版本最值得投入的不是美术细节不是代码架构而是“可追溯性”。开发日志让团队知道“为什么做、做了什么”运行日志让团队知道“程序发生了什么、失败在哪一行”。这两个习惯决定了项目从 v0.1 走到 v0.8 的时候是越来越清晰还是越来越混乱。很多游戏项目死在半路上不是因为技术太难而是因为历史遗留问题无法追溯最后连重构的勇气都没有了。我建议你从今天开始建一个Docs文件夹写一份 v0.1 版本规划然后在Scripts/Framework下面放一个上面那个二十行的LogManager。这两件事都不需要超过四十分钟但它们会在整个开发周期里持续给你回报。下一阶段可以围绕资源管理、新输入系统或角色控制来做专项记录。到时候你会发现有了日志体系和开发日志习惯任何一次疑难 Bug 排解都不会是无从下手的“玄学问题”。