---
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.

# 示例

> **需求**
>
> 在工作中行动——读者想要可运行的代码来复制和适配。他们的问题是：*"给我看 X 的可运行代码。"* 不是操作步骤（操作指南），不是课程（教程）：展示某件事*怎么做*的代码，这与做这件事的操作说明是不同的东西——文档鸿沟中可复制代码的那一半。在智能体时代，这是最高杠杆的类型：两种读者角色都从代码示例开始，而智能体会将示例原样粘贴到代码库中。

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

当**代码就是内容**时编写示例——一个值得整体复制的模式、集成、配置。它不是：

- **操作指南。** 操作指南是一个*流程*——跨接口（控制台、CLI、代码）的操作，最后验证。示例是一个*列表*——读者唯一的动作是复制和适配。如果读者必须在代码之外做些事情才能让它工作，要么将它们折叠为一行假设说明，要么写操作指南。
- **参考。** 参考是完整且中立的，按产品接口索引。示例是有选择性且有立场的，按读者目标索引。参考展示 `send()` 接受的每个字段；示例展示你用来批处理的那三个。
- **教程。** 无叙事、无教学、无分部。示例假定能力已具备，然后让路。

这种类型的两条法则：

1. **完整且可运行。** 完整的 import、完整的配置、无省略行——"你需要适配"的片段不是示例，是作业。复制粘贴必须产生页面展示的结果。
2. **经过测试。** 不能运行的示例代码比没有更糟——它在读者的编辑器中失败，带着产品的名字。如果可能，在 CI 中运行；无论哪种方式都盖上 `lastVerified`。

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

- **标题：目标加技术栈。** "Verify signatures **in a Next.js route handler**" · "Debounce webhook bursts **with Redis**。" 技术栈限定词是类型的标题信号——操作指南陈述接口中立的目标（"轮换签名密钥"）；示例命名其代码所在环境，因为代码就是内容。（对操作指南标题语法的有意软化：祈使动词匹配操作指南；技术栈后缀用于消歧。）永远不要写 "Example 3" 或 "Miscellaneous snippets"。
- **描述公式：** "*代码做什么*，为*所写技术栈服务*。"——例如 "在 Next.js 路由处理器中验证 Hookline 签名，拒绝重放。"

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

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

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

**食谱形式。** 多个相关示例可以共享一个页面：页面采用**名词短语分类标题**（"签名验证"、"批处理"），每个 `##` 条目遵循骨架安装的单页面结构，去掉 frontmatter——目标行、假设行、代码、展示结果、工作原理。页面的一个 `lastVerified` 意味着其*最旧已验证*条目的时间。当条目的代码超出一屏时，将其拆分为独立页面。添加相关示例首先放在分类页面上；新页面需要新分类或一个已超出的条目。

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

- **带标题的代码块**（`title="app/api/hooks/route.ts"`）是标志性组件——文件名是承载上下文的关键信息。多文件示例使用代码组；一个文件更好，只要诚实。
- **代码内的注释**承载使用点备注（`// rejects deliveries signed >5 min ago`）——代码注释胜过散文的唯一地方，因为它们在复制粘贴中存活。
- **不适用：** Steps（没有操作步骤）、Cards、折叠面板（隐藏的代码不可查找且不可提取）、Tabs 用于语言*除非每个标签页都维护和测试过*——未测试的标签页是隐藏在已测试标签页后面的坏示例。

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

**展示结果 → 工作原理（需要时）→ 另请参阅。** 无验证章节（操作指南的招式——这里展示结果和测试承担了那个分量）、无后续步骤旅程（读者为代码而来，带着代码离开）。

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

- **每个示例一个目标。** 标题测试：如果需要"和"，拆分。
- **解释不得超出代码。** 当工作原理开始需要段落而非要点时，说明一个概念或操作指南试图挣脱——改为链接它。
- **处理模式所涉及的错误；其余的让它抛出。** 提前说明错误约定，使条目不在裸正常路径和生产加固之间摇摆。目标不需要的防御性代码是伪装的散文。
- **食谱页面：每个条目遵循相同内部模板**，按目标索引，最需要的排在前面。

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

链接模式背后的概念和每个魔术值的参考；从相关操作指南*反向*链接到示例（"只想要代码？ →"）。新鲜度是这种类型的全部声誉：示例是经过测试的制品，在每次涉及它们的 API 发布时重新运行（如果可能用 CI），盖上 `lastVerified`——一个代码无法再编译的食谱是产品无人维护的最响信号。

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

- 智能体逐字提取示例，所以**完整性就是正确性**：一个省略的 import 变成别人代码库中幻觉出的 import；代码中的 `...` 变成任何东西。
- 将假设在页面上表述为可验证的事实（版本、环境变量）——智能体无法从你项目的渲染截图中推断出来。
- 全程使用真实值；占位符仅在 `<尖括号>` 中，且仅在真实值不可能存在时。
- 工作原理要点是检索黄金：它们将不明显的行与原因配对在一个块中，这正是阻止智能体"简化"关键部分（`req.text()` → `req.json()`）的东西。明确标记任何依赖特定提供者行为的要点，使适配的智能体知道该重新检查什么。

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

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

- [ ] 标题是目标加技术栈（食谱页面：名词短语分类）；一个目标
- [ ] 假设在一行中以可验证事实表述（版本、环境）
- [ ] 代码完整且粘贴即可运行——完整的 import、零省略、严格设置下通过类型检查
- [ ] 展示结果存在：粘贴代码产生的输出，以及如何触发
- [ ] 真实值；占位符仅在 `<尖括号>` 中
- [ ] 工作原理仅覆盖不明显的行；特定提供者假设已标记
- [ ] 错误处理限于模式所涉及的范围
- [ ] 变体是链接，不是附加的列表；食谱条目共享一个内部模板
- [ ] 在当前发布版本上测试过（如果可能用 CI）；已盖上 `lastVerified`（食谱：最旧条目）

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