Electron Skill

🤖 AI 接入指南：将本页链接发送给 AI，自动完成接入指导

快速信息

应用类型: Electron
Skill 版本: 2.0.0
接入难度: ⭐⭐ (简单)
预计时间: 15-30 分钟

📖 接入场景说明

根据项目类型，选择合适的接入方式：

场景	适用项目	特点	预计时间
场景一	非开源项目、私有项目	手动构建上传，数据上报	15 分钟
场景二	开源项目	GitHub Actions 自动化构建发布	30 分钟

场景一：非开源项目接入

适用于私有项目或不需要 GitHub Actions 自动化部署的项目。

1. 安装依赖

bash

npm install electron-updater

2. 创建 dev-update.yml

在项目根目录创建 dev-update.yml：

yaml

provider: generic
updaterCacheDirName: your-app-updater

3. 添加主进程代码

typescript

import { autoUpdater } from 'electron-updater';
import { app } from 'electron';

async function checkForUpdates() {
  const FeedURL = `https://api.upgrade.toolsetlink.com/v1/electron/upgrade?electronKey=YOUR_ELECTRON_KEY&versionName=${app.getVersion()}&appointVersionName=&devModelKey=&devKey=&platform=${process.platform}&arch=${process.arch}`;
  
  autoUpdater.setFeedURL({
    url: FeedURL,
    provider: 'generic',
  });
  
  autoUpdater.requestHeaders = {
    'X-AccessKey': 'YOUR_ACCESS_KEY',
  };
  
  const result = await autoUpdater.checkForUpdates();
  return result;
}

async function downloadUpdate() {
  const result = await checkForUpdates();
  if (result?.updateInfo) {
    autoUpdater.setFeedURL({
      url: result.updateInfo.path,
      provider: 'generic',
    });
    await autoUpdater.downloadUpdate();
  }
}

⚠️ 注意：将 YOUR_ELECTRON_KEY 和 YOUR_ACCESS_KEY 替换为您的实际密钥

4. 数据上报集成

在升级流程中，调用数据上报接口记录升级状态，以便进行数据统计和分析。

上报工具函数

typescript

import crypto from 'crypto';

function generateSignature(timestamp: string, nonce: string, body: string, accessSecret: string): string {
  const signStr = `timestamp=${timestamp}&nonce=${nonce}&body=${body}&accessSecret=${accessSecret}`;
  return crypto.createHash('md5').update(signStr).digest('hex');
}

function generateNonce(length: number = 16): string {
  return crypto.randomBytes(Math.ceil(length / 2)).toString('hex').slice(0, length);
}

async function reportEvent(
  eventType: string,
  appKey: string,
  eventData: Record<string, any>,
  accessKey: string,
  accessSecret: string
): Promise<void> {
  const timestamp = new Date().toISOString();
  const nonce = generateNonce();
  const body = JSON.stringify({
    eventType,
    timestamp,
    appKey,
    eventData,
  });
  
  const signature = generateSignature(timestamp, nonce, body, accessSecret);
  
  try {
    const response = await fetch('https://api.upgrade.toolsetlink.com/v1/app/report', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Timestamp': timestamp,
        'X-Nonce': nonce,
        'X-AccessKey': accessKey,
        'X-Signature': signature,
      },
      body,
    });
    
    const result = await response.json();
    console.log('上报结果:', result);
  } catch (error) {
    console.error('上报失败:', error);
  }
}

下载事件上报

typescript

function reportDownload(downloadVersionCode: number, code: number) {
  reportEvent(
    'app_upgrade_download',
    'YOUR_ELECTRON_KEY',
    {
      versionCode: parseInt(app.getVersion().split('.').join('')),
      downloadVersionCode,
      code,
      target: process.platform,
      arch: process.arch,
    },
    'YOUR_ACCESS_KEY',
    'YOUR_ACCESS_SECRET'
  );
}

升级完成事件上报

typescript

function reportUpgrade(upgradeVersionCode: number, code: number) {
  reportEvent(
    'app_upgrade_upgrade',
    'YOUR_ELECTRON_KEY',
    {
      versionCode: parseInt(app.getVersion().split('.').join('')),
      upgradeVersionCode,
      code,
      target: process.platform,
      arch: process.arch,
    },
    'YOUR_ACCESS_KEY',
    'YOUR_ACCESS_SECRET'
  );
}

