cursornew2026/参考计费/Scripts/RELEASE_GUIDE.md

Release 流程指南

本文档描述了 Vibeviewer 项目的完整 Release 流程，包括构建、签名和上传。

前置要求

1. GitHub CLI

   brew install gh
   gh auth login
   

快速开始

方法 1: 使用自动化脚本（推荐）

# 自动检测版本并执行完整流程
./Scripts/release.sh

# 指定版本号
./Scripts/release.sh 1.1.9

# 跳过构建（使用已有 DMG）
./Scripts/release.sh --skip-build 1.1.9

# 跳过上传（仅本地操作）
./Scripts/release.sh --skip-upload 1.1.9

方法 2: 使用 Makefile

# 构建 DMG
make release

# 然后手动执行后续步骤

方法 3: 手动步骤

1. 更新版本号

   • 编辑 Project.swift，更新 appVersion 常量

2. 构建和创建 DMG

   make release
   # 或
   Scripts/create_dmg.sh --version 1.1.9
   

3. 创建 Git Tag

   git tag -a v1.1.9 -m "Release version 1.1.9"
   git push origin v1.1.9
   

4. 创建 GitHub Release

   gh release create v1.1.9 \
     --title "Version 1.1.9" \
     --notes "Release notes here" \
     Vibeviewer-1.1.9.dmg
   

详细流程说明

1. 版本号管理

版本号在 Project.swift 中统一管理：

• appVersion: 统一版本号配置（如 "1.1.9"）
• MARKETING_VERSION: 显示版本号（从 appVersion 读取）
• CURRENT_PROJECT_VERSION: 构建版本号（从 appVersion 读取）
• CFBundleShortVersionString: Info.plist 中的版本号（从 appVersion 读取）
• CFBundleVersion: Info.plist 中的构建号（从 appVersion 读取）

2. 构建流程

Scripts/create_dmg.sh 脚本会：

1. 清理之前的构建产物
2. 构建 Release 版本应用
3. 验证应用版本信息和代码签名
4. 创建 DMG 安装包

3. GitHub Release

使用 GitHub CLI 创建 Release：

• 自动生成变更日志（基于 Git commits）
• 上传 DMG 文件
• 创建 Release 页面

故障排查

问题 1: GitHub Release 创建失败

可能原因:

• GitHub CLI 未认证
• Tag 已存在
• 网络问题

解决方案:

# 重新认证
gh auth login

# 删除现有 Tag/Release
git tag -d v1.1.9
git push origin :refs/tags/v1.1.9
gh release delete v1.1.9

问题 2: 构建失败

解决方案:

1. 检查 Xcode 是否正确安装
2. 运行 make clear 清理构建缓存
3. 检查 Project.swift 中的版本号配置

最佳实践

1. 版本号: 遵循语义化版本（Semantic Versioning）
2. 变更日志: 在 Release Notes 中清晰描述更新内容
3. 测试: 发布前在本地测试 DMG 安装
4. 文档: 重大更新时更新 README 和文档

相关文件

• Scripts/release.sh - 完整的自动化 Release 脚本
• Scripts/create_dmg.sh - DMG 创建脚本
• Project.swift - 版本号配置
• Makefile - 构建命令

参考链接

• GitHub CLI 文档
• 语义化版本