---
title: "故障排除"
description: "故障页面的指南——原始症状、原因和修复，标题使用读者会粘贴到搜索框的内容。包含清单和搭建命令。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排除

> **需求**
>
> 在工作中行动——在恢复，而非推进。读者有一个错误字符串或症状，会将其粘贴到搜索中（或他们的智能体会这样做）。他们的问题是：*"为什么会看到这个，怎么让它停下来？"* 错误是内容，不是异常——而这正是人类搜索和智能体检索完美对齐的类型，因为两者都匹配精确字符串。

<h2 id="when-to-use-it">何时使用</h2>

故障排除内容存在于两个地方，本指南覆盖两者：

- **内联在故障发生的页面上**——默认做法。在操作指南中使用"What if…"提示框，或在功能页面末尾使用 FAQ 折叠面板。内联形式保持相同的内部结构，但更紧凑：

  > **如果登录失败并显示 `Error: no workspace selected` 怎么办？**
  > CLI 已认证但未指向工作区。运行 `hookline workspace use <name>` 然后重试。

- **每个产品区域的独立故障排除页面**，当内联条目超过约 5 个或同一故障跨多个页面时。

它不是：

- **操作指南。** 操作指南追求目标；故障排除从故障中恢复。"设置投递警报"是操作指南，即使它涉及问题。
- **错误参考。** 如果产品有稳定的错误*代码*，完整的按代码目录是参考材料（每个代码一个条目，统一模板——见[参考指南](/writing/recipes/reference)）；故障排除页面覆盖症状、多原因问题，以及代码无法捕获的"它很慢/它不稳定"的叙述性情况。小型产品合并两者；说明哪个页面负责什么。
- **全局 FAQ。** 有已知答案的问题放在应该回答它们的页面上。故障排除页面按*故障*组织，而非按*问题*。

<h2 id="title--description">标题和描述</h2>

- **条目标题：原始症状——理想情况下是确切的错误信息。** "Error: signature timestamp outside tolerance" 在搜索、检索和侧边栏扫视中都优于 "Signature problems"。较长的信息：保留有区分度的子串，截断到约 70 个字符，用 ASCII `...` 标记截断位置。信息类型（"Error:"、"Warning:"）保留在标题中。没有错误信息的症状型条目使用可观察的表述："Deliveries succeed but arrive twice。"
- **页面标题：** "Troubleshooting *区域*"——例如 "Troubleshooting delivery。"
- **描述公式：** "*区域*常见故障的修复，按症状排列。"

<h2 id="scaffold-this-page">搭建此页面</h2>

安装指南——你的编码智能体会读取完整的骨架和清单，并将其适配到你的产品：

```sh
npx add content-troubleshooting
pnpm dlx add content-troubleshooting
yarn dlx add content-troubleshooting
bunx add content-troubleshooting
```

<h2 id="component-guidance">组件指导</h2>

- **围栏块用于原始信息**——搜索、读者和检索的匹配目标。展示一个具体的现实实例，包含变量值（`skew 512s > 300s` 展示了机制；稳定的子串仍然匹配搜索）。永远不要意译错误；永远不要省略有区分度的部分。
- **加粗的 Cause/Fix/Verify 标签**（或固定的子标题三联体）——统一的内部顺序让慌张的读者能直接跳到 Fix。
- **折叠面板**适合内联形式（功能页面末尾的 FAQ 风格）；在独立页面上，条目保持展开——隐藏的症状不可查找，页面的存在就是为了被扫读。
- **不适用：** Cards、营销语气、以及没有修复的安慰（"这通常是无害的"——那就说明什么时候不是）。

<h2 id="ending">结尾</h2>

独立页面以 **Still stuck?** 结尾——升级路径，附带一个先收集这些信息的列表。这是类型的诚实条款：一个暗示完整性的故障排除页面会让读者困在它遗漏的那个故障上。

<h2 id="thresholds">阈值</h2>

- **内联到约 5 个条目，然后独立页面**——在内联处留下链接。
- **最常见的故障排在前面；数据丢失故障插队。** 排序就是分诊。
- **每个临时方案说明其成本和永久替代方案。** 以修复面目出现的临时方案是技术债务被记录为永久性的方式。

<h2 id="links--freshness">链接和新鲜度</h2>

每个 Cause 链接到解释机制的概念；每个多步骤 Fix 链接到（或本身就是）操作指南。从支持请求和社区问题中获取此页面的内容——这是唯一一种积压自动生成的类型——当产品修复了底层故障时清除条目：修复已不存在问题的修复方案会让读者去寻找一个已经消失的设置。在对照当前发布版本清扫时盖上页面的 `lastVerified` 日期。

<h2 id="agent-notes">智能体备注</h2>

- 这是智能体通过精确字符串匹配检索的类型——围栏块中的原始错误信息就是全部。展示一个具体的现实实例；稳定的子串承载匹配。省略（ASCII `...`）仅属于长信息的*标题*中，且永远不在有区分度的部分。
- 将 Cause → Fix 结构化为智能体可以执行的声明；"检查你的配置"不是修复，`hookline test-event --endpoint <id>` 才是。
- 保持每个条目完全自成一体——条目 N 会在没有条目 N-1 和页面介绍的情况下被检索。

<h2 id="checklist">清单</h2>

建议性——供作者或智能体自查，不是构建门禁：

- [ ] 条目标题是原始信息或可观察的症状（长的截断到有区分度的子串，约 70 个字符）
- [ ] 每个有信息的条目在围栏块中展示一个具体实例；仅症状的条目在第一行说明可观察的行为
- [ ] 固定内部顺序：症状 → 原因 → 修复（→ 验证）；多原因条目将每个原因与其确认和修复配对
- [ ] 临时方案已标注、已说明成本、并与永久修复配对
- [ ] 最常见的故障排在前面；数据丢失故障插队
- [ ] 独立页面以 Still stuck? + 先收集这些信息列表结尾
- [ ] 原因链接到概念；多步骤修复链接到操作指南
- [ ] 当底层故障已修复时清除条目；清扫时盖上 `lastVerified`

Source: https://nimbus-docs.cn/writing/recipes/troubleshooting/index.mdx