完整升级流程示例

typescript

import { autoUpdater } from 'electron-updater';
import { app, BrowserWindow } from 'electron';

let upgradeVersionCode = 0;

autoUpdater.on('download-progress', (progressObj) => {
  console.log(`下载进度: ${progressObj.percent}%`);
});

autoUpdater.on('update-downloaded', (info) => {
  console.log('下载完成:', info.version);
  upgradeVersionCode = parseInt(info.version.split('.').join(''));
  
  reportDownload(upgradeVersionCode, 0);
  
  const win = BrowserWindow.getFocusedWindow();
  if (win) {
    win.webContents.send('update-downloaded', info);
  }
});

autoUpdater.on('error', (error) => {
  console.error('更新错误:', error);
  
  if (upgradeVersionCode > 0) {
    reportDownload(upgradeVersionCode, 1);
  }
});

function reportAppStart() {
  reportEvent(
    'app_start',
    'YOUR_ELECTRON_KEY',
    {
      versionCode: parseInt(app.getVersion().split('.').join('')),
      launchTime: new Date().toISOString(),
      target: process.platform,
      arch: process.arch,
    },
    'YOUR_ACCESS_KEY',
    'YOUR_ACCESS_SECRET'
  );
}

app.whenReady().then(() => {
  reportAppStart();
});

状态码说明

下载事件 code：

状态码	说明
0	下载成功
1	下载失败（泛用）
1001	HTTP 错误
1002	空间不足
1003	文件操作错误
1004	MD5 校验失败

升级事件 code：

状态码	说明
0	升级成功
1	升级失败

📖 详细接口文档：事件上报接口

5. 手动构建与上传

构建应用

bash

npm run build

生成的文件

平台	文件
macOS	`.dmg`、`.zip`、`latest-mac.yml`
Windows	`.exe`、`.msi`、`latest.yml`
Linux	`.AppImage`、`.deb`、`latest-linux.yml`

上传到 UpgradeLink

登录 UpgradeLink 后台
进入应用管理页面
创建新版本，上传对应的安装包和 yml 文件
配置升级策略

场景二：开源项目接入

适用于开源项目，需要 GitHub Actions 自动化构建、发布和更新。

1. 完成基础接入

首先完成场景一的所有步骤（1-4）。

2. 配置 GitHub Secrets

在 GitHub 仓库的 Settings > Security > Secrets and variables > Actions 中添加以下加密环境变量：

Secret 名称	说明	获取方式
`UPGRADE_LINK_ACCESS_KEY`	UpgradeLink 访问密钥	UpgradeLink 后台 > 密钥管理
`UPGRADE_LINK_ELECTRON_KEY`	Electron 应用唯一标识	UpgradeLink 后台 > 应用信息

3. 配置 GitHub Actions 工作流

在项目根目录创建 .github/workflows/publish.yml：

yaml

name: 'publish'

on:
  push:
    branches:
      - main
    tags:
      - '*.*.*'

