Dart Simple Live版本管理：语义化版本控制实践

痛点：多平台应用版本管理混乱

你是否遇到过这样的困扰？一个项目包含多个子应用，每个应用的版本号各自为政，发布时版本号混乱，用户无法清晰了解版本间的兼容性和功能变化。Dart Simple Live作为一个多平台直播聚合应用，面临着Android、iOS、Windows、macOS、Linux、Android TV等多个平台的版本管理挑战。

通过本文，你将掌握：

• 语义化版本控制（SemVer）的核心原则
• 多项目协同开发的版本管理策略
• Flutter项目的版本号最佳实践
• 自动化版本发布流程设计
• 版本变更记录规范

当前版本管理现状分析

Dart Simple Live项目采用模块化架构，包含四个主要子项目：

项目名称	当前版本	版本格式	发布状态
simple_live_app	1.9.2+10902	主版本+构建号	未发布
simple_live_core	1.0.3	标准语义化	未发布
simple_live_console	1.0.0	标准语义化	未发布
simple_live_tv_app	1.4.1+10401	主版本+构建号	未发布

版本号解析示例

// pubspec.yaml中的版本定义
version: 1.9.2+10902

// 语义化版本结构
MAJOR.MINOR.PATCH+BUILD

其中：

• MAJOR（主版本）：不兼容的API修改
• MINOR（次版本）：向下兼容的功能性新增
• PATCH（修订版本）：向下兼容的问题修正
• BUILD（构建号）：编译标识，通常用于CI/CD

语义化版本控制（SemVer）实践指南

核心原则

graph TD
    A[代码变更] --> B{变更类型}
    B -->|不兼容API修改| C[MAJOR版本递增]
    B -->|向下兼容功能新增| D[MINOR版本递增]
    B -->|问题修复| E[PATCH版本递增]
    C --> F[版本号: X+1.0.0]
    D --> G[版本号: X.Y+1.0]
    E --> H[版本号: X.Y.Z+1]

版本递增规则表

变更类型	版本递增	示例	说明
重大功能更新	MAJOR+1	1.9.2 → 2.0.0	不兼容性变更
新功能添加	MINOR+1	1.9.2 → 1.10.0	向后兼容
Bug修复	PATCH+1	1.9.2 → 1.9.3	问题修正
预发布版本	追加标识	1.9.2-alpha.1	测试版本
构建元数据	+BUILD	1.9.2+10902	编译信息

多项目协同版本管理策略

依赖关系管理

graph BT
    TV[simple_live_tv_app 1.4.1] --> Core[simple_live_core 1.0.3]
    App[simple_live_app 1.9.2] --> Core
    Console[simple_live_console 1.0.0] --> Core
    
    style Core fill:#e1f5fe

版本同步策略

1. 核心库先行：simple_live_core版本更新后，依赖项目同步更新
2. API稳定性保证：核心库MAJOR版本变更时，需要评估所有依赖项目
3. 依赖版本约束：使用caret语法确保兼容性

# 正确的依赖声明
dependencies:
  simple_live_core: ^1.0.3  # 兼容1.0.3及以上，但低于2.0.0

Flutter项目版本管理最佳实践

版本号格式规范

// 推荐格式：语义化版本 + 构建号
version: 2.1.0+21001

// 构建号生成规则：
// 前两位：主版本 * 1000 + 次版本 * 100
// 后三位：修订版本 * 10 + 构建序列

自动化版本管理脚本

#!/bin/bash
# version_bump.sh - 自动化版本管理

# 获取当前版本
CURRENT_VERSION=$(grep 'version:' pubspec.yaml | awk '{print $2}')
echo "当前版本: $CURRENT_VERSION"

# 版本号递增逻辑
bump_version() {
    local version=$1
    local type=$2
    
    IFS='.' read -r major minor patch <<< "${version%%+*}"
    local build=${version#*+}
    
    case $type in
        major) major=$((major + 1)); minor=0; patch=0 ;;
        minor) minor=$((minor + 1)); patch=0 ;;
        patch) patch=$((patch + 1)) ;;
    esac
    
    # 生成新的构建号
    local new_build=$((major * 1000 + minor * 100 + patch * 10 + 1))
    echo "$major.$minor.$patch+$new_build"
}

