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

# 变更日志

> **需求**
>
> 处于工作、正在查资料 —— 读者维护着一个昨天还能用的集成。他们的第一个问题：*“改了什么，会影响我吗，我该做什么？”*
>
> 不能传达变更的文档，到下一季度就是错的。对智能体来说赌注更高，因为变更日志正是模型过时知识被纠正的地方。

## 适用场景

每个产品（或每个明确版本化的界面）一个变更日志。两个承重区分：

- **记录与政策：** 按日期记录改了什么，放在这里；版本如何工作、如何迁移，放在各自页面，并从每条破坏性条目链接过去。
- **两种体裁，按读者关注点选择：**
  - **按日期分标题** —— 适用于持续交付的产品界面。每次发布一个日期分节；条目按变更命名。
  - **按版本分标题** —— 适用于版本化产物（SDK、命名的 API 版本）：每个版本一个分节（`## [2.14.0] — 2026-06-18`，库还要有 `Unreleased` 分节）。下面的条目规则在*每个版本分节内部*适用。维护者的问题 “2.13 到 2.14 之间改了什么？” 在按日期的日志里无法回答 —— 如果读者会固定版本，就按版本分标题。

变更日志不是：

- **提交日志。** 变更日志是写给人类（如今也写给智能体）的 —— 精挑细选、收益优先的条目，而不是合并消息的倾倒场。一项变更如果不值得解释，就不值得列出。
- **发布营销。** 发布文章用于说服；变更日志条目用于告知。如果有发布文章，从条目链接过去 —— 不要用它替换条目。
- **迁移指南。** 条目说明*某事*会破坏什么，并链接出去；逐步迁移过程是一篇操作指南（大型迁移可写专门的迁移指南）。

## 标题与描述

- **页面标题：**“变更日志” —— 固定的、预期的字符串。
- **条目标题：变更本身，具体且自成一体。** “重试退避现在可按端点配置” —— 不要 “投递改进”（什么都没说），也不要裸版本号（版本是分节标题，不是条目）。
- **页面描述公式：**“*产品*的每次重要变更，按日期记录，并标出破坏性变更。”

## 脚手架生成本页

安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：

```sh
npx @cloudflare/nimbus-docs add content-changelog
yarn nimbus-docs add content-changelog
pnpm nimbus-docs add content-changelog
bunx @cloudflare/nimbus-docs add content-changelog
```

## 组件建议

- **分节标题（日期或版本）+ 条目小标题**是结构。**破坏性标记以粗体放在条目正文开头**（`**Deprecated · Breaking, effective 2026-09-18**`）—— 这是扫读者和订阅源读者第一眼看到的内容，又不会污染标题锚点。在渲染页面中，标题行上的 Badge 组件可以呼应它。
- **分类标签**（六个标准分类：Added / Changed / Deprecated / Removed / Fixed / Security）作为一致的粗体前缀 —— 让页面既能用眼睛筛选，也能被机器筛选。
- **不适合：** Steps（迁移步骤住在链接的指南里）、卡片、截图（改为链接到展示新 UI 的文档 —— 变更日志里的截图会原地永久腐坏）。

## 结尾

变更日志没有结尾；它只累积。契约放在*顶部*（政策链接、订阅渠道）以及每条条目里（链接到描述新状态的页面）。

绝不*悄悄*改写已发布的条目。如果某条后来发现写错了，比如漏标了破坏性变更，就修改它，*并*发布一条带日期的更正，让按版本和按日期扫读的读者都能看到。

## 阈值

- **条目正文 ≤ 3 句。** 更深的细节放在链接的详情页、迁移指南或发布文章里。
- **改变已记录行为的条目要链接到更新后的文档页。** Fixed 和 Security 条目在有对应页面时链接到相关参考或故障排查页 —— 修复了文档从未记录的行为，无处可指，这没关系。
- **每条破坏性/弃用条目都要写明：影响谁、该做什么、日期。** 缺任何一项，就不该发布。

## 链接与时效

条目要深链到稳定的文档锚点，这也是[参考锚点](/style-guide/reference/)永不移动的又一个原因。条目标题也是永久链接，所以要保持稳定。

发布条目和更新它所链接的页面是*同一个*动作。宣布某个字段的条目，若参考页还没展示该字段，就是在记录一个不存在的产品。

## 智能体说明

- 变更日志是**纠正先验知识的地方**：已弃用的东西在训练数据里还活着，所以 Deprecated/Removed 条目正是阻止智能体推荐它们的内容。把它们写成智能体可执行的平铺陈述句：“`attempt_count` 已弃用；请使用 `attempt`。”
- 日期用 ISO 格式（`2026-06-18`）；“上个月” 在被检索的块里毫无意义。
- 每条条目自成一体：完整字段名、完整功能名 —— 被单独检索的条目必须单独看也讲得通。
- 个性永远不能替代事实。没有具体信息的俏皮话是空话，读者和智能体都无法据此行动；想要语气，就加在事实*之后*，而不是代替事实。

## 检查清单

建议性 —— 供作者或智能体自检，永不作为构建闸门：

- [ ] 有意选择了体裁：按日期分标题（持续交付的界面）或按版本分标题（固定产物，库还要有 Unreleased）
- [ ] 条目按变更命名，自成一体，倒序排列
- [ ] 已分类：Added / Changed / Deprecated / Removed / Fixed / Security
- [ ] 破坏性标记放在条目正文开头，含 影响谁 + 该做什么 + 日期
- [ ] 弃用公告与移除是两个独立条目；绝不悄悄进行
- [ ] 改变行为的条目链接到更新后的文档页（Fixed/Security 在有目标时链接）
- [ ] 条目正文 ≤ 3 句；先讲影响再讲机制；深度放在链接页面
- [ ] 链接的文档页在发布时已更新
- [ ] 更正既修改原条目，又新增带日期的更正条目
- [ ] 订阅渠道（至少 RSS）链接在顶部；条目锚点稳定

Source: https://nimbus.ndjp.net/style-guide/changelog/index.mdx