把发布流程做成一张可执行的清单

我做过几个长期维护的小项目，发版频率不算高，但每次都要重新回忆：版本号改了吗？静态资源更新了吗？ 备份做了吗？回滚路径是什么？后来我把这些步骤整理成一张清单，发版时逐项确认，问题明显少了。

一、发布前先确认版本

版本号最好只在一个地方定义，构建时再写进产物和版本接口。不要在多个文件里手改，否则很容易出现页面显示 1.2.0、 安装包却是 1.2.1 的情况。

{
  "version": "1.2.1",
  "build": "20261105.1",
  "notes": "修复列表分页与缓存问题"
}

构建号可以带上日期，方便在日志和发布记录里对应。版本说明尽量写给用户看，而不是只写“修复若干问题”。

二、构建后做三项校验

• 检查产物里是否包含正确的版本号和构建时间。
• 计算文件大小和 SHA-256，部署后再次核对。
• 在干净环境里启动一次，确认没有遗漏的运行依赖。

sha256sum dist/app.tar.gz
du -h dist/app.tar.gz
curl -fsS https://example.com/api/version

文件大小和摘要看起来麻烦，但它们是判断“线上到底是不是这份包”的最快方式。尤其是手动上传时， 一次网络中断就可能留下一个不完整的文件。

三、部署时保留可回滚路径

我习惯把每次发布放到独立目录，再用一个稳定的软链接指向当前版本。切换时只改软链接，回滚也只是把链接指回去。

/srv/app/releases/20261105-1/
/srv/app/releases/20261105-2/
/srv/app/current -> releases/20261105-2

数据库迁移要单独考虑。能向后兼容的字段先加，不要在同一版里既删旧字段又要求旧版本还能读。 如果必须做破坏性变更，先确认回滚时数据是否还能恢复。

四、发布后的冒烟检查

• 首页、登录页和核心接口各访问一次。
• 检查静态资源是否 200，缓存头是否符合预期。
• 查看服务日志，确认没有启动错误和异常堆栈。
• 用真实设备或干净浏览器走一遍关键路径。

冒烟检查不需要很复杂，但要固定下来。比如每次都检查版本接口、首页标题和一个核心写操作， 就能覆盖大部分低级错误。

五、把结果记录下来

发布完成后，在项目里留一条记录：版本号、时间、变更摘要、产物摘要、回滚目录。 下次出问题时，这些信息比聊天记录可靠得多。

清单的价值不在于形式，而在于把“我记得要做”变成“流程要求我做”。

如果项目只有一个人维护，更值得这样做。没有人帮你兜底时，流程就是最简单的保险。