好的发版说明在第一行就说出对读者改变了什么,按类型分组,标明日期和版本,并让破坏性变更单独成条。糟糕的要么是空话(「修复问题并优化体验」),要么是提交日志。示例里,利益优先的格式点击率 3.1%,含糊格式是 1.2%。
读完你会知道
- 第一行写给读者:他们现在能做什么,或不再遭受什么
- 按类型分组(新增、变更、弃用、移除、修复、安全),并标明 ISO 8601 日期
- 对格式做测试:示例里利益优先的说明点击率 3.1%,是含糊说明 1.2% 的 2.6 倍
发版说明是写给谁的
发版说明按顺序告诉用户三件事:改了什么、是否影响我、去哪里看细节。好的例子在前两行就把三件事说完。糟糕的要么是空话(「修复问题并改进体验」),要么是把团队做过的所有事一股脑倒出来,让读者自己猜哪一行跟自己有关。
格式比篇幅更重要。Nielsen Norman Group 发现,79% 的测试用户总是扫读新页面,只有 16% 逐字阅读,所以发版说明是被扫读的。Apple 的 App Store Connect 要求第一个版本之后的每个版本都填写「此版本的新功能」,最多 4,000 个字符,但这个上限只是天花板,不是目标。本文给出带批注的好坏示例、一份示例数据上的格式对比和一份检查清单。常与发版同时发出的发布邮件见产品发布邮件;版本号怎样传达变化见应用版本号。
让人读下去的发版说明由什么构成
Keep a Changelog 约定写给开源项目,但在任何地方都有用,它给出一套简短的规则。更新日志是给人看的,不是给机器看的。每个版本都有一条记录。相似的改动要分组。版本和各节可以直接链接。最新版本放最前面,每个版本都标明发布日期,采用 ISO 8601 格式(年-月-日,如 2026-11-21),避免与各地区的日期写法混淆。它还列出六种改动类型。
| 类型 | 用于 | 回答读者的什么问题 |
|---|---|---|
| Added(新增) | 新功能 | 我现在能做什么? |
| Changed(变更) | 现有行为的改变 | 什么用法不一样了? |
| Deprecated(弃用) | 即将下线的功能 | 我该停止用什么? |
| Removed(移除) | 已下线的功能 | 我这里什么坏了? |
| Fixed(修复) | 缺陷修复 | 我遇到的问题解决了吗? |
| Security(安全) | 漏洞 | 我需要马上更新吗? |
一次发布超过几条时,用这六种类型当小标题。面向普通用户的 App,可以合并成「新功能」和「已修复」,但要保留分组。
| 类型 | 用于 | 读者的问题 |
|---|---|---|
| Added(新增) | 新功能 | 我现在能做什么? |
| Changed(变更) | 现有行为的改变 | 什么用法不一样了? |
| Deprecated(弃用) | 即将下线的功能 | 我该停止用什么? |
| Removed(移除) | 已下线的功能 | 我这里什么坏了? |
| Fixed(修复) | 缺陷修复 | 我遇到的问题解决了吗? |
| Security(安全) | 漏洞 | 我需要马上更新吗? |
Keep a Changelog 1.1.0 的六种改动类型。
反面示例 1:空洞的承诺
「修复问题并优化性能。」
问题在哪。 它没说任何读者用得上的信息。它没告诉读者自己遇到的缺陷是否已解决,所以既没有更新的理由,也没有信任下一份说明的理由。每个版本看起来都一样。
怎么改。 至少点出最显眼的修复及其效果:「已修复:从 iPhone 上传的照片不再旋转。」如果这次只有看不见的改动,就用一句老实话说明:「无可见变化:底层稳定性改进。」
反面示例 2:提交日志
「重构认证中间件。升级依赖。合并 PR #412(fix-null-check)。更新 CI 配置。把配置键
timeout改名为timeout_ms。」
问题在哪。 它是写给团队的,不是写给读者的。大多数行都是噪声,而真正重要的那一行,改名的配置键,会让安装出问题,却被埋在里面。Keep a Changelog 直接说明了理由:把提交日志当作更新日志是个坏主意,因为里面全是噪声,条目应当描述对终端用户有意义的差异。
怎么改。 只保留读者必须采取行动的内容,并说明该做什么:「变更:timeout 设置改名为 timeout_ms,单位为毫秒。升级之前请先更新你的配置。」
正面示例 1:利益优先,按类型分组
4.2 版,2026-11-21 新增 - 可从报告菜单把任何报告导出为 CSV,方便把数字分享给应用外的人。 - 深色模式跟随手机设置。 已修复 - 从 iPhone 上传的照片不再旋转。 - 搜索能找到名称带重音符号的条目。
为什么有效。 每一行都以读者能做的事、或不再遭受的问题开头,用平实的话写。条目分了组,读者可以在「已修复」里直接找自己的那个缺陷。日期和版本让人能把它和旧说明区分开。这里是四条,不是四十条:只列用户会注意到的,其余的放链接。
正面示例 2:破坏性变更
提醒:v1 API 将于 2027-03-01 停用。 谁受影响:所有调用
/v1/events的人。怎么做:改用/v2/events;响应字段相同,只是ts改为timestamp。怎么迁移:[迁移指南]。v2 自 2026-09-01 起可用。
为什么有效。 它按顺序写出日期、谁受影响、该做什么和指南在哪里,还用了扫读的人不会错过的加粗开头。破坏性变更和弃用值得单独成条,而不是列表里的一行,并且要提前通知,建议至少提前一个完整的发布周期。
让说明读起来顺的措辞规则
- 以动词或用户看得见的东西开头。「可把任何报告导出为 CSV」胜过「我们很高兴地宣布推出导出功能」。
- 用用户看得见的名称。 菜单叫「报告」,就写「报告」,不要用内部项目代号。
- 一行一个改动。 带「和」的一行通常藏着两个改动,其中一个会被漏掉。
- 修复要写出症状。「搜索能找到带重音符号的条目」让撞到这个缺陷的人知道说的就是自己。
- 不要夸张,也不要道歉套话。「太棒了」「给您带来不便深表歉意」增加了长度,却没有增加信息。
- 必要时说明哪些没变。「你已有的导出仍然可用」能避免一张客服工单。
让格式匹配渠道
| 渠道 | 长度 | 语气 | 包含 |
|---|---|---|---|
| 应用商店文案 | 3 到 6 行短句(该字段允许 4,000 个字符,但很少有人读过前几行) | 友好、平实 | 最重要的两项变化、最重要的一项修复 |
| 应用内提示 | 1 到 3 行 | 直接 | 一个功能、一个按钮 |
| 更新日志页 | 完整,按类型分组 | 准确 | 日期、版本、六种类型、链接 |
| 发布邮件 | 主题行加 3 个要点 | 以利益为主 | 主要利益、完整说明的链接 |
先写更新日志页,因为它是完整记录,再从中裁出较短的版本。千万不要先写短版本,让页面落在后面。
格式会改变互动吗?示例数据上的对比
示例数据:三种说明格式,各发给 5,000 位用户,衡量「查看详情」的点击。
| 格式 | 点击 | 点击率 |
|---|---|---|
| 「修复问题并优化体验」 | 60 | 1.2% |
| 提交日志式列表 | 45 | 0.9% |
| 利益优先、按类型分组 | 155 | 3.1% |
利益优先版本的点击率是含糊版本的 3.1 ÷ 1.2 = 2.6 倍。对两者做两比例 z 检验(5,000 个中的 155 个对 5,000 个中的 60 个),合并比例 2.15%,标准误 0.00290,z = 6.5,远超 1.96。这个差距是真的。
含糊版本和提交日志版本之间(60 对 45),z = 1.5,p = 0.14:不显著。这个样本分不出两种糟糕格式孰优孰劣,也没必要分。教训不是某种糟糕格式胜过另一种,而是结构和利益优先,值得拿来和你现在的做法对比测试。
不要停在点击上。要统计读者接下来做了什么:打开了功能、更新了应用,或者不再为旧缺陷联系客服。
按说明格式区分的「查看详情」点击率
示例数据,各 5,000 位用户的百分比发布前的检查清单
- 第一行说的是对读者改变了什么,而不是对团队?
- 条目分了组吗?版本和日期(ISO 8601)看得见吗?
- 每一条都是用户能注意到的改动吗?去掉重构和依赖升级。
- 破坏性变更单独成条了吗?有日期、谁受影响、该做什么吗?
- 每条「已修复」都点出了人们看到的症状吗?
- 短版本链接到完整说明了吗?
在 TapCub 里衡量一次发版带来了什么
拿示例里的 4.2 版,跟踪它的效果。
- 标记发版。 在 配置 › 日期标注 里,在发版日期加一条标注,这样每张图都会在行为变化的地方显示一条线。
- 给链接打标记。 在邮件和应用内提示的链接上加
utm_campaign=release-4-2。网站统计 › 来源 随后显示这个活动的会话和转化。 - 看新功能有没有人用。 在 全端分析 › 行为分析 › 事件分析 里,按天画出新导出功能的事件在该日期前后的变化。比较标注两侧的几周。
- 盯回归。 在 全端分析 › 智能运营 › 监控 给
error_rate建监控,发版后错误上升就会通知你,监测 › 错误 显示受影响的页面和会话。对 App,应用统计 › 质量与归因 › 稳定性 覆盖崩溃。 - 比较说明格式。 发送带不同
utm_content值的版本,按版本比较点击和目标,如上表所示。
TapCub 不撰写或发送发版说明和邮件;这部分用你的邮件工具和应用商店页面。它衡量之后发生了什么。
常见问题
什么是发版说明?
发版说明是对产品某个版本改了什么的简短描述,写给用户看。它说明新增了什么、哪些用法不同了、修了什么,以及出问题时该怎么做,建议带上日期和版本。
好的发版说明是什么样的?
好的例子按类型分组(新增、变更、修复),每一行以读者现在能做的事开头,标明日期和版本,其余的链接到细节。「已修复:从 iPhone 上传的照片不再旋转」胜过「修复问题并优化体验」。
发版说明应该多长?
按受众需要,越短越好:应用商店 3 到 6 行,应用内提示 1 到 3 行,更新日志页要完整。Apple 允许最多 4,000 个字符,但那只是上限。把最重要的变化放最前面。
发版说明应该包含什么?
版本和发布日期、新功能、现有行为的变化、点出症状的缺陷修复、带日期的弃用,以及任何安全修复。对会出问题的改动,写明谁受影响、该做什么。
怎么衡量发版说明有没有用?
给说明里的链接打标记,然后统计点击,以及读者接下来做了什么:使用功能、更新应用,以及为旧问题联系客服的次数。示例里,利益优先的格式点击率 3.1%,含糊的格式是 1.2%。
资料来源
- Keep a Changelog,Keep a Changelog 1.1.0:指导原则、六种改动类型、ISO 8601 日期,以及为什么提交日志不是更新日志。核对日期 2026-11-21。
- Apple,平台版本信息(App Store Connect 帮助):第一个版本之后必须填写「此版本的新功能」,最多 4,000 个字符。核对日期 2026-11-21。
- Nielsen Norman Group,How Users Read on the Web:79% 的测试用户总是扫读,16% 逐字阅读。核对日期 2026-11-21。
这篇文章对你有帮助吗?
我们会根据反馈修改和补充这篇内容。
提交没有成功,请稍后再试。
谢谢你的反馈,我们会据此改进这篇内容。你已经反馈过这篇了,谢谢。

