版本标签管理工具

QXS-BNS 提供了强大的 Git Tag 管理工具，帮助开发者轻松管理项目版本标签和自动化发布流程。

🎯 工具概述

设计目标

独立管理 - 从发布流程中独立出来，避免干扰
自动化 - 与 GitHub Actions 无缝集成
灵活性 - 支持多种标签类型和命名规范
安全性 - 提供验证和确认机制

核心功能

🏷️ 标签创建 - 支持多种标签类型
📋 标签查看 - 列出所有现有标签
❌ 标签删除 - 安全删除不需要的标签
🔍 配置验证 - 验证 GitHub Actions 配置
🚀 自动发布 - 触发自动化发布流程

🚀 快速开始

启动工具

bash

# 启动交互式标签管理工具
pnpm tag-manager

# 或使用简化命令
pnpm run tag-manager

交互式菜单

启动后会显示友好的交互式菜单：

🏷️  QXS-BNS 标签管理工具

请选择操作：
  📋 查看所有标签
  ➕ 创建新标签
  ❌ 删除标签
  🔍 验证 GitHub Actions 配置
  📚 查看帮助
  🚪 退出

请输入选项 (1-6):

命令行模式

bash

# 查看所有标签
pnpm tag-manager --list
pnpm tag-manager -l

# 创建新标签
pnpm tag-manager --create
pnpm tag-manager -c

# 删除标签
pnpm tag-manager --delete
pnpm tag-manager -d

# 验证配置
pnpm tag-manager --validate
pnpm tag-manager -v

# 查看帮助
pnpm tag-manager --help
pnpm tag-manager -h

🏷️ 标签类型详解

包版本标签

用于标记各个包的版本发布：

标签格式	说明	示例	触发的 Actions
`components@x.y.z`	组件库版本	`components@1.0.0`	组件库发布
`utils@x.y.z`	工具库版本	`utils@1.0.0`	工具库发布
`hooks@x.y.z`	Hooks 版本	`hooks@1.0.0`	Hooks 发布
`directives@x.y.z`	指令版本	`directives@1.0.0`	指令发布
`icons@x.y.z`	图标库版本	`icons@1.0.0`	图标库发布

文档版本标签

用于标记文档更新：

标签格式	说明	示例	触发的 Actions
`docs@x.y.z`	文档版本	`docs@1.0.0`	文档部署

通用版本标签

用于标记整个项目的版本：

标签格式	说明	示例	触发的 Actions
`vx.y.z`	项目版本	`v1.0.0`	完整发布流程

📋 功能详解

查看标签

bash

# 查看所有标签
pnpm tag-manager --list

# 输出示例：
# 📋 现有标签列表 (按时间倒序)
#
# 🏷️  components@1.0.2    (2024-01-15 10:30:25)
#     提交: a1b2c3d - feat: 添加新组件
#
# 🏷️  docs@1.0.1         (2024-01-14 16:20:10)
#     提交: e4f5g6h - docs: 更新安装指南
#
# 🏷️  utils@1.0.1        (2024-01-13 14:15:30)
#     提交: i7j8k9l - fix: 修复工具函数bug

创建标签

bash

# 交互式创建
pnpm tag-manager --create

# 创建流程：
# 1. 选择标签类型
# 2. 输入版本号
# 3. 添加描述信息（可选）
# 4. 确认创建
# 5. 自动推送到远程

创建示例：

🏷️  创建新标签

请选择标签类型：
  1. components@x.y.z  (组件库版本)
  2. utils@x.y.z       (工具库版本)
  3. hooks@x.y.z       (Hooks版本)
  4. directives@x.y.z  (指令版本)
  5. icons@x.y.z       (图标库版本)
  6. docs@x.y.z        (文档版本)
  7. vx.y.z            (项目版本)

请输入选项 (1-7): 1

请输入版本号 (如: 1.0.0): 1.0.3

请输入标签描述 (可选): 添加新的移动端组件

✅ 标签 components@1.0.3 创建成功！
🚀 已推送到远程仓库
🔄 GitHub Actions 将自动触发发布流程

删除标签

bash

# 交互式删除
pnpm tag-manager --delete