jobs:
  electron-build:
    outputs:
      appVersion: ${{ steps.extract-version.outputs.appVersion }}
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: ubuntu-22.04
            target: x86_64-unknown-linux-gnu
            artifact-name: ubuntu-x86_64
            arch-suffix: x64
            build-command: "yarn electron-builder --linux --x64 --publish always --config.publish.channel=latest-linux"

          - platform: ubuntu-22.04
            target: aarch64-unknown-linux-gnu
            artifact-name: ubuntu-aarch64
            arch-suffix: arm64
            build-command: "yarn electron-builder --linux --arm64 --publish always --config.publish.channel=latest-linux"

          - platform: macos-latest
            target: aarch64-apple-darwin
            artifact-name: macos-arm64
            arch-suffix: arm64
            build-command: "yarn electron-builder --mac --arm64 --publish always --config.publish.channel=latest-mac"

          - platform: macos-latest
            target: x86_64-apple-darwin
            artifact-name: macos-x64
            arch-suffix: x64
            build-command: "yarn electron-builder --mac --x64 --publish always --config.publish.channel=latest-mac"

          - platform: windows-latest
            target: x86_64-pc-windows-msvc
            artifact-name: windows-x64
            arch-suffix: x64
            build-command: "yarn electron-builder --win --x64 --publish always --config.publish.channel=latest-win"

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: setup node
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install

      - name: Build Electron App
        run: ${{ matrix.build-command }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract version
        id: extract-version
        run: |
          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
            VERSION=${{ github.ref_name }}
          else
            VERSION=$(node -p "require('./package.json').version")
          fi
          echo "appVersion=$VERSION" >> $GITHUB_OUTPUT
          echo "Extracted version: $VERSION"
        shell: bash

      - name: Upload artifacts
        uses: actions/upload-artifact@v4.0.0
        with:
          name: ${{ matrix.artifact-name }}
          path: dist/*
          if-no-files-found: error

  electron-release:
    needs: electron-build
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    steps:
      - name: Download all artifacts
        uses: actions/download-artifact@v4
        with:
          path: artifacts
          merge-multiple: false

      - name: Prepare release files
        run: |
          mkdir -p release-files
          find artifacts -type f -exec cp {} release-files/ \;

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          tag_name: ${{ needs.electron-build.outputs.appVersion }}
          name: Release ${{ needs.electron-build.outputs.appVersion }}
          files: release-files/*
          draft: false
          prerelease: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  upgradeLink-upload:
    needs: [electron-build, electron-release]
    permissions:
      contents: write
    runs-on: ubuntu-latest
    steps:
      - name: Send a request to UpgradeLink
        uses: toolsetlink/upgradelink-action-electron@v1.0.1
        with:
          source-url: 'https://github.com/${{ github.repository }}/releases/download/${{ needs.electron-build.outputs.appVersion }}'
          access-key: ${{ secrets.UPGRADE_LINK_ACCESS_KEY }}
          electron-key: ${{ secrets.UPGRADE_LINK_ELECTRON_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          version: ${{ needs.electron-build.outputs.appVersion }}
          prompt-upgrade-content: '发现新版本，建议升级'

4. 工作流详解

electron-build 作业

功能：跨平台构建 Electron 应用

步骤	说明
检出代码	`actions/checkout@v4`
安装 Node.js	设置 Node.js LTS 版本
安装依赖	`yarn install`
构建应用	使用 `electron-builder` 构建
提取版本号	从 tag 或 package.json 提取
上传产物	上传构建产物供后续使用

多平台构建策略：

平台	Runner	架构
Linux (x64)	ubuntu-22.04	x64
Linux (ARM)	ubuntu-22.04	arm64
macOS (M1+)	macos-latest	arm64
macOS (Intel)	macos-latest	x64
Windows	windows-latest	x64

electron-release 作业

功能：创建 GitHub Release 并上传安装包

步骤	说明
下载产物	从 `electron-build` 下载所有构建产物
准备文件	整理发布文件
创建 Release	使用 `softprops/action-gh-release` 创建发布

upgradeLink-upload 作业

功能：将更新信息同步到 UpgradeLink 平台

步骤	说明
等待构建	依赖 `electron-build` 和 `electron-release` 完成
获取版本号	从 `electron-build` 输出获取
上传信息	使用 `upgradelink-action-electron` 同步

UpgradeLink Action 参数：

参数	说明
`source-url`	GitHub Releases 地址
`access-key`	UpgradeLink 访问密钥
`electron-key`	Electron 应用唯一标识
`github-token`	GitHub Token
`version`	应用版本号
`prompt-upgrade-content`	升级提示内容

5. UpgradeLink 平台配置

在 UpgradeLink 后台配置 GitHub 仓库地址：

登录 UpgradeLink 后台
进入应用管理 > Electron 应用详情
在「GitHub 仓库地址」字段填入仓库地址，如：https://github.com/username/repo-name
保存配置

6. 自动化流程说明

当代码推送到 main 分支时，自动化流程如下：

代码推送
    │
    ▼
┌─────────────────────────────────────────┐
│         electron-build 作业              │
│  ┌─────────────────────────────────┐    │
│  │ 并行构建 5 个平台                │    │
│  │ - Linux (x64)                   │    │
│  │ - Linux (ARM)                   │    │
│  │ - macOS (M1)                    │    │
│  │ - macOS (Intel)                 │    │
│  │ - Windows                       │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│        electron-release 作业             │
│  ┌─────────────────────────────────┐    │
│  │ 创建 GitHub Release              │    │
│  │ 上传安装包和 yml 文件            │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│       upgradeLink-upload 作业            │
│  ┌─────────────────────────────────┐    │
│  │ 读取 GitHub Releases             │    │
│  │ 调用 UpgradeLink API             │    │
│  │ 自动创建版本和升级策略            │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
    │
    ▼
用户收到更新通知

🤖 AI 接入

将本页链接发送给 AI：

请帮我接入 Electron 应用升级，这是 Skill 链接：
https://www.toolsetlink.com/upgrade/skill/electron

AI 将自动：

识别应用类型为 Electron
判断项目类型（开源/非开源）
获取配置信息和示例代码
指导您替换占位符
验证配置正确性
完成接入测试

📋 完整示例

查看完整示例项目：electron-demo

❓ 常见问题

Q: 如何获取 Electron Key？

A: 登录 UpgradeLink 后台，创建 Electron 应用后获取。

Q: 如何获取 Access Key 和 Access Secret？

A: 登录 UpgradeLink 后台，在密钥管理页面获取。

Q: 更新失败怎么办？

A: 检查网络连接、配置是否正确，或联系 AI 获取帮助。

Q: 数据上报失败会影响升级流程吗？

A: 不会。数据上报是异步操作，失败不会影响正常的升级流程。建议在业务低峰期重试。

Q: macOS 应用签名问题？

A: macOS 应用必须签名才能使自动更新工作。请参考 Electron Builder 文档。

Q: GitHub Actions 构建失败怎么办？

检查 GitHub Actions 日志，查看具体错误信息
确认所有依赖已正确安装
确保 Node.js 版本兼容
检查 GitHub Secrets 是否配置正确

Url应用

文件应用

配置

Tauri应用

Electron应用

安卓应用

Windows应用

Linux应用

Macos应用

应用上报信息

Url应用

文件应用

配置

Tauri应用

Electron应用

安卓应用

Windows应用

Linux应用

Macos应用

应用上报信息

Url应用

文件应用

配置

Tauri应用

Electron应用

安卓应用

Windows应用

Linux应用

Macos应用

应用上报信息

Url应用

文件应用

配置

Tauri应用

Electron应用

安卓应用

Windows应用

Linux应用

Macos应用

应用上报信息

Url应用

文件应用

Url应用

文件应用

安卓应用

配置升级

Url应用

文件应用

Windows应用

配置升级

Electron Skill ​

快速信息 ​

📖 接入场景说明 ​

场景一：非开源项目接入 ​

1. 安装依赖 ​

2. 创建 dev-update.yml ​

3. 添加主进程代码 ​

4. 数据上报集成 ​

上报工具函数 ​

下载事件上报 ​

升级完成事件上报 ​

完整升级流程示例 ​

状态码说明 ​

5. 手动构建与上传 ​

构建应用 ​

生成的文件 ​

上传到 UpgradeLink ​

场景二：开源项目接入 ​

1. 完成基础接入 ​

2. 配置 GitHub Secrets ​

3. 配置 GitHub Actions 工作流 ​

4. 工作流详解 ​

electron-build 作业 ​

electron-release 作业 ​

upgradeLink-upload 作业 ​

5. UpgradeLink 平台配置 ​

6. 自动化流程说明 ​

🤖 AI 接入 ​

📋 完整示例 ​

❓ 常见问题 ​

Electron Skill

快速信息

📖 接入场景说明

场景一：非开源项目接入

1. 安装依赖

2. 创建 dev-update.yml

3. 添加主进程代码

4. 数据上报集成

上报工具函数

下载事件上报

升级完成事件上报

完整升级流程示例

状态码说明

5. 手动构建与上传

构建应用

生成的文件

上传到 UpgradeLink

场景二：开源项目接入

1. 完成基础接入

2. 配置 GitHub Secrets

3. 配置 GitHub Actions 工作流

4. 工作流详解

electron-build 作业

electron-release 作业

upgradeLink-upload 作业

5. UpgradeLink 平台配置

6. 自动化流程说明

🤖 AI 接入

📋 完整示例

❓ 常见问题

Q: 如何获取 Electron Key？

Q: 如何获取 Access Key 和 Access Secret？

Q: 更新失败怎么办？

Q: 数据上报失败会影响升级流程吗？

Q: macOS 应用签名问题？

Q: GitHub Actions 构建失败怎么办？

📚 参考资源