# 使用示例
NEW_VERSION=$(bump_version "$CURRENT_VERSION" "minor")
echo "新版本: $NEW_VERSION"

版本变更记录（CHANGELOG）规范

CHANGELOG.md模板

# 变更日志

## [2.0.0] - 2024-01-15
### 🚀 新功能
- 新增抖音直播支持
- 添加画中画播放模式

### ⚠️ 重大变更
- 重构核心API，不向下兼容
- 移除已弃用的方法

### 🐛 Bug修复
- 修复虎牙直播弹幕丢失问题
- 解决内存泄漏问题

## [1.9.2] - 2024-01-10
### 🐛 Bug修复
- 修复Android TV遥控器导航问题
- 优化播放器稳定性

变更类型标识规范

标识	含义	说明
🚀	新功能	新增的功能特性
⚠️	重大变更	不兼容的API修改
🐛	Bug修复	问题修正
📚	文档	文档更新
♻️	重构	代码重构优化
⚡	性能	性能改进

自动化发布流程设计

CI/CD版本管理流水线

sequenceDiagram
    participant Dev as 开发者
    participant CI as CI服务器
    participant Git as Git仓库
    participant Pub as Pub发布

    Dev->>Git: 提交代码(含版本变更)
    Git->>CI: 触发构建
    CI->>CI: 运行测试
    CI->>CI: 版本号自动递增
    CI->>Git: 创建发布标签
    CI->>Pub: 发布到Pub.dev(可选)
    CI->>CI: 生成CHANGELOG

GitHub Actions版本发布配置

name: Version Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Dart
        uses: dart-lang/setup-dart@v1
      
      - name: Get version from tag
        id: get_version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Update pubspec version
        run: |
          sed -i "s/version: .*/version: ${{ steps.get_version.outputs.VERSION }}/" pubspec.yaml
      
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          tag_name: ${{ github.ref }}
          generate_release_notes: true

实战：版本管理问题解决方案

问题1：多项目版本同步

场景：core库更新后，所有依赖项目需要同步版本

解决方案：

# 使用脚本批量更新依赖版本
./scripts/update_dependencies.sh 1.2.0

问题2：预发布版本管理

场景：需要发布测试版本供内部测试

解决方案：

# 使用预发布标识
version: 2.0.0-beta.1+20001

问题3：构建号冲突

场景：多人协作时构建号可能冲突

解决方案：

# 使用时间戳作为构建号
BUILD_NUMBER=$(date +%Y%m%d%H%M)
version: 1.9.2+$BUILD_NUMBER

版本管理工具推荐

1. version - Dart版本管理工具

dev_dependencies:
  version: ^2.0.0

2. melos - Dart monorepo管理

dev_dependencies:
  melos: ^2.0.0

3. conventional_commit - 规范提交信息

dev_dependencies:
  conventional_commit: ^1.0.0

总结与最佳实践

通过实施语义化版本控制，Dart Simple Live项目实现了：

1. 版本清晰可读：用户和开发者都能理解版本含义
2. 依赖管理规范：确保多项目协同开发的稳定性
3. 发布流程自动化：减少人为错误，提高效率
4. 变更记录完整：便于追踪和审计版本历史

关键实践要点

• ✅ 严格遵守SemVer规范
• ✅ 核心库版本先行策略
• ✅ 自动化版本递增和发布
• ✅ 完整的变更记录维护
• ✅ 预发布版本管理机制

通过这套版本管理体系，Dart Simple Live项目能够更加规范地进行版本发布和管理，为用户提供更稳定可靠的产品体验。

---

下一步行动：立即检查你的项目版本管理实践，开始实施语义化版本控制，让你的项目版本管理更加专业和高效！