发布说明是信，不是日志：vibe 项目该怎么写更新公告

发布说明不是更新日志的复制粘贴：它是写给用户看的信

很多 vibe 项目的发布说明读起来像一份机器生成的清单：“修复了若干 bug，优化了性能，改进了体验。”用户读完不知道发生了什么、跟自己有什么关系，下次也就不再点开了。发布说明的真正读者不是开发者自己，而是三类人：正在用的用户（想知道“这次更新对我有什么用”）、正在观望的人（想知道“这个项目是不是还在好好维护”）、以及未来的你（想知道“当时为什么改了这一处”）。写给这三类人看的东西，和写给代码仓库看的提交记录，本来就不该是同一份。这篇文章讲清楚发布说明该怎么写、按什么结构写、哪些话不该写，并给出一套可以直接套用的模板。文中的示例项目“记账小助手”和版本号、更新内容均为虚构示例，只用来演示写法。

先建立一个判断标准：好的发布说明，用户读完能回答三个问题——这次变了什么、对我有什么影响、我需要做什么。变了什么要具体到功能名，不要用“若干”“部分”“相关”这类词；影响要落到使用场景上，不要只写技术名词；需要做什么要明确说出来，包括“什么都不用做”——明确告诉用户不用做，也是一种有用的信息。反过来，如果一篇发布说明读完，用户还是不知道要不要更新、更新后要注意什么，那它就是没写好，不管它列了多少条。

结构：四段式就够了，别写成论文

推荐的结构是四段，顺序固定，篇幅依次递减。第一段是一句话总览：这次版本的核心变化是什么，用用户能听懂的话说。比如“2.3 版本给报表加了按月对比，你不用再导出数据自己算了。”一句话，不要铺垫，不要写“我们很高兴地宣布”。第二段是“新功能”，每个功能一到两句话，写清楚“能干什么”和“在哪找到”。第三段是“修复与改进”，只列用户能感知到的修复——界面错位、闪退、数据对不上这类；纯内部重构、依赖升级，用户感知不到的，不用列，或者合并成一句“顺带做了一些内部整理”。第四段是“需要注意”，包括需要重新登录、数据迁移、旧功能下线、价格变化，凡是用户不做点什么就会踩坑的，都要写在这里，而且要放在显眼的位置，不要藏在末尾。

这个结构有一个好处：它强迫作者做取舍。vibe 项目的更新常常一次改很多地方，AI 生成的提交记录能列出二三十条，但用户只关心其中三五条。取舍的标准是“用户感知”：用户点开应用能不能感觉到变化？能，就写；不能，就不写。还有一个取舍标准是“风险”：改动有没有可能让用户现有的用法失效？有，就必须写进“需要注意”，哪怕它看起来只是个小调整。很多项目的口碑事故，都是因为把一个“需要注意”写成了“改进”，用户更新后发现旧功能没了，第一反应不是“哦原来改了”，而是“这东西把我的东西弄坏了”。

写法：说人话、给场景、标出影响范围

说人话的第一条是：不要用只有开发者懂的词，或者用了就立刻解释。比如“我们重构了账单聚合层”不如写成“报表打开速度变快了，以前要等三秒，现在基本秒开”。第二条是给场景：不要只写功能名，要写用户在什么情况下会用到它。比如“新增了按月对比”不如写成“月底对账时，你可以直接看到这个月比上个月多花了多少钱，不用再导出表格自己算”。第三条是标出影响范围：这个变化影响所有用户，还是只影响用某个功能的用户？影响范围写清楚，用户才能判断自己要不要仔细看。举个例子：“这次更新只影响用 iCloud 同步的用户，其他用户不受影响”——一句话，就帮 90% 的用户省了阅读时间。

还有几类话建议直接删掉。第一类是空话：“我们一直在努力改进产品体验”“感谢大家的支持”——放在发布说明里就是噪音，感谢可以放在文末一句，不要占正文篇幅。第二类是技术自夸：“采用了最新的某某架构”——用户不关心架构名，只关心结果。第三类是模糊词：“若干”“部分”“相关优化”——每个模糊词背后，都是作者自己也没搞清楚到底改了什么的表现。写的时候有一个自测方法：把发布说明念给一个没用过这个产品的朋友听，他能复述出“这次变了什么、对我有什么影响”就算通过；复述不出来，就继续改。

