Electron 自动化发布指南：GitHub Actions 跨平台打包全纪录

前言

绝大多数 Electron 开发者最初都是在 Windows 环境下起步的。得益于 Windows 系统的普及度，在本地顺手打包出一个 .exe 安装包往往是水到渠成的事。然而，当产品走向成熟，全平台支持（同时支持 Windows、macOS 和 Linux）便成了绕不开的硬需求。Electron 的跨平台打包高度依赖宿主系统的编译环境------这意味着，你无法直接在 Windows 上打包出原生的 macOS .dmg 或 Linux .AppImage 安装包。

面对跨平台打包的鸿沟，开发者们通常会联想到两条传统路径：

虚拟机方案：在宿主机中配置 macOS 和 Linux 虚拟机，手动搭建环境进行编译。不仅镜像配置繁琐，对电脑的硬件配置（尤其是内存和 CPU）也是一场灾难。
物理机方案：直接购置 Mac 电脑甚至组装 Linux 主机，实现"多机物理流"。虽说可行，但硬件采购和多端维护的成本居高不下，极不环保也不优雅。

这两条路线虽然可行，但无一例外都面临着成本高、效率低、环境难同步的痛点。

那么，有没有一种零硬件投入、开箱即用且能一键梭哈全平台的优雅解法？答案就是借助 GitHub Actions 构建云端 CI/CD 流水线。具体该如何操作？且听下文分解。

GitHub Actions 凭什么能一键打通全平台

很多人第一次看到 GitHub Actions 同时产出 Windows、macOS 和 Linux 安装包时，会觉得有些不可思议：为什么我一台 Windows 电脑，却能凭空变出 Mac 的 .dmg 呢？

其实，这背后核心归功于两个关键机制：云端动态宿主机 和electron-builder全平台适配能力

1. 云端动态宿主机

很多初次接触 CI/CD 的开发者并不知道，GitHub 默默提供了一个极其强大却常常被忽视的宝藏功能------云端动态宿主机（GitHub-hosted Runners） 。

简单来说，当你向 GitHub 提交代码或触发 Action 时，GitHub 并不只是在远默默"存"你的代码，它还会根据你的指令，在云端按需实时为你分配纯净的虚拟计算机。

这意味着：

当你指定同时构建多个系统时，GitHub 会瞬间在云端为你唤醒一台 macOS 虚拟机 、一台 Windows 虚拟机 以及一台 Linux 虚拟机。
各回各家，各找各妈 ：macOS 虚拟机自带了苹果编译环境，专门用来帮你压制 .dmg 和 .zip；Windows 虚拟机负责生成 .exe；Linux 虚拟机则产出 .AppImage。

这就像是 GitHub 免费借给了你几台配置拉满、随时待命的顶配电脑。你不需要在本地买 Mac、也不用费劲配虚拟机，只需要在配置文件里写下一行矩阵指令，这些云端宿主机就会像流水线上的工人一样，自动把各个平台的安装包同时生产出来，最后整整齐齐地塞进你的 Releases 页面。这种"借力打力"的降维打击，正是自动化打包的核心奥秘。

2. `electron-builder` 的全平台适配能力

光有操作系统还不够，为什么代码能在对应的系统上顺利变成安装包？这就不得不提 electron-builder 的强大之处：

electron-builder 内部针对各个平台的打包规范进行了高度封装。
在 Windows 上，它会调用 NSIS 工具链生成安装向导；在 macOS 上，它能规范地处理苹果签名结构、生成 DMG 镜像；在 Linux 上，它能打包出标准的 AppImage。
每一台云端虚拟机在拉取代码后，都会经历"安装依赖 $→\rightarrow$ → 编译前端/主进程 $→\rightarrow$ → 调用对应系统的 Builder 产出安装包"的标准流水线。

实战落地

原理懂了，接下来就是真刀真枪的落地环节。要让云端宿主机自动完成全平台打包并发布，核心依赖两个配置文件：一个是定义流水线逻辑的 GitHub Actions 工作流（release.yml） ，另一个是告诉 electron-builder 如何打包的 package.json。以下是保姆级的核心配置拆解：

1. 编写工作流：`release.yml`

在项目的 .github/workflows/ 目录下创建 release.yml 文件。这段配置通过矩阵策略（Matrix Strategy） ，让云端同时启动 Windows、macOS 和 Linux 三台机器并行干活：

关键点解析：

