故障排除页将读者遇到的每一次失败与其原因及解决步骤配对,按症状而非按问题组织。语气为引导性、直截了当、以解决方案为导向。
故障排除有两种位置:在失败发生的页面上以内联的 “What if ...”(如果……)标注框或折叠面板出现;以及当内联条目大约超过五条、或同一失败跨越多个页面时,为每个产品区域提供专用故障排除页。使用它是为了帮助读者从失败中恢复。它不是:
- 如何操作。 如何操作追求一个目标;故障排除从失败中恢复。
- 错误参考。 完整的按错误码目录属于参考材料。本页覆盖症状、多原因问题,以及错误码捕获不到的“很慢或不稳定”情况。
- 全局常见问题。 故障排除页按失败组织,而不是按问题组织。
完整对比请参阅内容类型。
- 页面标题:“故障排除”后接产品、功能或区域,例如 “Troubleshooting delivery”。
- 条目标题:逐字的症状,最好是确切错误消息,因为在搜索和侧边栏扫读中,“Error: signature timestamp outside tolerance” 优于 “Signature problems”。将过长消息裁到大约 70 个字符的独特子串,用 ASCII
...标出截断,并保留消息类型,例如 “Error:”。没有消息的症状使用可观察的表述,例如 “Deliveries succeed but arrive twice”。 - 描述:说明该页按症状修复该区域中的常见失败。
使用 Nimbus troubleshooting 模板生成此页面。你的编程代理会获取完整页面框架和自查清单,然后根据你的产品进行调整:
npx @cloudflare/nimbus-docs add content-troubleshootingyarn @cloudflare/nimbus-docs add content-troubleshootingpnpm @cloudflare/nimbus-docs add content-troubleshooting将模板生成的 frontmatter 调整为 Cloudflare 的 schema:设置 pcx_content_type 和 products,替代模板生成的 type 等通用字段。
- 围栏代码块 承载逐字错误消息,这是搜索、读者和检索的匹配目标。展示一个带真实值的具体实例,切勿转述消息或省略其独特部分。
- 加粗的 Cause、Fix 和 Verify 标签 让每条都有相同的内部顺序,以便慌乱的读者可以直接跳到修复。
- Details 折叠面板适合功能页末尾的内联形式,但在专用页上条目应保持展开,因为隐藏的症状无法被找到。
- 不适合放在这里的内容: Cards、营销语气,以及没有修复方案的安慰话。
pcx_content_type: troubleshooting
products:
- product-a
- product-b有关更多详细信息,请参阅 pcx_content_type。
按发生频率排序条目,最常见的失败在前,数据丢失类失败可以插到队列最前面。在产品区域大约不超过五条时保持内联;之后移到专用页,并在原内联位置留下链接。每个权宜方案都要说明代价,并点明永久替代方案。专用页以 “Still stuck?” 部分结束,给出升级路径和“请先收集这些信息”清单,这是该类型的诚实条款:暗示自己已经穷尽所有情况的页面,会把读者困在它漏掉的那一次失败里。
- 条目自包含。 让每条都能单独成立,因为条目 N 被检索时没有前一条,也没有页面介绍。写全症状、原因和修复。
- 可执行的修复。 把原因和修复写成智能体可以执行的陈述:“检查您的配置”不是修复,具体命令如
hookline test-event --endpoint <id>才是。 - 逐字症状。 在围栏代码块中以一个具体实例展示逐字错误消息,以便搜索、读者和检索都匹配字面文本。