版本号与节奏：让用户一眼看出这次更新有多大

版本号本身就是一种沟通工具，前提是它有规律。最常用的是三段式：大版本（有 breaking 变化或重大功能）、小版本（新增功能但兼容）、补丁（只修问题）。比如从 2.2 到 2.3，用户能预期“有新功能、不用重新学”；从 2.3 到 3.0，用户能预期“可能有变化需要适应”。关键是保持一致：不要这次用 2.3.1 表示大改版，下次又用 3.0 表示只修了个错别字。vibe 项目因为更新频繁，特别容易在版本号上随意——AI 生成的版本建议常常没有统一口径，开发者随手就用了。建议在项目里定一条简单的规则并写下来，发布说明里每次都按规则标版本号，用户慢慢就会建立起预期。

发布节奏也值得单独定一下。频繁的小更新和攒着的大更新各有利弊：小更新的好处是每次变化小、用户容易接受，坏处是发布说明容易写成流水账；大更新的好处是每次都有故事可讲，坏处是一次改太多、出了问题不好定位。对个人 vibe 项目，一个实用的节奏是：修问题的补丁随时发、只写一句话；功能更新攒到“一句话能讲清楚”的程度再发，比如“报表加了按月对比”就是一个可以单独发的版本。不要为了“显得活跃”而硬凑版本，也不要把三个月的功能攒成一篇谁也读不完的长文。发布说明的篇幅，应该和这次更新对用户的影响成正比。

发布渠道：同一份内容，三种写法

同一份发布说明，在不同的渠道要写成不同的样子。应用内更新提示要最短：标题一句话、要点三到五条、附一个“查看详情”的链接，用户在弹窗里不会读长文。官网或博客的发布文章可以最长：可以讲背景、讲为什么做这个功能、贴两张截图，适合想深入了解的用户。社交媒体的版本要最抓人：一句话讲核心变化、配一张图、带一个链接，不要把完整清单搬过去。三个渠道共用同一份事实，但篇幅和语气各不相同——这不是重复劳动，而是针对不同阅读场景的适配。很多项目只写一种，然后原样粘贴到所有渠道，结果是弹窗里塞了长文、社交媒体上贴了清单，两边都读不下去。

还有一个渠道容易被忽略：给老用户的邮件或站内信。它的作用不是通知，而是召回：告诉那些已经一段时间没打开应用的用户，“你上次提的那个问题修好了”或者“你想要的那个功能上线了”。这种信的写法和发布说明正好相反：不要列全部变化，只讲和收信人有关的那一两条。比如给提过“报表不能对比”的用户发一句“按月对比上线了，你可以直接在报表页看到”，比群发一篇完整发布说明有效得多。前提是你真的记录了用户反馈，并且能对应到具体的人——这也是为什么平时要把用户反馈按主题归档，而不是散落在聊天记录里。

模板与检查清单：照着填，填完就能发

最后给一个可以直接套用的模板。标题格式：版本号 + 一句话核心变化，例如“2.3：报表支持按月对比”。正文第一段：一句话总览。第二段：新功能，每条格式为“功能名：场景 + 位置”，例如“按月对比：月底对账时直接看本月与上月的差额，位置在报表页右上角”。第三段：修复与改进，只列用户可感知的条目，每条写清楚“之前什么样、现在什么样”。第四段：需要注意，逐条列出需要用户操作的事项，没有就写“本次更新无需任何操作”。文末附一句：反馈渠道（邮箱或表单链接）和下一版本预告（如果有的话，一句话即可）。

发之前按这张检查清单过一遍：标题里有没有版本号和核心变化；每条新功能有没有场景和位置；修复条目是不是用户能感知到的；需要注意里有没有漏掉必须用户操作的事项；有没有模糊词（若干、部分、相关）需要替换成具体表述；有没有把技术名词翻译成人话；三个渠道的版本是不是分别准备好了。全部通过再发。发布说明写得好，带来的不只是“用户知道更新了什么”，还有一种更长远的东西：用户会开始相信，这个项目的每一次更新都是经过思考的。这种信任，就是 vibe 项目从“能跑的演示”变成“值得长期用的产品”之间，最关键的一步。

反面教材：五种最常见的糟糕发布说明