on.push.tags：每次打tag时精准触发，避免每次普通 commit 都去漫长打包。
matrix.os：矩阵作业,一行代码拉起三大主流操作系统的云端虚拟机。
GITHUB_TOKEN ：当 electron-builder 在云端虚拟机里打包完成后，它需要把安装包上传到你的 GitHub 仓库 Releases 页面,但问题来了：GitHub 怎么知道这个虚拟机是你的仓库授权的？凭什么允许它修改你的仓库？答案就是 GITHUB_TOKEN：secrets.GITHUB_TOKEN 是 GitHub Actions 运行时自动生成的内置临时密钥。你不需要去个人设置里手动申请 Token，GitHub 会在每次工作流触发时，自动为当前仓库签发一个专属令牌。通过 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}，我们把这个通行证注入到了打包环境变量中。当 electron-builder 执行 --publish always 时，它会读取这个环境变量，向 GitHub 的 API 发送请求："我是本项目合法的打包进程，这是我的通行证，请帮我把这些安装包挂载到对应的 Release 页面上。"

yml 复制代码

name: Build and Release

on:
  push:
    tags:
      - 'v*' # 触发条件：推送 v* 标签时（例如 v1.0.1）

jobs:
  release:
    name: Build and Release Electron App
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [windows-latest, macos-latest,ubuntu-latest] 

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # 1. 全局安装并启用 pnpm
      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8
          run_install: false

      # 2. 获取 pnpm 缓存路径并配置缓存，加速依赖安装
      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v4
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-

      - name: Install dependencies
        run: pnpm install

      - name: Build and Publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          pnpm run build
          pnpm exec electron-builder --publish always

2. 配置打包规则：`package.json`

光有流水线还不够，我们还需要在 package.json 的 build 字段中精细化控制打包输出、多架构适配以及发布行为：

关键点解析：

directories.output ：将打包产物统一输出到专用的 release 目录，防止和前端 Vite 的编译产物混淆冲突。
publish.releaseType: "release" ：确保打包完成后，云端直接生成正式版（非草稿状态）的 Release。
macOS 双架构配置 ：通过 target: ["dmg", "zip"] 配合 arch: ["x64", "arm64"]，一次性搞定 Intel 芯片和苹果自研 M 系列芯片的全覆盖。

js 复制代码

{
  "name": "five-in-row",
  "version": "1.0.2",
  "main": "dist-electron/main.js",
  "scripts": {
    "build": "vite build && electron-builder"
  },
  "build": {
    "appId": "com.example.fiveinrow",
    "productName": "FiveInRow",
    "directories": {
      "output": "release"
    },
    "publish": [
      {
        "provider": "github",
        "owner": "你的GitHub用户名",
        "repo": "你的仓库名",
        "releaseType": "release"
      }
    ],
    "win": {
      "target": ["nsis"]
    },
    "mac": {
      "target": ["dmg", "zip"],
      "arch": ["x64", "arm64"]
    },
    "linux": {
      "target": ["AppImage"]
    }
  }
}

3. 避坑：赋予云端写权限（Workflow permissions）

很多开发者在第一次配置自动化发布时，往往会卡在最后一步------代码跑通了，但安装包就是传不到 Releases 页面。这是因为 GitHub 默认的 GITHUB_TOKEN 是只读的。

我们需要在仓库后台手动放开权限：

打开你的 GitHub 仓库主页，点击顶部导航栏的 Settings（设置） 。
在左侧边栏找到 Actions -> General。
滚动到页面中下方的 Workflow permissions 区域。
将其勾选为 Read and write permissions（读和写权限） 。
点击底部的 Save 保存。

效果演示

Step 1 修改并提交代码

修改package.json中的版本号，并提交代码

bash 复制代码

git add .
git commit -m '自动化跨平台打包演示'
git push origin master

Step2 打tag并推送到远程仓库

bash 复制代码

git tag v1.0.2 && git push origin v1.0.2

如果出现失误，删除重新打tag

bash 复制代码

git tag -d v1.0.2
git push origin :refs/tags/v1.0.2

之后会触发三个作业流水线，进行编译打包

打出之后发布到了release菜单下，可供用户下载

结语：让自动化成为标配

回过头来看，从最初在 Windows 下手忙脚乱的单平台打包，到面对 macOS 和 Linux 跨平台编译时的硬件窘境，再到如今借助 GitHub Actions 实现"推完代码打个 Tag，喝杯咖啡拿全平台安装包"的丝滑体验，CI/CD 带来的不仅是效率的质变，更是开发幸福感的提升。

希望这篇全纪录能帮你扫清 Electron 跨平台发布的最后一道障碍，让你的应用能够顺畅地触达每一位用户。如果你在实践过程中遇到了其他有趣的坑或更好的优化方案，欢迎随时交流探讨！

Electron 自动化发布指南：GitHub Actions 跨平台打包全纪录

前言

GitHub Actions 凭什么能一键打通全平台

1. 云端动态宿主机

2. electron-builder 的全平台适配能力

实战落地

1. 编写工作流：release.yml

2. 配置打包规则：package.json

3. 避坑：赋予云端写权限（Workflow permissions）

效果演示

结语：让自动化成为标配

2. `electron-builder` 的全平台适配能力

1. 编写工作流：`release.yml`

2. 配置打包规则：`package.json`