HarmonyOS 项目写到后面日志经常会变成一锅粥。页面里打几行Repository 里打几行网络层和数据库层也各打一行。真正出问题时控制台里能看到一堆failed、empty、error但很难判断它们是不是同一次操作产生的。这次只拆一个具体问题日志不是越多越好关键是能不能把一次操作串起来。尤其是搜索、收藏、购物清单、页面跳转这类链路失败点可能在页面也可能在数据层。如果没有模块标签和 traceId后面排查只能靠肉眼猜。这篇按 HarmonyOS 5.0 及以上的 hilog 排查思路来写不讲复杂平台理论只讲一个可落地的封装方式每次关键操作生成一个 traceId页面、数据层、兜底分支都带着它打日志。这样看到一条错误日志时可以顺着 traceId 找到前面发生了什么。为什么散日志不好查看一个常见写法hilog.info(0x0000,search,start search)hilog.info(0x0000,repository,query db)hilog.error(0x0000,list,render failed)这三行单独看都没错但排查时有两个问题search、repository、list之间没有同一个请求编号如果用户连续点了两次搜索很难判断错误属于哪一次。所以日志至少要带三个东西模块名、链路编号、关键字段。字段作用不建议怎么写module判断日志来自哪个模块全部都写成 apptraceId把一次操作串起来每层自己生成一个新编号action说明当前步骤只写 success 或 failedfields放少量关键字段把完整对象直接打出来先把验证环境说清楚这里的示例按 HarmonyOS 5.0 及以上项目来理解日志侧使用 hilog工具侧按 DevEco Studio 的日志查看与关键字过滤来排查。示例不是为了多封一层工具类而是为了验证一件事当一次操作从页面走到 Repository再回到 UI 渲染时日志能不能沿着同一个 traceId 找回完整路径。我会用两个对照案例看效果第一个案例只有错误日志看得到失败但看不到前因后果第二个案例把 traceId、module、action 和少量字段带上能把输入、查询、兜底和渲染串起来。案例一只有错误没有上下文先看一个失败例子。页面只在出错时打一行hilog.error(0x0000,search,query failed)这行日志只能说明“查失败了”但回答不了几个关键问题用户搜的是什么失败前有没有命中过缓存是数据库查询失败还是结果映射失败这条错误和页面上哪次点击有关我用本地脚本模拟了一下这种情况。错误日志确实存在但 traceId 是空的前后文也只有它自己{missingContext:{errorCount:1,contextCount:1,traceId:missing}}这类日志看起来有记录实际排查价值很低。因为它没有把“用户动作到错误点”的路径留下来。案例二一次操作用同一个 traceId 串起来更稳的做法是页面入口先生成一个 traceId然后往后传。classLogContext{constructor(publicmoduleName:string,publictraceId:string){}}functioncreateTraceId(scene:string):string{return${scene}-${Date.now()}-${Math.floor(Math.random()*1000)}}页面里这样用asyncfunctionsearch(keyword:string){consttraceIdcreateTraceId(recipe-search)constloggercreateLogger(recipe-search,traceId)logger.info(input keyword accepted,{keywordLength:keyword.length})try{logger.info(query local index,{source:rdb})constrowsawaitrepository.search(keyword,traceId)logger.info(render result list,{count:rows.length})this.rowsrows}catch(err){logger.error(search failed,{reason:${err}})this.errorText搜索失败可以换个关键词再试}}Repository 不要重新造一个编号继续用页面传进来的 traceIdasyncfunctionsearch(keyword:string,traceId:string):PromiseSearchRow[]{constloggercreateLogger(recipe-repository,traceId)logger.info(build predicates,{hasKeyword:keyword.length0})constresultawaitqueryFromRdb(keyword)if(result.length0){logger.warn(fallback to fuzzy match,{reason:exact-empty})returnfuzzySearch(keyword)}returnresult}本地验证结果是这样{traceContext:{errorCount:1,contextCount:4,traceId:search-20260726-001}}这里的重点不是数字本身而是错误日志终于能往前追了。看到render list failed时可以顺着同一个 traceId 找到输入已经通过校验已经查过本地索引精确命中为空进入过模糊匹配兜底最后才是在列表渲染阶段失败。这比单独一行query failed有用得多。hilog 封装不要太重日志封装不需要一开始就做成很大的系统。一个小工具就够用classAppLogger{constructor(privatemoduleName:string,privatetraceId:string){}info(action:string,fields:Recordstring,string|number|boolean{}){this.print(INFO,action,fields)}warn(action:string,fields:Recordstring,string|number|boolean{}){this.print(WARN,action,fields)}error(action:string,fields:Recordstring,string|number|boolean{}){this.print(ERROR,action,fields)}privateprint(level:string,action:string,fields:Recordstring,string|number|boolean){constmessageJSON.stringify({traceId:this.traceId,module:this.moduleName,action,fields})hilog.info(0x0000,this.moduleName,[${level}]${message})}}有几个边界要注意不要在日志里打手机号、账号、定位、完整用户输入这类敏感内容不要把整个对象直接JSON.stringify扔进去错误日志要带 reason但 reason 应该是可排查的枚举或短描述traceId 用来串排查链路不是用户身份标识。哪些地方最值得加 traceId我会优先放在这几类地方场景为什么需要搜索/筛选用户连续输入时旧请求和新请求容易混在一起收藏/取消收藏页面状态、Preferences、RDB 可能同时变化购物清单写入多条食材合并时失败点可能在事务中间页面跳转Want 参数、NavPathStack、返回刷新容易串图片加载占位、失败图、缓存命中要能区分不是所有函数都要打日志。更合适的做法是入口打一行关键分支打一行失败打一行。日志太密会影响阅读也会把真正有价值的错误埋掉。最后怎么检查我会用下面这几条检查日志有没有写对一次用户操作只有一个 traceId页面层和数据层能共享这个 traceId错误日志能找到前面的关键步骤日志字段足够排查但不暴露隐私失败分支有可读提示不只是控制台里有错误日志模块名稳定不要今天叫 search明天叫 listSearch。把这些边界定下来以后hilog 就不只是“打印一下看看”而是能帮我们复原问题现场。页面越复杂这个习惯越值钱。参考资料HarmonyOS hilog 日志能力文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/hilog-guidelines-V13HarmonyOS 故障日志与调试相关文档https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/ide-debug-hilog-V13