# 删除流程：
# 1. 显示所有现有标签
# 2. 选择要删除的标签
# 3. 二次确认
# 4. 删除本地和远程标签

删除示例：

❌ 删除标签

现有标签：
  1. components@1.0.2
  2. docs@1.0.1
  3. utils@1.0.1
  4. v1.0.0

请选择要删除的标签 (输入序号，多个用逗号分隔): 2

⚠️  确认删除以下标签？
   - docs@1.0.1

这将同时删除本地和远程标签，此操作不可撤销！

确认删除？ (y/N): y

✅ 标签 docs@1.0.1 删除成功！

📏 版本号规范

语义化版本

严格遵循 Semantic Versioning 规范：

主版本号.次版本号.修订号[-预发布标识]

例如：1.2.3-alpha.1

版本号含义

类型	说明	何时递增	示例
主版本号	不兼容的 API 修改	破坏性变更	`1.0.0` → `2.0.0`
次版本号	向下兼容的功能新增	新功能	`1.0.0` → `1.1.0`
修订号	向下兼容的问题修正	Bug 修复	`1.0.0` → `1.0.1`

预发布版本

bash

1.0.0-alpha.1    # Alpha 版本（内部测试）
1.0.0-beta.1     # Beta 版本（公开测试）
1.0.0-rc.1       # Release Candidate（发布候选）

版本号验证

工具会自动验证版本号格式：

bash

# ✅ 有效版本号
1.0.0
1.2.3
2.0.0-alpha.1
1.0.0-beta.2
1.0.0-rc.1

# ❌ 无效版本号
1.0          # 缺少修订号
v1.0.0       # 不应包含 v 前缀
1.0.0.1      # 过多的版本号段

🚀 GitHub Actions 集成

自动化发布流程

当推送标签到远程仓库时，GitHub Actions 会自动触发：

mermaid

graph LR
    A[推送标签] --> B[触发 GitHub Actions]
    B --> C[构建项目]
    C --> D[生成 Changelog]
    D --> E[创建 GitHub Release]
    E --> F[上传构建产物]

工作流配置

1. Release 工作流 (`.github/workflows/release.yml`)

yaml

name: Release
on:
  push:
    tags:
      - 'v*'           # 项目版本
      - 'components@*' # 组件库版本
      - 'utils@*'      # 工具库版本
      - 'docs@*'       # 文档版本

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate Changelog
        uses: changelogithub/action@v1
      - name: Create Release
        uses: actions/create-release@v1

2. 配置验证

工具会自动验证：

✅ 检查工作流文件存在
✅ 验证标签触发器配置
✅ 确保权限设置正确
✅ 测试工作流响应

标签信息策略

工具采用简化策略，让 GitHub Actions 处理详细内容：

bash

# 工具创建的标签信息
Release components@1.0.0

# GitHub Actions 自动生成详细信息：
# - 完整的 Changelog
# - 提交记录分析
# - 构建产物上传
# - Release Notes

💡 最佳实践

标签管理策略

标签命名规范

bash

# ✅ 推荐的标签命名
components@1.0.0     # 组件库版本
utils@1.2.3          # 工具库版本
docs@2.0.0           # 文档版本
v1.0.0               # 项目整体版本

# ❌ 避免的标签命名
component-1.0.0      # 使用连字符
Components@1.0.0     # 大小写不一致
v1.0                 # 版本号不完整

版本递增策略

变更类型	版本递增	示例
🐛 Bug 修复	修订号 +1	`1.0.0` → `1.0.1`
✨ 新功能	次版本号 +1	`1.0.1` → `1.1.0`
💥 破坏性变更	主版本号 +1	`1.1.0` → `2.0.0`
📚 文档更新	修订号 +1	`1.0.0` → `1.0.1`

标签描述规范

bash

# ✅ 好的标签描述
"添加移动端组件支持"
"修复文件上传组件bug"
"重构工具函数API"

# ❌ 避免的标签描述
"更新"                # 太简单
"修复了一些问题"      # 不具体
"Release v1.0.0"      # 重复信息

团队协作规范

权限管理

bash

# 只有维护者可以：
# - 创建 release 标签 (v*)
# - 删除已发布的标签
# - 修改 GitHub Actions 配置