先看五种反面典型，对照一下自己的项目有没有中招。第一种是“谜语型”：“本次更新包含多项改进与问题修复。”读完等于没读，用户不知道改了什么，也不知道要不要更新。这种写法的问题不在于短，而在于没有信息量——短不是错，没信息才是错。第二种是“技术报告型”：“重构了账单聚合层，升级了某某依赖，优化了查询计划。”开发者读得懂，用户读不懂，发布说明的读者是用户，不是代码评审。第三种是“流水账型”：把二三十条提交记录原样贴出来，用户翻三屏都找不到和自己有关的那一条。流水账的问题不是内容错，而是没有取舍——取舍本身就是作者的责任，不能推给读者。

第四种是“报喜不报忧型”：新功能写得天花乱坠，需要用户注意的变化却一个字不提，比如旧功能下线了、免费额度变了、登录方式改了。用户更新后踩坑，第一反应是被欺骗，信任的损失远大于功能本身的价值。第五种是“情感泛滥型”：全文都在讲团队多么努力、多么感谢用户，具体变化只占两行。感谢本身没有错，但发布说明不是感谢信，情感表达应该控制在一句话以内，剩下的篇幅全部留给事实。五种反面典型有一个共同点：作者写的时候想的是“我要交代我做了什么”，而不是“用户需要知道什么”。把主语从“我”换成“你”，很多毛病自己就改掉了。

进阶：用发布说明做产品沟通，而不只是通知

发布说明写到一定水平后，可以承担更多的沟通任务。第一是讲“为什么”：不只是说“加了按月对比”，而是说“很多用户反馈月底对账要导出表格自己算，所以我们加了按月对比”。一句话的背景，能让用户感到被听见，也能让观望的人判断这个项目是不是在认真听反馈。第二是讲“取舍”：有时候一个功能的上线意味着另一个功能的调整，比如“为了让报表打开更快，我们暂时下线了导出 PDF 功能，正在重做，下个版本回来”。把取舍讲出来，用户反而更能理解；藏着不说，等用户自己发现，性质就变成了“偷偷砍功能”。

第三是积累“更新历史”作为信任资产。把历次发布说明按时间顺序放在官网一个固定页面上，几个月后，它就变成了一份公开的产品进化史：新用户一眼能看出项目是不是在持续维护、更新频率怎么样、每次更新是不是言之有物。这对 vibe 项目尤其重要，因为用户对 AI 生成的项目天然有一层怀疑——“这个东西会不会下个月就不维护了”。一份持续、具体、诚实的更新历史，是打消这种怀疑最便宜的方式。反过来，如果更新历史里全是“修复了若干问题”，怀疑只会加重。第四是把发布说明和用户反馈闭环：每次发布后，主动收集用户对这次更新的反馈，记下来，下次发布时回应——“上次大家提到的某某问题，这次修好了”。这样发布说明就从单向通知，变成了一场持续的对话，而对话，正是小项目留住用户的关键。

写给 AI 协作的特别提醒：别让 AI 直接替你发发布说明

vibe 项目的作者很容易犯一个错误：让 AI 根据提交记录自动生成发布说明，然后不经检查就发出去。AI 生成的版本通常有两个问题：第一，它会把所有改动都列出来，不管用户感不感知，因为它没有“用户感知”这个判断标准；第二，它会用模糊词掩盖自己没搞清楚的地方，比如“优化了相关体验”——这句话在提交记录里找不到对应，纯粹是 AI 为了凑完整而编的过渡句。正确的做法是把 AI 当成初稿工具：让它先按提交记录整理出一份清单，你再按“用户感知”和“风险”两个标准做取舍、改写成人话、删掉模糊词。初稿可以交给 AI，定稿必须经过人。发布说明是产品对外说话的场合，话一出口就收不回来，这个环节省下的十分钟，很可能在客服那里花掉十个小时。

还有一个细节：AI 生成的发布说明常常会“发明”一些没有发生的变化，比如把计划中的功能写成已上线，或者把一次重构写成性能提升。发之前必须逐条核对事实：每一条新功能，是不是真的在这个版本里；每一条修复，是不是真的修好了；每一个数字，是不是真的测过。核对的方法很简单：打开应用，按发布说明里写的路径亲自走一遍。这个动作花不了十分钟，但能拦住绝大多数事实错误。记住，发布说明里的每一个错误，都会在用户那里变成一次信任扣分，而信任是小项目最经不起消耗的东西。