meijiaka-zy/docs/github-actions-release.md

GitHub Actions 发版方案（免费双平台构建）

利用 GitHub Actions 免费的 macOS + Windows runner，实现零成本的双平台自动构建。

---

一、方案优势

对比项	GitLab CI（原有）	GitHub Actions（新方案）
macOS runner	需要自维护 Mac 物理机	✅ GitHub 免费提供（macos-latest）
Windows runner	需要自维护 Windows 物理机	✅ GitHub 免费提供（windows-latest）
并发构建	依赖 runner 在线状态	✅ 随时触发，并行执行
产物保留	30 天（可配置）	90 天（默认）
成本	维护 runner 硬件/电费	✅ 公有仓库完全免费

---

二、前置准备

2.1 确认代码已推送到 GitHub

GitHub Actions 只能构建 GitHub 仓库中的代码。如果你的代码只在 GitLab，需要：

# 在 GitHub 创建空仓库，然后添加远程地址
git remote add github https://github.com/你的用户名/美家卡智影.git
git push github master
git push github --tags

2.2 配置 GitHub Secrets（只需做一次）

进入 GitHub 仓库 → Settings → Secrets and variables → Actions → New repository secret

Secret 名称	值	说明
TAURI_SIGNING_PRIVATE_KEY	dW50cnVzdGVk...（私钥完整内容）	Tauri updater 签名私钥
TAURI_SIGNING_PRIVATE_KEY_PASSWORD	（留空，不创建）	若私钥有密码则填，当前无密码

私钥从 tauri-app/.tauri-signing-key 文件中复制全部内容。

---

三、触发构建的两种方式

方式一：推送 Git tag（推荐，用于正式发版）

# 1. 更新版本号
python scripts/bump-version.py 1.5.16

# 2. 提交并推送
git add -A
git commit -m "release: v1.5.16"
git push github master

# 3. 推送 tag 自动触发 GitHub Actions
git tag v1.5.16
git push github v1.5.16

推送 tag 后，GitHub Actions 自动开始构建：

• build-macos：在 macos-latest runner 上构建 Universal .dmg
• build-windows：在 windows-latest runner 上构建 .exe + .msi

方式二：手动触发（用于测试或紧急打包）

进入 GitHub 仓库 → Actions → Release → Run workflow

• 输入版本号（如 1.5.16）
• 点击 Run workflow

---

四、获取构建产物

构建完成后（约 10-20 分钟）：

1. 进入 GitHub 仓库 → Actions
2. 点击最新的 workflow run
3. 页面底部 Artifacts 区域下载：
   • macos-universal → 包含 .dmg 和 .app
   • windows-x64 → 包含 .exe 和 .msi

---

五、发布更新包（手动执行）

下载产物后，解压到本地目录，执行发版脚本：

# 1. 创建产物目录结构
mkdir -p bundle/macos
mkdir -p bundle/dmg
mkdir -p bundle/nsis
mkdir -p bundle/msi

# 2. 将下载的 artifact 解压并放入对应目录
# macos-universal.zip → bundle/dmg/xxx.dmg, bundle/macos/xxx.app
# windows-x64.zip → bundle/nsis/xxx.exe, bundle/msi/xxx.msi

# 3. 执行发版脚本
cd python-api
python scripts/publish_release.py \
  --version 1.5.16 \
  --notes "修复视频导出崩溃\n优化启动速度" \
  --bundle-dir ../bundle

---

六、注意事项

6.1 macOS 签名

GitHub Actions 的 macos-latest runner 没有 Apple Developer 证书，构建出的 .app/.dmg 与本地构建一样，是未签名的。用户在首次打开时仍需手动允许。

后续升级：购买 Apple Developer Program 后，在 workflow 中添加：

env:
  APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
  APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
  APPLE_ID: ${{ secrets.APPLE_ID }}
  APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
  APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}

6.2 Windows 签名

同理，未配置 WINDOWS_CERTIFICATE 时，.exe 会有 SmartScreen 提示。购买证书后配置 GitHub Secrets 即可自动签名。

6.3 产物自动上传到 Release（可选进阶）

如需让 GitHub 自动创建 Release 页面并上传产物，可在 workflow 末尾添加：

      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: |
            tauri-app/src-tauri/target/**/bundle/dmg/*.dmg
            tauri-app/src-tauri/target/**/bundle/nsis/*.exe
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

---

七、文件清单

文件	作用
.github/workflows/release.yml	GitHub Actions 工作流定义
tauri-app/.tauri-signing-key	私钥源文件（本地保存）
tauri-app/src-tauri/tauri.key.pub	公钥（已提交 Git）