# 开发者可以：
# - 创建功能分支标签
# - 查看所有标签
# - 提交标签创建请求

发布检查清单

[ ] 代码已合并到主分支
[ ] 所有测试通过
[ ] 文档已更新
[ ] 版本号符合语义化规范
[ ] 标签描述清晰明确
[ ] GitHub Actions 配置正确

自动化配置

配置 GitHub Actions

yaml

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'
      - 'components@*'
      - 'utils@*'
      - 'hooks@*'
      - 'directives@*'
      - 'icons@*'
      - 'docs@*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate Changelog
        run: npx changelogithub
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

配置验证命令

bash

# 验证 GitHub Actions 配置
pnpm tag-manager --validate

# 输出示例：
# ✅ GitHub Actions 配置检查
# ✅ 工作流文件存在: .github/workflows/release.yml
# ✅ 标签触发器配置正确
# ✅ 权限设置正确
# ✅ changelogithub 配置正确

🔧 故障排除

常见问题及解决方案

1. 标签推送失败

问题现象：

bash

❌ 推送标签失败: Permission denied

解决方案：

bash

# 检查 Git 权限
git remote -v

# 检查 SSH 密钥
ssh -T git@github.com

# 重新配置远程仓库
git remote set-url origin git@github.com:username/qxs-bns.git

# 手动推送测试
git push origin v1.0.0

2. 版本号冲突

问题现象：

bash

⚠️  标签 v1.0.0 已存在

解决方案：

bash

# 方案1: 使用工具自动递增
pnpm tag-manager --create
# 选择自动递增版本号

# 方案2: 手动指定新版本
# 输入 1.0.1 或 1.1.0

# 方案3: 删除现有标签后重新创建
pnpm tag-manager --delete
# 选择要删除的标签

3. GitHub Actions 未触发

问题现象：

bash

✅ 标签创建成功，但 GitHub Actions 未运行

解决方案：

bash

# 1. 验证配置
pnpm tag-manager --validate

# 2. 检查标签格式
git tag --list | grep v1.0.0

# 3. 检查工作流文件
cat .github/workflows/release.yml

# 4. 手动触发（如果支持）
# 在 GitHub Actions 页面手动运行工作流

4. 权限问题

问题现象：

bash

❌ GitHub Actions 权限不足

解决方案：

bash

# 检查 GitHub Token 权限
# 需要以下权限：
# - contents: write
# - pull-requests: write
# - actions: write

# 在 GitHub 仓库设置中检查：
# Settings > Actions > General > Workflow permissions

5. 网络连接问题

问题现象：

bash

❌ 网络连接超时

解决方案：

bash

# 工具会自动重试 3 次
# 如果仍然失败，可以手动操作：

# 创建本地标签
git tag -a v1.0.0 -m "Release v1.0.0"

# 稍后推送
git push origin v1.0.0

手动操作指南

Git 标签操作

bash

# 查看所有标签
git tag --sort=-version:refname

# 查看标签详情
git show v1.0.0

# 创建带注释的标签
git tag -a v1.0.0 -m "Release v1.0.0"

# 创建轻量级标签
git tag v1.0.0

# 推送单个标签
git push origin v1.0.0

# 推送所有标签
git push origin --tags

# 删除本地标签
git tag -d v1.0.0

# 删除远程标签
git push origin --delete v1.0.0

GitHub Release 操作

bash

# 使用 GitHub CLI 创建 Release
gh release create v1.0.0 \
  --title "Release v1.0.0" \
  --notes "发布说明" \
  --draft

