学习 Vue2 的发布说明生成器：自动化生成优雅的 Release Notes

转载于 2025-06-12 14:32:05 发布 · 128 阅读

0 ·

CC 4.0 BY-SA版权

原文链接：https://juejin.cn/post/7514518228078493746

文章标签：

#学习 #自动化 #运维

前言：Release Notes 的重要性

在软件发布流程中，Release Notes（发布说明）是连接开发团队和用户的重要桥梁。Vue2 通过一个精巧的脚本自动生成发布说明，今天我们就来解析这个神秘的工具！

1. 获取版本号 - 灵活的数据来源

const version = process.argv[2] || process.env.VERSION

作用：获取当前要发布的版本号
参数来源：
- process.argv[2]：命令行参数（如 node script.js 2.7.0）
- process.env.VERSION：环境变量（如 VERSION=2.7.0 node script.js）
设计目的：提供两种灵活的版本传递方式，适应不同使用场景

2. 引入核心工具 - 自动化生成引擎

const cc = require('conventional-changelog')

作用：引入 conventional-changelog 库
工具功能：解析 Git 提交历史，根据约定式提交规范自动生成变更日志
为什么选择它：这是业界标准的自动生成 changelog 工具，被 Angular、Vue 等主流项目采用

3. 确定输出文件 - 动态文件名

const file = `./RELEASE_NOTE${version ? `_${version}` : ''}.md`

作用：确定生成的发布说明文件路径
动态命名：
- 有版本号：RELEASE_NOTE_2.7.0.md
- 无版本号：RELEASE_NOTE.md
目的：按版本归档发布说明，便于历史查阅

4. 创建文件写入流 - 准备输出

const fileStream = require('fs').createWriteStream(file)

作用：创建文件写入流
技术点：使用 Node.js 的 fs 模块
目的：高效地将生成的发布说明写入文件

5. 核心配置 - 定制生成规则

cc({
  preset: 'angular',
  pkg: {
    transform (pkg) {
      pkg.version = `v${version}`
      return pkg
    }
  }
})

配置项	值	作用
`preset`	`'angular'`	使用 Angular 提交规范
`pkg.transform`	自定义函数	动态设置版本号

transform 函数详解：

transform (pkg) {
  pkg.version = `v${version}` // 添加 'v' 前缀
  return pkg
}

- 目的：确保生成的发布说明中包含正确格式的版本号（如 v2.7.0）
- 为什么重要：保持与 Git 标签一致的版本格式

6. 管道连接与完成通知 - 优雅的异步处理

.pipe(fileStream).on('close', () => {
  console.log(`Generated release note at ${file}`)
})

作用：
1. 将生成的 changelog 内容通过管道传输到文件流
2. 在写入完成后显示成功消息
技术亮点：
- 使用流式处理（pipe）提高内存效率
- 事件监听（on('close')）确保操作完成
用户反馈：清晰告知生成文件的位置

工作流程解析

1. 输入阶段

获取版本号（命令行参数或环境变量）

2. 处理阶段

解析 Git 历史提交（根据 Angular 规范）
过滤并分类提交信息（feat, fix, chore 等）
按版本分组变更内容

3. 输出阶段

生成 Markdown 格式的发布说明
写入版本命名的文件
输出成功消息

为什么需要这样的设计？

自动化代替手工：避免人工编写 Release Notes 的疏漏和耗时
标准化格式：确保所有版本发布说明风格统一
与提交规范结合：强制执行 Conventional Commits 规范
可追溯性：按版本保存发布说明，便于历史查阅
集成发布流程：作为发布脚本的关键一环

实际效果展示

生成的发布说明示例：

# v2.7.0 (2023-01-01)

### Features
* 新增 Composition API 兼容层
* 改进 TypeScript 类型定义

### Fixes
* 修复 SSR 内存泄漏问题
* 解决 v-model 与自定义组件兼容性问题

### Performance
* 优化虚拟 DOM 算法
* 减少运行时包大小 5%

最佳实践建议

提交信息规范化：团队遵循 Conventional Commits 规范

feat(compiler): add new syntax
fix(runtime): handle edge case

版本管理：使用语义化版本（SemVer）
- 主版本.次版本.修订号（Major.Minor.Patch）

总结

Vue2 的发布说明生成器展示了如何优雅地解决一个常见问题：将技术细节转化为用户友好的发布说明。这个不到 20 行的小工具包含了几个关键设计思想：

约定优于配置：采用标准化的 Conventional Commits
自动化优先：减少人工操作成本
灵活输入：支持多种版本号传递方式
可扩展架构：通过配置适应不同需求