软件发布说明：它是什么，以及应该写哪些内容
阅读约 1 分钟
软件发布说明，是随软件某个版本一起发出的文档，告诉读者这个版本改了什么、这些改动会影响谁，以及读者如果需要做点什么，该做什么。它每次发布写一份，读它的人包括：正在决定要不要升级的人，想确认自己遇到的问题是否已修复的人，以及负责支持这个产品的人。好的发布说明简短、针对具体版本，而且对任何会造成破坏的改动都坦诚相告。
| 类型 | 读者 | 内容 | 发布位置 |
|---|---|---|---|
| 面向客户 | 产品的用户 | 新功能、修复、行为变化 | 应用内、体验日志页面、邮件 |
| 面向开发者 | 调用你的 API 或 SDK 的人 | 破坏性变更、弃用、新端点 | API 文档、开发者体验日志 |
| 企业或 IT | 负责推送更新的管理员 | 已知问题、系统要求、迁移步骤 | 每个版本一份发布说明文档 |
| 内部 | 支持、销售、QA | 发布了什么、该怎么对客户说、哪里有风险 | 内部频道或维基 |
什么是软件发布说明？
它是对某一次发布的、带日期和版本号的摘要。发布说明要为一个当时不在现场的读者回答三个问题：有什么不同，会不会影响我，我需要采取行动吗。项目的完整历史是体验日志，提交记录则是给写代码的人看的。
同样的事实既可能出现在体验日志条目里，也可能出现在发布说明里。区别在于取舍和读者：体验日志列出每一项值得注意的改动，而发布说明把读者会注意到的改动放在前面并加以解释。体验日志与发布说明的区别对这条界线做了详细划分。
软件发布说明应该包含什么？
写上版本号和日期、一段话的摘要，然后按读者能用它做什么来给改动分组。对每一项改动，用读者的话说明有什么不同、谁会受到影响、是否需要采取行动。
一份完整的说明包含这些部分：
- **版本号和发布日期。**采用和你的标签一致的格式，读者才能把说明和某个构建对应起来。
- **摘要。**两三句话：这次发布是为了什么，升级是否需要读者做什么。
- **新功能和改进。**读者现在能做什么，而不是代码里现在多了什么。
- **修复。**消失的是什么症状，以及它从哪个版本开始出现。
- **破坏性变更和弃用。**什么将停止工作、什么时候，以及该用什么替代。如果有，就放在最前面。
- **已知问题。**你明知有问题却已经发布的东西，如果有变通办法就一并写上。
- **要求和升级步骤。**支持的平台、最低版本、迁移命令。
重构、没有可见影响的依赖升级和内部工单就不要写了。如果读者注意不到这项改动，它就属于 git 历史。如何写出用户真正愿意花时间读完的发布说明讲了措辞和顺序。
一份软件发布说明是什么样子？
下面是为一个虚构的命令行工具写的简短示例。重要的是它的结构，而不是内容。
## 2.4.0 (2026-10-08)
Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.
### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
with "unknown key". Rename the key; nothing else changes.
### New
- Exports stream to disk, so files over 100 MB no longer time out.
### Fixed
- Search works again for queries containing a hyphen. Broken
since 2.3.0.
### Known issues
- Windows paths longer than 260 characters still fail. Use a
shorter output directory for now.破坏性变更放在最前面，并附上读者会看到的确切错误文字，因为人们会去搜索错误信息。修复一条写明了它是从哪个版本坏的，读者就能把它和自己的问题开始的时间对上。已知问题给出了变通办法，这比保持沉默好。发布说明示例里有更多适用于各类条目的措辞。
不同的读者，软件发布说明有什么不同？
保留一个事实来源，再为每类读者写一个版本。事实不变，变的是细节程度。客户想用一句话看到好处，管理员想看到要求和已知问题，开发者想看到确切的名称和版本，支持团队想知道工单来了该怎么回答。
对 API 产品来说，面向开发者的版本最需要用心，因为在你看来只是个小修复的改动，对调用方可能就是一次故障。API 体验日志和破坏性变更讲的就是这类读者。至于内部版本，对内发布说明介绍了支持和销售需要、而客户不需要的内容。
软件发布说明应该发布在哪里？
发布在读者提出问题时本来就在的地方。对移动应用来说，那是应用商店的页面，平台为每个版本提供了发布说明字段；Apple 记录了如何为构建版本提供发布说明。对网页产品来说，是应用里链接到的体验日志页面。对库来说，是发布页面，以及仓库里的一个文件，详见 GitHub 发布说明。
让每个版本都有一个稳定的 URL，方便支持团队引用，并且保留旧版本。用 2.2 版本的读者，也需要 2.3 和 2.4 的说明。如果你想要一个起步的结构，发布说明模板提供了可以复制的标题。
发布说明应该写多长？
需要多长就写多长，不必更长。补丁版本可以只有三行。带迁移的大版本需要一页，很可能还要从说明里链接到一份单独的迁移指南。判断的标准是：读者扫一眼第一屏，能不能知道这次发布是否影响自己。如果不能，就把摘要往上移，其余的删掉。发布说明最佳实践列出了哪些做法经得起时间考验，哪些只是习惯。
FAQ
什么是软件发布说明? 它是对软件某次发布中变化的带版本号的摘要，写给使用或支持这个软件的人。内容涵盖新功能、修复、破坏性变更，以及读者必须做的事。
发布说明和体验日志有什么区别? 体验日志是对所有值得注意的改动的完整持续记录。发布说明则是关于某一次发布的信息，经过挑选和改写，写给正在决定是否升级的读者。许多团队会把某个版本的体验日志条目直接作为它的发布说明发布。
谁来写软件发布说明? 通常是产品经理、技术文档工程师，或者发布这项改动的工程师，再由另一个人把关语气。最好的效果来自离改动最近的人起草，再由第二个人站在读者的角度编辑。
小版本也需要发布说明吗? 需要，短一些就行。即使是补丁版本，也应该说明修复了什么、读者是否需要采取行动。一行说明也比没有好，因为”错误修复与改进”什么都没告诉读者。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。