# 发布流程指南

## 概述

本项目采用专业的发布流程，避免 GitHub Actions 存储配额超限问题。

## 发布策略

### 1. macOS 构建优化

✅ **仅在创建 tag 时构建 macOS** - 避免每次 push 都触发 macOS 构建
✅ **使用 GitHub Releases** - 不占 artifact 配额
✅ **完全移除 artifacts** - 彻底避免配额问题

## 开发测试流程

### 本地构建（推荐）

对于开发测试，建议在本地构建：

```bash
# Windows
npm run web:build
npm run build-win-installer

# macOS
npm run web:build
npm run build-mac-installer
```

### 云端测试（临时）

如果需要在云端测试，可以：
- 使用云 Mac 服务（如 MacStadium、GitHub Codespaces）
- 或者在本地测试完成后再发布

**注意**：已完全移除 artifacts 上传，不再使用临时下载方式。

## 正式发布流程

### 创建新版本发布

```bash
# 1. 确保代码已合并到 main 分支
git checkout main
git pull origin main

# 2. 更新版本号（package.json）
# 修改 "version": "0.0.100" → "0.0.101"

# 3. 提交版本变更
git add package.json
git commit -m "chore: bump version to 0.0.101"
git push origin main

# 4. 创建并推送标签
git tag -a v0.0.101 -m "Release version 0.0.101"
git push origin v0.0.101
```

### 自动化构建流程

创建 tag 后，GitHub Actions 会自动：

1. ✅ 构建 Windows 安装包（.exe）
2. ✅ 构建 macOS 安装包（.dmg）
3. ✅ 自动发布到 GitHub Releases
4. ✅ 生成 Release Notes（基于提交历史）

### 用户下载

用户访问 Releases 页面即可下载：
```
https://github.com/your-username/capcut-mate-electron/releases
```

## 工作流说明

### Build Mac 工作流

**触发条件**：
- `workflow_dispatch` - 手动触发（开发测试）
- `push tags: 'v*'` - 创建版本标签时触发

**行为**：
- 开发测试：上传到 artifacts（24小时过期）
- 正式发布：上传到 GitHub Releases

### Build 工作流

**触发条件**：
- `push branches: [main]` - 推送到 main 分支
- `push tags: 'v*'` - 创建版本标签
- `pull_request` - PR 合并

**行为**：
- 普通 push：上传到 artifacts（1天过期）
- 创建 tag：发布到 GitHub Releases

## 最佳实践

### 1. 版本号管理

遵循 [语义化版本](https://semver.org/lang/zh-CN/)：

- `v0.1.0` - 初始版本
- `v0.1.1` - Bug 修复（向后兼容）
- `v0.2.0` - 新功能（向后兼容）
- `v1.0.0` - 主要更新（可能不兼容）

### 2. 发布前检查清单

- [ ] 代码已通过测试
- [ ] 更新了版本号（package.json）
- [ ] 更新了 CHANGELOG（如果有）
- [ ] 提交信息清晰明了
- [ ] README 文档已更新

### 3. 发布后验证

- [ ] 检查 GitHub Releases 页面
- [ ] 验证下载链接可用
- [ ] 测试安装包可正常安装
- [ ] 验证核心功能正常

## 故障排查

### tag 未触发构建

**原因**：tag 格式不符合要求

**解决**：确保 tag 以 `v` 开头，如 `v1.0.0`

### macOS 构建失败

**检查**：
1. `build/entitlements.mac.plist` 文件是否存在
2. `CSC_IDENTITY_AUTO_DISCOVERY: false` 是否设置

### Release 未生成

**检查**：
1. tag 是否成功推送到远程
2. `GITHUB_TOKEN` 是否有权限
3. Actions 日志是否有错误

## 相关资源

- [GitHub Actions 文档](https://docs.github.com/cn/actions)
- [GitHub Releases 文档](https://docs.github.com/cn/repositories/releasing-projects-on-github/about-releases)
- [Semantic Versioning](https://semver.org/lang/zh-CN/)