# 上传文件到 Release
gh release upload v1.0.0 dist/*.tgz

调试技巧

1. 启用详细日志

bash

# 设置环境变量启用调试模式
DEBUG=tag-manager pnpm tag-manager

# 查看详细的操作日志

2. 验证工具配置

bash

# 验证 GitHub Actions 配置
pnpm tag-manager --validate

# 检查输出：
# ✅ 工作流文件存在
# ✅ 标签触发器配置正确
# ✅ 权限设置正确
# ❌ changelogithub 配置缺失

3. 测试标签创建

bash

# 创建测试标签（不推送）
git tag -a test-v1.0.0 -m "Test tag"

# 验证标签创建成功
git tag --list | grep test

# 删除测试标签
git tag -d test-v1.0.0

🛡️ 安全特性

操作确认机制

危险操作确认 - 删除标签前需要二次确认
版本冲突检测 - 自动检测并提示版本冲突
权限验证 - 操作前验证 Git 和 GitHub 权限

数据保护

本地备份 - 操作前自动备份重要数据
回滚支持 - 提供操作失败时的回滚建议
详细日志 - 记录所有操作的详细日志

网络安全

重试机制 - 网络操作支持自动重试
超时保护 - 设置合理的网络超时时间
错误处理 - 完善的错误处理和提示

📚 相关资源

官方文档

Semantic Versioning - 语义化版本规范
GitHub Actions - GitHub Actions 文档
Git Tagging - Git 标签文档

工具链

changelogithub - 自动生成 Changelog
GitHub CLI - GitHub 命令行工具
conventional-commits - 约定式提交规范

🎉 恭喜！ 你已经掌握了 QXS-BNS 标签管理工具的完整使用方法。

通过这个工具，你可以轻松管理项目版本，自动化发布流程，让版本管理变得简单高效！

版本标签管理工具 ​

🎯 工具概述 ​

设计目标 ​

核心功能 ​

🚀 快速开始 ​

启动工具 ​

交互式菜单 ​

命令行模式 ​

🏷️ 标签类型详解 ​

包版本标签 ​

文档版本标签 ​

通用版本标签 ​

📋 功能详解 ​

查看标签 ​

创建标签 ​

删除标签 ​

📏 版本号规范 ​

语义化版本 ​

版本号含义 ​

预发布版本 ​

版本号验证 ​

🚀 GitHub Actions 集成 ​

自动化发布流程 ​

工作流配置 ​

1. Release 工作流 (.github/workflows/release.yml) ​

2. 配置验证 ​

标签信息策略 ​

💡 最佳实践 ​

推荐的发布流程 ​

1. 开发阶段 ​

2. 发布阶段 ​

3. 自动化阶段 ​

标签管理策略 ​

标签命名规范 ​

版本递增策略 ​

标签描述规范 ​

团队协作规范 ​

权限管理 ​

发布检查清单 ​

自动化配置 ​

配置 GitHub Actions ​

配置验证命令 ​

🔧 故障排除 ​

常见问题及解决方案 ​

1. 标签推送失败 ​

2. 版本号冲突 ​

3. GitHub Actions 未触发 ​

4. 权限问题 ​

5. 网络连接问题 ​

手动操作指南 ​

Git 标签操作 ​

GitHub Release 操作 ​

调试技巧 ​

1. 启用详细日志 ​

2. 验证工具配置 ​

3. 测试标签创建 ​

🛡️ 安全特性 ​

操作确认机制 ​

数据保护 ​

网络安全 ​

📚 相关资源 ​

官方文档 ​

工具链 ​

版本标签管理工具

🎯 工具概述

设计目标

核心功能

🚀 快速开始

启动工具

交互式菜单

命令行模式

🏷️ 标签类型详解

包版本标签

文档版本标签

通用版本标签

📋 功能详解

查看标签

创建标签

删除标签

📏 版本号规范

语义化版本

版本号含义

预发布版本

版本号验证

🚀 GitHub Actions 集成

自动化发布流程

工作流配置

1. Release 工作流 (`.github/workflows/release.yml`)

2. 配置验证

标签信息策略

💡 最佳实践

推荐的发布流程

1. 开发阶段

2. 发布阶段

3. 自动化阶段

标签管理策略

标签命名规范

版本递增策略

标签描述规范

团队协作规范

权限管理

发布检查清单

自动化配置

配置 GitHub Actions

配置验证命令

🔧 故障排除

常见问题及解决方案

1. 标签推送失败

2. 版本号冲突

3. GitHub Actions 未触发

4. 权限问题

5. 网络连接问题

手动操作指南

Git 标签操作

GitHub Release 操作

调试技巧

1. 启用详细日志

2. 验证工具配置

3. 测试标签创建

🛡️ 安全特性

操作确认机制

数据保护

网络安全

📚 相关资源

官方文档

工具链