体验日志到底是什么，里面又该放些什么内容

体验日志是对产品发生了哪些变化所做的、带有日期的记录，它是写给真正受这个变化影响的那些人看的，而不是写给把它发布出去的那个团队自己看的。每一条记录都会指明一个具体的变化，说明它是从什么时候开始生效的，也说明读者应该对此做些什么，而对大多数记录来说，读者其实什么都不用做。正是这最后一点，把体验日志和提交日志区分开来：提交日志是写给写代码的人看的记录，体验日志则是写给使用它的人看的记录。

体验日志到底是什么，更准确地说

一份按日期排列的记录列表，最新的排在最前面，每一条都用读者能够自行核实的说法，描述一个单一的变化。它说的不是团队做了什么，而是现在有什么地方不一样了。“重构了计费服务”是一条提交信息。“发票现在会把税额单独列成一行”才是一条体验日志记录，因为它告诉读者一件她可以在自己账户里亲自核实的事情。

这种格式很古老，也是被有意设计得很简单的：每次发布或每一天配一个标题，下面跟一份简短的列表，有时候还会带一个分类标签。Keep a Changelog是这种形式里被引用得最多的规范，它之所以存在，是因为大多数跳过规范的项目最终都会转而直接把提交历史一股脑倒出来，而这回答的其实是一个和读者本来想问的完全不同的问题。

这五种文档在实际使用中会互相重叠，但它们并不是同一份文档，区别就在于读的那一刻，究竟是谁把它拿在手里。体验日志是那种被设计成方便被搜索、方便日后再次被链接引用的文档，正因如此，它的每一条记录都比其他文档更需要稳定的日期和稳定的网址。

一条体验日志记录里到底应该放些什么

按这个顺序，四样东西：发生了什么变化，用用户或调用方会注意到的说法表达出来；这个变化是什么时候生效的；它属于哪个分类（added、fixed、changed、removed是最常见的四种）；以及在重要的时候，读者应该为此做些什么。指向更多细节的链接是受欢迎的。一整段内部理由的说明则不受欢迎，因为读者问的从来不是为什么，而是发生了什么。

## 2026-09-07

### Added
- 发票现在会以客户账户所用的货币，把税额单独列成一行。

### Fixed
- 把报表导出为 CSV 时，如果报表超过 10,000 行，
  现在不会再丢失最后一行了。

这种形式可以从一次只有两行的更新，一路扩展到一次发布里上百条记录，而完全不需要改变自身的结构，这才是判断一种格式到底管不管用的真正标准：在最忙的那一周和最清闲的那一周，读起来是不是一样。

谁来写体验日志，又是在什么时候写

是真正做出这个变化的人，在它被发布的那一刻就动手写，而不是让一位技术编辑一周之后再从工单里把它重新拼凑出来。真正碰过代码的人，才知道对用户来说到底发生了什么变化；事后才写出来的总结，往往描述的是那张工单本身，而不是最终实际发布出去的东西，而这通常会比真实的范围更宽，或者更窄。有些团队会在一条记录公开之前加入一道审阅流程，主要是为了拦住不小心混进来的内部用语，而这道审阅必须足够快，快到那条记录还能在当天就发布出去。

体验日志到底应该放在哪里

放在它自己独立的页面上，配一个稳定的网址，并作为一个订阅源来分发。如果被埋在某个设置菜单里，或者藏在代码托管平台的一个发布标签下面，它就只能触达那些原本就已经知道该去哪里找的人。一个公开的页面可以从工单里被链接过来，可以被一篇评测引用，也可以被人订阅。订阅源和页面本身同样重要：一个每月才去检查一次产品体验日志的读者是很少见的，一个订阅了它的读者却不是，而只有订阅源才能真正服务好后面这一类人。

它和发布说明到底有什么不同

这两者总是被人不断混淆，而它们之间的差别又足够大，大到把二者混在一起会产生一份对两类读者都没有真正服务好的文档。体验日志对比发布说明会把这个区别完整地讲一遍；简单来说，体验日志是完整的、按时间顺序排列的记录，而发布说明则是一份经过精心筛选的子集，专门写来让一次更新听起来值得拥有。一个产品通常两者都需要，分别对应读者一天当中不同的时刻。

什么才让一份体验日志值得一读

对自身覆盖范围的具体和诚实。“各种缺陷修复”这句话，会教会读者不再打开这个页面，因为它没有承诺任何她可以核实的东西。即使只是一个很小的修复，一条能准确说出到底哪个具体行为发生了变化的记录，才是能让订阅一直保持活跃的那种记录。这份自律同样适用于被省略的内容：一份只发布胜利、却从来不发布对某个曾经损坏的东西所做修复的体验日志，读起来就像披着体验日志外衣的营销文案，而读者是会察觉到这一点的。

版本管理上的自律同样重要。语义化版本控制和你的体验日志展示了版本号和记录应该如何对应起来，这样一个正在浏览版本历史的读者，得到的就是同一个信号被重复了两次，而不是两个互相矛盾的信号。

体验日志到底是怎么生成出来的

有两种方式，而绝大多数真实的配置其实都是两者的混合。自动化生成会读取提交信息，通常采用Conventional Commits格式，然后在没有任何人碰过输出结果的情况下，把它们转换成一条条记录；从 Conventional Commits 到体验日志覆盖了这整条流水线。经过筛选的生成方式，意味着有人会手动写出或者编辑每一条记录。自动化的输出速度更快，也绝不会漏掉任何一个已经合并的拉取请求，但它会把每一条含糊不清的提交信息原封不动地继承下来，所以大多数采用自动化的团队，最终还是会在发布之前保留一道轻量的编辑环节，而不是直接把未经处理的原始输出展示出来。

FAQ

是不是每一个产品都需要一份体验日志? 只要有用户会受到变化影响，任何产品都需要，不管它是一款 SaaS 应用、一个内部工具，还是一个公开的 API。形式会随之调整（API 体验日志的读法和面向消费者的应用完全不同），但这份需求本身并不会变。

用软件领域的说法来讲，体验日志到底是什么? 和上面完全一样的定义：一份按日期排列、按时间顺序记录软件发生了哪些变化的清单，它是写给使用这个软件的人看的，而不是写给构建它的人看的。

体验日志能不能从提交记录里自动生成出来? 可以，而且很多团队做的正是这件事，通常是从 Conventional Commits 格式的提交信息里生成。这样做的代价在于，一条自动生成的记录，清晰程度完全取决于它所来源的那条提交信息有多清晰，所以在发布之前的一道审阅环节，就是用来专门抓出那些需要重新措辞的记录的。

体验日志和版本历史是同一回事吗? 两者之间足够接近，接近到这两个说法经常被人互相换着用。版本历史有时候只是一份不带任何描述的版本号加日期的清单；而体验日志则始终会包含到底发生了什么变化这一点。

本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。

changeloop 相关页面： changelog 示例, 开发者文档