跳到正文

错误与故障排查

通过可搜索的错误标识、可验证的原因和安全的恢复步骤帮助读者定位问题。

让读者用观察结果找到页面

以实际错误码或消息中的稳定短语作为标题或开头。日志中的项目路径、时间和请求编号可用示例值。写明消息出现在哪里,例如终端、构建日志或浏览器界面,并交代适用的版本和模式。

错误码可能对应多个原因。先给读者一个成本较低的检查,再根据观察结果分流。确认原因后提供恢复步骤与验证方法。

用现象、检查和动作编排诊断

示例工具提示 INDEX_FILE_MISSING 时,可以按下表定位。

实际现象先检查恢复动作
构建结束后找不到索引输出目录是否与配置一致从配置指定的目录读取产物
部署后搜索为空已部署资源中是否包含索引添加索引产物后重新部署
项目移动后首次构建失败日志中的索引输入路径是否仍存在更新相对路径并重新构建

每行使用能验证的条件。读者完成恢复后,写明希望看到的状态,例如搜索返回示例文档,并报告索引文件的实际读取位置。

交代重试、回退和报告途径

重试会改变数据或产生重复任务时,说明在重试前怎么判断上次是否成功。回退要注明适用的版本和数据条件。需要上报时,告诉读者应收集哪些版本、错误字段和最小输入,再按可复查的问题报告组织信息。

维护错误参考时,用对应版本重新触发一次错误,并确认恢复步骤能消除错误。跨版本变更可以按修订记录保留旧错误名或替代操作。