PT-Plugin-Plus 项目版本号生成机制优化探讨

在开源浏览器插件 PT-Plugin-Plus 的开发过程中，版本号的生成机制一直是一个值得关注的技术细节。本文将从技术角度深入分析现有版本号生成方案的问题，并探讨几种可能的优化方向。

现有版本号机制分析

当前项目使用 git rev-list --all --count % 65535 来计算版本号的最后一部分数字。这种方法存在几个明显问题：

1. 计算的是所有分支的提交总数，导致同一提交在不同分支环境下可能生成不同的版本号
2. 当开发者本地存在多个分支时，版本号计算结果会出现不一致
3. 对于 Pull Request 构建的版本，其版本号可能高于主分支版本，容易误导用户

技术方案对比

方案一：使用 git describe --tag

git describe --tag 可以生成类似 v1.6.1.2657-7-g6f07eb1a 的版本描述，其中：

• 2657 表示距离上一个标签的提交数量
• 7 表示当前提交与描述提交之间的差异数
• g6f07eb1a 是当前提交的短哈希值

优点：

• 不受其他分支影响
• 包含更丰富的版本信息

缺点：

• 生成的字符串不符合 WebExtensions 的版本格式规范
• 需要额外处理才能用于 manifest.json

方案二：限制 git rev-list 范围

改用 git rev-list HEAD --count 仅计算当前分支的提交数量。

优点：

• 实现简单
• 保持现有版本号格式
• 不受其他分支干扰

缺点：

• 仍无法解决 PR 版本号高于主分支的问题

方案三：差异化构建策略

根据构建场景动态调整版本号生成策略：

• 对于 PR 构建，固定版本号为 1.6.1.1
• 对于主分支构建，使用完整提交计数
• 通过 GitHub Actions 的 github.event_name 判断构建类型

优点：

• 有效防止 PR 版本号过高
• 保持主分支版本号的连续性

缺点：

• 增加了构建配置的复杂性

技术实现建议

综合考量后，建议采用组合方案：

1. 主分支构建：

   • 使用 git rev-list HEAD --count 获取精确提交数
   • 保持现有版本号格式

2. PR/MR 构建：

   • 设置固定版本号 1.6.1.1
   • 通过 CI 环境变量识别构建类型

3. 本地开发构建：

   • 保留现有逻辑或添加明确标识
   • 在构建日志中显示完整 git 描述

版本号规范的重要性

浏览器插件对版本号格式有严格要求：

• 必须符合 数字.数字.数字 或 数字.数字.数字.数字 格式
• 每个数字部分不得超过 65535
• 不允许包含字母或其他特殊字符

这一规范限制了版本号的表达方式，也是方案选择时的重要考量因素。

总结

版本号作为软件的重要标识，需要在准确性、一致性和用户体验之间找到平衡。对于 PT-Plugin-Plus 这样的开源项目，采用基于构建场景的差异化版本号生成策略，既能保证主分支版本的连续性，又能避免 PR 版本造成的混淆，是目前较为理想的解决方案。