GitHub Actions CI/CD 集成与多平台自动化构建

概述

当应用需要在 Windows、macOS、Linux 三端交付时，靠本地一台机器手动打包很快就会成为瓶颈：环境不一致、签名证书难管理、耗时且容易漏步骤。GitHub Actions 把“拉代码 → 装依赖 → 构建 → 打包 → 发布”固化为可重复的工作流，让每次发布都走同一条受控路径。本节先建立 CI/CD 的整体认知，再给出一个可直接参照的 release 工作流骨架，并顺势引出自动更新所需的发布链路。

学习目标

• 理解 CI/CD 对桌面端多平台交付的价值
• 掌握 GitHub Actions 的四个核心概念：Workflow、Job、Step、Action
• 能读懂并改写一份 release.yml 模板
• 区分不同触发方式：push、pull_request、workflow_dispatch、schedule
• 理清构建流程的多个阶段与 Draft 草稿机制
• 理解 electron-updater 自动更新对发布链路的前置要求

一、为什么桌面端需要 CI/CD

本地打包的最大问题是“环境即真相”：你本地能跑，不代表干净机器能跑；你记得每一步，不代表队友记得。CI/CD 把构建过程写成声明式配置，每次都在全新 runner 上执行，天然消除了“在我机器上能跑”的差异。

对 Electron 这类需要签名、公证、跨平台产物的项目，CI 还有额外价值：证书和密钥通过 Secrets 注入，不必落在代码仓库；macOS 签名与公证所需的 Apple 凭证只能在云端 runner 里安全使用；三端可以并行构建，缩短发布周期。把重复劳动交给机器，是人做桌面交付的基本素养。

二、GitHub Actions 的四个核心概念

理解工作流，先分清四层：

• Workflow：一个 YAML 文件定义的整体流程，放在 .github/workflows/
• Job：Workflow 里的一个任务，默认并行，可用 needs 串成先后
• Step：Job 里按顺序执行的具体步骤
• Action：可复用的单元（如 actions/checkout、actions/setup-node）

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

把 Job 想成“在哪台机器上做什么”，把 Step 想成“这件事分几步”，Action 则是“每一步用哪个现成工具”。

三、一份 release 工作流模板

最朴素的发布工作流由一个准备 Job 和多个平台构建 Job 组成：准备阶段创建 Draft Release，各平台 Job 依赖它并上传产物。

name: Release
on:
  push:
    branches: [main]
  workflow_dispatch:
jobs:
  prepare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: softprops/action-gh-release@v1
        with:
          draft: true
  build-windows:
    needs: prepare
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build:win
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}

模板的价值不在照抄，而在建立“先草稿、后并行构建、再统一发布”的心智模型。

四、触发方式的取舍

on 字段决定工作流什么时候跑：

• push：推送到指定分支自动触发，适合正式发布
• pull_request：开 PR 时触发，适合在合并前验证构建
• workflow_dispatch：在 Actions 面板手动触发，适合调试和选择性发布
• schedule：按 cron 定时触发，适合周期性构建

实际项目常同时保留 push 与 workflow_dispatch：日常提交自动跑，紧急修复或测试时手动指定分支跑。切忌把所有触发都打开导致构建泛滥，也别只靠手动而忘了自动化初衷。

五、构建流程的阶段拆解

一个完整的发布 Job 通常包含这些阶段：准备运行环境 → 拉取代码 → 安装依赖 → 编译前端资源 → 调用 electron-builder 打包 → 上传产物到 Release。每个阶段失败都会中断后续，所以日志要逐段查看。

依赖安装推荐用 npm ci 而非 npm install，因为前者严格按 package-lock.json 还原，更适合流水线。打包阶段则通过环境变量注入 GH_TOKEN、签名证书、Apple 凭证等敏感信息，保证代码仓库本身不含密钥。

六、Draft 草稿机制

softprops/action-gh-release 配合 draft: true 会先创建一个对用户不可见的草稿 Release。各平台构建完成后把安装包上传到这个草稿，等所有平台就绪，你再手动编辑并发布。

草稿机制的好处是“先聚齐再发布”：避免 Windows 已发布、macOS 还没好的尴尬；也给人工审核留了窗口。发布时取消 draft、勾选 latest，Release 才对用户可见并触发自动更新检测。

七、自动更新对发布链路的要求

自动更新（electron-updater）依赖构建产物旁边的元数据文件（如 latest.yml）。要让客户端检测得到更新，Release 必须是已发布状态，且 publish 配置正确指向 GitHub provider。草稿状态下的产物不会被当作有效更新源。

换句话说，CI/CD 不只是“打出包”，还要保证包和元数据一起稳定落地到 Release。下一节我们会展开 electron-updater 的接入细节，这里先记住：未完成发布的 Release，等于没有更新源。

八、把多平台交付沉淀为配置

CI/CD 的终点不是“这次打出来了”，而是“以后每次都这样打”。把操作系统矩阵、Node 版本、签名注入、发布策略全部写进 release.yml，团队任何人都只需推代码或点一下手动触发，就能得到三端一致的交付物。

这节建立了 GitHub Actions 的主干认知。下一节我们进入实操：本地要做什么准备、Token 怎么申请、工作流怎么改、草稿怎么发布。

常见问题

延伸阅读

• 上一篇：Electron 应用上架 Mac App Store 打包演示与常见问题
• 下一篇：GitHub Actions 实操配置、前置准备与构建测试
• 相关：GitHub Actions 文档、softprops/action-gh-release、electron-builder 发布