--- title: "故障排查" description: "按症状组织的常见失败修复，让读者能从报错原文直接定位。" --- > Documentation Index > Fetch the complete documentation index at: https://nimbus.ndjp.net/llms.txt > Use this file to discover all available pages before exploring further. # 故障排查 > **需求** > > 处于工作、正在行动 —— 是恢复，不是推进。读者手里有一个报错字符串或一个症状，会把它粘进搜索，或者由智能体去搜。他们的第一个问题：*“我为什么看到这个，怎么让它停下来？”* > > 报错也是内容。在这里，人类搜索和智能体检索想要的是同一样东西，因为两者都按精确字符串匹配。 ## 适用场景 故障排查内容生活在两个地方，本配方两者都覆盖： - **内联，放在失败发生的页面上** —— 默认做法。在操作指南里用 “如果……怎么办” 提示框，或在功能页末尾用 FAQ 式折叠面板。内联形式保持相同的内部形状，只是压缩： > **如果登录失败并报 `Error: no workspace selected` 怎么办？** > CLI 已通过认证，但还没指向任何工作区。运行 `hookline workspace use ` 后重试。 - **每个产品区域一个专门的故障排查页**，当内联条目超过约 5 条，或同一失败跨越多个页面时使用。 它不是： - **操作指南。** 操作指南追求目标；故障排查从失败中恢复。“设置投递告警” 是操作指南，即使它涉及问题。 - **错误参考。** 如果产品有稳定的错误*码*，完整的逐码目录属于参考材料（每个码一个条目、统一模板 —— 见[参考配方](/style-guide/reference/)）；故障排查页覆盖症状、多因问题和代码捕捉不到的叙述性问题（“它很慢 / 它不稳定”）。小型产品会把两者合并；说明哪个页面负责哪部分。 - **全局 FAQ。** 有已知答案的问题，放到本应回答它的页面。故障排查页按*失败*组织，而不是按*问题*组织。 ## 标题与描述 - **条目标题：逐字的症状，最好是精确的报错信息。** “Error: signature timestamp outside tolerance” 在任何地方都胜过 “签名问题”。长消息裁剪到最有辨识度的部分，约 70 个字符，用 `...` 标记截断，并保留 “Error:” 或 “Warning:”。没有报错信息时，描述可观察到的现象：“投递成功但到达两次。” - **页面标题：**“故障排查 *区域*” —— 例如 “故障排查：投递”。 - **描述公式：**“*区域*内常见失败的修复，按症状组织。” ## 脚手架生成本页 安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整： ```sh npx @cloudflare/nimbus-docs add content-troubleshooting yarn nimbus-docs add content-troubleshooting pnpm nimbus-docs add content-troubleshooting bunx @cloudflare/nimbus-docs add content-troubleshooting ``` ## 组件建议 - **用围栏代码块放逐字的报错信息** —— 它是搜索、读者和检索的匹配目标。展示一个真实具体实例，包含变量值（`skew 512s > 300s` 展示了机制；稳定子串仍能匹配搜索）。绝不要改写报错；绝不要省略它有辨识度的部分。 - **加粗的 Cause/Fix/Verify（原因/修复/验证）标签**（或固定的三小标题）—— 统一的内部顺序让慌乱的读者直接跳到 “修复”。 - **折叠面板**适合内联形式（功能页末尾的 FAQ 式）；在专门页面上，条目保持展开 —— 藏起来的症状找不到，而页面存在的意义就是被扫读。 - **不适合：** 卡片、营销语气，以及没有修复的安慰（“这通常无害” —— 那就说明何时有害）。 ## 结尾 专门页面以 **Still stuck?（仍然卡住？）** 结尾 —— 升级路径，附一份 “先收集这些” 的清单。这是本类型的诚实条款：暗示自己完整的故障排查页，会把读者困在它恰好漏掉的那个失败上。 ## 阈值 - **内联到约 5 条，然后建专门页面** —— 并在原内联位置留下链接。 - **最常见的失败排最前；数据丢失类失败插队。** 排序就是分诊。 - **每个变通方案都说明其代价和永久替代方案。** 把变通方案当作修复来写，是技术债被写进永久文档的方式。 ## 链接与时效 每条 “原因” 链接到解释它的概念；每个多步 “修复” 链接到（或本身就是）一篇操作指南。 用支持请求和社区问题喂养本页。产品修复该失败后，删掉对应条目，否则读者会去寻找一个已经不存在的设置。对照某个版本检查页面时，盖上 `lastVerified`。 ## 智能体说明 - 这是智能体按精确字符串匹配检索的类型 —— 围栏代码块中的逐字报错就是全部胜负手。展示真实具体的实例；稳定子串承载匹配。省略（ASCII `...`）只允许出现在长消息的*标题*里，且绝不在有辨识度的部分上使用。 - 把 Cause → Fix 写成智能体可执行的陈述句；“检查你的配置” 不是修复，`hookline test-event --endpoint ` 才是。 - 让每个条目完全自成一体 —— 第 N 条会在没有第 N−1 条、也没有页面引言的情况下被检索。 ## 检查清单 建议性 —— 供作者或智能体自检，永不作为构建闸门： - [ ] 条目标题是逐字报错或可观察症状（长消息裁到有辨识度的子串，约 70 字符） - [ ] 每个带报错的条目都在围栏代码块中展示它，作为一个具体实例；仅有症状的条目在第一行说明可观察行为 - [ ] 固定内部顺序：症状 → 原因 → 修复（→ 验证）；多因条目为每个原因配对确认方法和修复 - [ ] 变通方案已标注、已说明代价，并与永久修复配对 - [ ] 最常见的失败排最前；数据丢失类失败插队 - [ ] 专门页面以 Still stuck? + 先收集这些清单结尾 - [ ] 原因链接到概念；多步修复链接到操作指南 - [ ] 底层失败修复后删除对应条目；巡检时盖上 `lastVerified` Source: https://nimbus.ndjp.net/style-guide/troubleshooting/index.mdx