基于 electron-autoupdate-server 的 Electron 应用自动更新后端搭建与实战

的灵活性来源于其丰富的配置选项。合理设置这些参数不仅能提升服务性能，还能增强跨平台兼容性和安全性。本节将详细解析关键配置字段，并结合实际案例说明如何根据企业需求进行定制化调整。为提高代码组织性，建议将更新逻辑封装为独立类：// 手动控制下载时机});});try {主进程导入：MethodGETPathHeadersAccept:200 OK: 存在新版本，返回更新元数据: 当前已是最新版: 平台

莱财一哥

1344人浏览 · 2025-10-22 11:08:19

莱财一哥 · 2025-10-22 11:08:19 发布

本文还有配套的精品资源，点击获取

简介： electron-autoupdate-server 是一个使用 JavaScript 编写的、专为 Electron 应用提供自动更新能力的服务端解决方案，可与 electron-builder 和 electron-updater 等前端工具无缝集成。该服务通过提供版本管理 API 和更新文件存储功能，实现客户端应用的新版本检测、下载与静默安装，提升用户体验。本文详细介绍其部署流程、前后端集成方法、安全性配置及常见问题解决策略，帮助开发者快速构建安全可靠的自动更新系统。
electron-autoupdate-server:electron 应用自动更新服务后台

1. Electron 自动更新机制原理详解

Electron 的自动更新机制建立在 Squirrel 框架之上，通过前后端协同实现版本检测与静默升级。其核心流程始于客户端调用 autoUpdater.checkForUpdates() ，向指定服务器发起 HTTPS 请求获取最新版本元数据文件（如 latest.yml 或 latest-mac.json ）。系统依据当前应用版本号进行语义化比对（semver），判断是否存在可用更新。

// 示例：主进程中触发更新检查
const { autoUpdater } = require('electron-updater');
autoUpdater.setFeedURL({ url: 'https://your-update-server.com/update/win32/1.0.0' });
autoUpdater.checkForUpdates();

若存在新版本， autoUpdater 将依次触发 update-available → 下载进度事件 → update-downloaded 事件，驱动安装流程。更新包通常包含完整安装器（full）和增量补丁（delta），服务端根据客户端版本智能返回最优更新类型，减少带宽消耗。

整个机制依赖 HTTPS 安全通道保障传输完整性，并结合代码签名防止恶意篡改。Windows 使用 Squirrel.Windows ，macOS 则基于 Squirrel.Mac 实现应用替换，二者均采用“差分更新 + 原子提交”策略，确保更新过程崩溃可回滚。

graph TD
    A[客户端启动] --> B{是否启用自动更新}
    B -->|是| C[发送GET请求至/update/:platform/:version]
    C --> D[解析latest.yml/latest-mac.json]
    D --> E[比较本地与远程版本]
    E --> F{有新版本?}
    F -->|是| G[下载更新包(支持断点续传)]
    G --> H[安装前备份旧版本]
    H --> I[应用增量或完整更新]
    I --> J[重启并清理临时文件]
    F -->|否| K[保持运行]

为何必须构建独立更新服务？因为 Electron 官方不提供托管服务，开发者需自行部署以控制发布节奏、支持灰度发布、实现访问鉴权与行为追踪。 electron-autoupdate-server 正是为此而生——它不仅提供标准 RESTful 接口响应更新请求，还能自动生成元数据、管理存储路径、适配多平台格式，成为整套更新体系的中枢组件。

2. electron-autoupdate-server 服务端部署与配置

在构建具备自动更新能力的 Electron 桌面应用时，仅完成客户端逻辑是远远不够的。一个稳定、可扩展且安全的服务端更新系统才是支撑整个自动更新机制长期运行的核心基础设施。 electron-autoupdate-server 是专为 Electron 应用设计的轻量级更新服务器实现，它能够托管发布包、生成符合 Squirrel 框架要求的元数据文件（如 latest.yml 或 latest-mac.json ），并响应来自不同平台客户端的版本检测请求。本章节将深入探讨如何从零开始搭建和配置 electron-autoupdate-server ，涵盖环境准备、核心参数调优、生产级部署方案以及监控体系建立等关键环节，确保其能够在真实业务场景中高效可靠地运行。

2.1 服务端环境搭建与依赖安装

为了使 electron-autoupdate-server 正常运行，首先需要搭建一个兼容 Node.js 的后端运行环境，并正确初始化项目依赖。该过程不仅涉及基础软件栈的选择与安装，还需考虑版本兼容性、安全性及未来可维护性。选择合适的 Node.js 版本对于避免潜在的模块冲突至关重要，尤其是在使用某些底层二进制插件或处理 HTTPS 请求时。

2.1.1 Node.js 运行时环境准备与版本选择

Node.js 作为 electron-autoupdate-server 的运行时基础，其版本直接影响到服务的稳定性与性能表现。推荐使用 LTS（Long Term Support）版本 ，例如当前主流的 v18.x 或 v20.x 系列，这些版本经过广泛测试，拥有更长的支持周期和更高的社区支持度。避免使用已进入维护期或已被弃用的版本（如 v14.x 及以下），以防止因安全漏洞或依赖不兼容导致的问题。

可以通过以下命令检查本地 Node.js 版本：

node --version
npm --version

若未安装或需升级，建议通过官方 LTS 安装包或使用版本管理工具（如 nvm for Linux/macOS 或 nvm-windows ）进行管理：

# 使用 nvm 安装并切换至 Node.js v18 LTS
nvm install 18
nvm use 18

选择 Node.js v18+ 的另一个重要原因是其对现代 JavaScript 特性（ES2022+）、HTTP/2 支持、V8 引擎优化以及更好的 TLS 1.3 实现提供了原生支持，这对后续启用 HTTPS 和高并发访问至关重要。

Node.js 版本	支持状态	推荐用途
v14.x	已停止维护（2023年4月终止）	不推荐使用
v16.x	维护期结束（2023年9月）	仅限遗留项目
v18.x	Active LTS（至2025年4月）	推荐用于生产环境
v20.x	Maintenance LTS（自2025年起）	新项目首选

注意： electron-autoupdate-server 基于 Express 构建，依赖大量 npm 包，因此必须保证 Node.js 和 npm 能正常解析 package.json 并下载依赖。

2.1.2 npm 包管理与 electron-autoupdate-server 初始化

完成 Node.js 环境配置后，接下来初始化项目并安装 electron-autoupdate-server 。尽管该服务并非由官方 Electron 团队开发，但在社区中已被广泛采用，具有良好的文档支持和活跃的维护记录。

创建项目目录并初始化：

mkdir electron-update-server
cd electron-update-server
npm init -y

随后安装核心依赖：

npm install electron-autoupdate-server express

然后创建入口文件 server.js ：

const express = require('express');
const path = require('path');
const { createAutoUpdateServer } = require('electron-autoupdate-server');

const app = express();
const PORT = process.env.PORT || 3000;

// 配置更新服务器选项
const updateOptions = {
  storage: path.join(__dirname, 'storage'), // 存放构建产物和元数据
  platform: ['win32', 'darwin', 'linux'],   // 支持多平台
  serveFiles: true,                         // 启用静态资源服务
};

// 创建自动更新路由
app.use('/update', createAutoUpdateServer(updateOptions));

// 提供静态资源访问（可选）
app.use('/downloads', express.static(updateOptions.storage));

app.listen(PORT, () => {
  console.log(`[INFO] Electron 更新服务器启动于 http://localhost:${PORT}`);
  console.log(`[INFO] 更新接口路径: /update/:platform/:version`);
});

代码逻辑逐行解读：

第1–3行：引入 Express 框架、Node.js 内置 path 模块和 electron-autoupdate-server 提供的工厂函数。
第6行：定义 HTTP 服务实例。
第9–13行：设置更新服务器的核心配置项：
storage ：指定用于存储上传的应用程序包（如 .exe , .dmg , .AppImage ）及其对应元数据（ latest.yml 等）的本地路径；
platform ：声明支持的操作系统平台列表，影响 /update/:platform 路由的行为；
serveFiles ：是否允许通过 HTTP 直接下载更新包，默认开启。
第16行：挂载 /update 路由，由 createAutoUpdateServer 中间件处理所有更新相关请求。
第19行：额外暴露 /downloads 路径用于调试或外部 CDN 加速。
第21–24行：启动服务并输出提示信息。

启动服务：

node server.js

此时服务将在 http://localhost:3000/update/win32/1.0.0 上监听来自 Windows 客户端的更新请求。当客户端发起 GET 请求时，服务会查找是否存在比当前版本更新的版本，并返回相应的元数据文件。

graph TD
    A[客户端发起 /update/win32/1.0.0] --> B{服务端接收请求}
    B --> C[解析平台 win32 和当前版本 1.0.0]
    C --> D[读取 storage/latest.yml]
    D --> E[比较版本号]
    E --> F[返回最新版本信息或 304 Not Modified]
    F --> G[客户端决定是否下载]

该流程体现了典型的 RESTful 设计风格，基于 URL 参数驱动版本判断逻辑。同时，由于 electron-autoupdate-server 自动化生成 latest.yml 文件，开发者无需手动编写 YAML 内容，极大简化了运维成本。

此外，在 CI/CD 流程中，每次打包完成后可自动将输出文件上传至 storage 目录，并触发元数据刷新，从而实现“构建即发布”的自动化流水线。

2.2 核心配置项解析与自定义设置

electron-autoupdate-server 的灵活性来源于其丰富的配置选项。合理设置这些参数不仅能提升服务性能，还能增强跨平台兼容性和安全性。本节将详细解析关键配置字段，并结合实际案例说明如何根据企业需求进行定制化调整。

2.2.1 存储路径、端口、静态资源目录设定

除了上文提到的 storage 路径外，还应明确以下几个关键路径与网络参数：

const updateOptions = {
  storage: path.resolve('./artifacts'),     // 构建产物存储根目录
  metadataDir: path.resolve('./meta'),      // 元数据单独存放（可选）
  port: 3000,                               // 显式指定端口
  host: '0.0.0.0',                          // 绑定所有网络接口
  maxAge: '1y',                             // 缓存控制头，适用于 CDN 场景
  transformName: (fileName, platform) => {
    return `${platform}-${fileName}`;       // 自定义文件命名规则
  }
};

参数名	类型	默认值	说明
`storage`	string	`./storage`	主要用于存放上传的安装包和自动生成的 `latest.yml`
`metadataDir`	string	同 `storage`	若希望分离元数据与二进制文件，可独立设置
`port`	number	3000	服务监听端口，可通过环境变量覆盖
`host`	string	`localhost`	设置为 `0.0.0.0` 以便外部访问
`maxAge`	string	`'1h'`	控制 `Cache-Control` 头部，减少重复请求
`transformName`	function	identity	自定义上传文件重命名策略

特别地， transformName 函数可用于规范化文件命名，防止冲突。例如：

transformName: (originalName, platform, version) => {
  return `[${platform}]-v${version}-${Date.now()}.exe`;
}

这有助于在审计日志中快速识别来源。

2.2.2 支持平台（Windows/macOS/Linux）识别规则配置

electron-autoupdate-server 支持三大主流桌面操作系统，但各平台的更新机制存在差异：

Windows ：基于 Squirrel.Windows，使用 RELEASES 和 .nupkg 文件，最终生成 latest.yml
macOS ：遵循 Sparkle 框架规范，期望返回 latest-mac.json 或 XML feed
Linux ：通常依赖 AppImage/Snap，无统一标准，需自定义处理

因此，在配置中明确声明支持的平台非常重要：

platform: ['win32', 'darwin', 'linux'],
allowPrerelease: true, // 是否允许 beta 版本参与更新
channelMapping: {
  'win32': 'stable',
  'darwin': 'beta'
} // 按平台指定更新通道

服务器会根据请求路径中的 :platform 参数（如 /update/darwin/1.2.0 ）自动匹配对应平台的元数据文件。对于 macOS，若启用了 Sparkle 兼容模式，还会生成 appcast.xml 。

2.2.3 自动生成更新元数据文件策略

元数据文件是自动更新的核心桥梁。 electron-autoupdate-server 在每次新版本上传后会自动重建 latest.yml （Windows）或 latest-mac.json （macOS）。以 Windows 为例， latest.yml 结构如下：

version: 1.3.0
url: https://your-server.com/downloads/MyApp-Setup-1.3.0.exe
sha512: base64encodedhash==
size: 123456789

该文件由服务端在检测到新文件上传后自动生成，计算 SHA512 哈希值并填充大小信息。此过程依赖于文件扫描机制，可通过配置控制频率：

autoGenerate: true,
generateInterval: 5000 // 每5秒检查一次新文件

也可以通过 API 触发手动刷新：

curl -X POST http://localhost:3000/update/rebuild

pie
    title 元数据生成方式占比
    “自动扫描” : 70
    “CI/CD推送触发” : 20
    “手动调用API” : 10

推荐结合 CI 工具（如 GitHub Actions）在构建成功后主动通知服务器重建元数据，而非依赖轮询，以提高时效性。

2.3 反向代理与生产级部署方案

在生产环境中，直接暴露 Node.js 服务存在安全隐患且难以应对高并发请求。因此，必须通过反向代理（如 Nginx）实现 HTTPS 卸载、负载均衡和静态资源缓存。

2.3.1 Nginx 配置反向代理实现 HTTPS 终端卸载

以下是典型的 Nginx 配置片段：

server {
    listen 443 ssl;
    server_name update.yourapp.com;

    ssl_certificate /etc/nginx/ssl/update.crt;
    ssl_certificate_key /etc/nginx/ssl/update.key;

    location /update/ {
        proxy_pass http://127.0.0.1:3000/update/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /downloads/ {
        alias /opt/electron-update-server/artifacts/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

此配置实现了：
- SSL 加密通信（HTTPS）
- 请求头透传，便于日志追踪
- 静态资源直出，减轻 Node.js 负担
- 支持 CDN 缓存长期不变的安装包

2.3.2 Docker 容器化部署实践与 CI/CD 集成

使用 Docker 封装服务可提升部署一致性：

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

配合 docker-compose.yml ：

version: '3'
services:
  updater:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./artifacts:/app/artifacts
      - ./meta:/app/meta
    environment:
      - NODE_ENV=production

在 CI/CD 流水线中，可添加步骤：

- name: Build and Push Docker Image
  run: |
    docker build -t your-registry/electron-updater:v${{ env.VERSION }} .
    docker push your-registry/electron-updater:v${{ env.VERSION }}

- name: Deploy to Server
  run: ssh deploy@server "docker-compose pull && docker-compose up -d"

实现一键发布。

2.4 服务健康监测与日志追踪

2.4.1 请求日志记录与客户端行为分析

启用详细日志有助于排查问题：

app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`${req.method} ${req.path} ${res.statusCode} - ${duration}ms`);
  });
  next();
});

记录字段包括：
- 客户端 IP
- User-Agent（识别平台和版本）
- 请求路径
- 响应码
- 处理耗时

可导入 ELK 或 Prometheus + Grafana 进行可视化分析。

2.4.2 错误码响应体系与监控告警机制建立

定义标准错误响应：

状态码	含义	示例场景
200	找到新版本	返回 `latest.yml`
304	无更新	客户端已是最新版
400	请求格式错误	平台不支持
404	资源不存在	版本路径无效
500	服务器内部错误	元数据生成失败

结合 Sentry 或 Prometheus 报警规则：

rules:
  - alert: HighErrorRate
    expr: rate(http_requests_total{code=~"5.."}[5m]) > 0.1
    for: 10m
    labels:
      severity: critical

确保第一时间发现异常。

3. electron-builder 打包与自动更新支持

在 Electron 应用的发布生命周期中， electron-builder 是目前最主流、功能最全面的打包工具。它不仅支持跨平台（Windows、macOS、Linux）构建原生安装包，还深度集成了自动更新机制所需的元数据生成和发布流程管理能力。本章将深入探讨如何通过 electron-builder 配置实现与 electron-autoupdate-server 协同工作的完整自动更新链条，涵盖从构建配置到签名验证、版本控制以及自动化发布的各个环节。

3.1 构建配置中启用自动更新功能

要使 Electron 应用具备自动更新能力，首先必须在 electron-builder 的构建配置中正确声明发布目标和服务端地址。这一过程不仅仅是填写 URL，更涉及安全策略、渠道划分和路径映射等关键决策，直接影响后续更新行为的准确性和可维护性。

3.1.1 在 `package.json` 中配置 publish 属性指向更新服务器

electron-builder 使用 publish 字段来定义应用更新包上传的目标位置及更新元信息获取方式。该字段可以配置为对象数组，支持多种发布类型，其中 generic 类型适用于自建更新服务如 electron-autoupdate-server 。

{
  "build": {
    "publish": [
      {
        "provider": "generic",
        "url": "https://updates.yourdomain.com/"
      }
    ],
    "appId": "com.example.myapp",
    "productName": "MyApp"
  }
}

参数说明：
- provider : 指定发布方式。 generic 表示使用通用 HTTP/HTTPS 服务器进行文件分发。
- url : 必须以 / 结尾，指向你的 electron-autoupdate-server 实例地址。客户端会基于此 URL 请求 latest.yml 或 latest-mac.json 等元数据文件。
- appId : 唯一标识应用，用于区分不同项目，在服务端存储结构中作为目录名使用。
- productName : 安装包名称，影响最终用户看到的应用标题。

代码逻辑分析：

上述 JSON 片段是 package.json 中 build 字段的一部分。当执行 electron-builder --publish always 时，构建系统会：
1. 先完成所有平台的打包任务；
2. 将生成的二进制文件（如 .exe , .dmg , .AppImage ）和对应的元数据文件（如 latest.yml ）上传至 url 指定的服务端；
3. 调用 electron-publish 模块处理上传逻辑，其底层依赖 fs-extra 和 axios 进行文件读取与 HTTP PUT/POST 请求。

⚠️ 注意：若未设置 --publish 参数或值为 onTag ，则不会触发上传动作。建议结合 CI/CD 流程使用 always 模式确保每次发布都同步至更新服务器。

此外， generic 提供商不支持自动重试或断点续传上传，因此需要保证网络稳定性。对于高可用部署场景，可在 Nginx 层面配置负载均衡和静态资源缓存策略。

3.1.2 设置发行渠道（stable/beta）与发布路径映射

为了实现灰度发布或 A/B 测试， electron-builder 支持通过 channel 参数区分不同的发布通道。这使得你可以同时维护多个版本线（如稳定版与测试版），并让客户端根据自身设定选择合适的更新源。

{
  "build": {
    "win": {
      "target": "nsis",
      "publish": [
        {
          "provider": "generic",
          "url": "https://updates.yourdomain.com/stable/",
          "channel": "latest"
        }
      ]
    },
    "mac": {
      "target": "dmg",
      "publish": [
        {
          "provider": "generic",
          "url": "https://updates.yourdomain.com/beta/",
          "channel": "beta"
        }
      ]
    }
  }
}

参数说明：
- channel : 客户端 autoUpdater 会据此请求特定路径下的元数据文件。例如， channel=beta 时，macOS 客户端将请求 https://updates.yourdomain.com/beta/latest-mac.json 。
- 不同平台可独立配置 publish ，便于实施差异化发布策略。

发布路径映射规则表：

平台	Channel 值	请求的元数据文件路径
Windows	latest	`${url}latest.yml`
Windows	beta	`${url}beta.yml`
macOS	latest	`${url}latest-mac.json`
macOS	beta	`${url}beta-mac.json`
Linux	latest	`${url}latest-linux.yml`

📌 提示：服务端需按此命名规范存放文件，并确保 Web Server 正确路由请求。例如 Nginx 应允许 .json 和 .yml 文件被公开访问。

mermaid 流程图：客户端根据 channel 获取更新信息

graph TD
    A[启动应用] --> B{是否开启自动更新?}
    B -->|是| C[读取当前版本号 & platform]
    C --> D[确定 channel: stable / beta]
    D --> E[拼接 update URL]
    E --> F[GET ${url}${channel}-*.json|.yml]
    F --> G{响应成功且有新版本?}
    G -->|是| H[触发 download]
    G -->|否| I[提示已是最新版]

该流程体现了 channel 在动态更新源选择中的核心作用。开发者可通过环境变量或配置文件控制 channel 值，从而灵活切换更新策略。

3.2 多平台打包输出与更新文件生成

Electron 应用需针对不同操作系统生成兼容的安装包格式，而每种格式都有其独特的更新机制和配套元数据要求。 electron-builder 在打包过程中会自动生成这些辅助文件，确保客户端能正确解析并执行更新操作。

3.2.1 Windows 平台 NSIS 安装包与 RELEASES 文件生成

在 Windows 上， electron-builder 默认使用 NSIS（Nullsoft Scriptable Install System）生成 .exe 安装程序。与此同时，还会创建一个名为 RELEASES 的文本文件，这是 Squirrel.Windows 框架用于增量更新的核心索引文件。

# 构建命令
npx electron-builder --win nsis

构建完成后，输出目录结构如下：

dist/
├── MyApp Setup 1.0.0.exe
├── MyApp-1.0.0-full.nupkg
└── RELEASES

RELEASES 文件内容示例：

5a8b7e9c7f3d4a2e8f1c0d2e3f4a5b6c MyApp-1.0.0-full.nupkg 12345678

每行包含三个字段：
1. SHA1 校验和 ：用于完整性验证；
2. NuGet 包名 ： .nupkg 文件是 Squirrel 使用的标准更新包格式；
3. 文件大小（字节） ：便于下载前预估资源消耗。

自动生成机制说明：

.nupkg 文件本质上是一个 ZIP 压缩包，内部包含应用资源和 app-1.0.0 目录；
每次新版本发布时， electron-builder 会比较前后两个 .nupkg 差异，生成差分更新包（ delta ），命名为 MyApp-1.1.0-delta.nupkg ；
RELEASES 文件追加新条目，保留历史记录以便回溯。

✅ 优势：Squirrel.Windows 支持静默安装、快捷方式创建、注册表写入等功能，适合企业级部署。

3.2.2 macOS 平台 DMG/ZIP 输出与 Sparkle 兼容性处理

macOS 上的自动更新依赖 Sparkle 框架，尽管 electron-updater 已内置封装，但仍需确保构建配置符合其规范。

{
  "build": {
    "mac": {
      "target": ["dmg", "zip"],
      "category": "public.app-category.productivity",
      "hardenedRuntime": true,
      "gatekeeperAssess": false
    }
  }
}

关键参数解释：

参数	含义
`target`	推荐同时输出 `.dmg` （用户友好）和 `.zip` （CI 自动化提取）
`category`	App Store 分类，提升系统识别度
`hardenedRuntime`	启用苹果硬运行时保护，避免 Gatekeeper 因权限问题阻止启动
`gatekeeperAssess`	设为 `false` 可绕过本地恶意软件扫描（仅限开发调试）

更新元数据文件： `latest-mac.json`

构建后生成的 latest-mac.json 内容如下：

{
  "version": "1.2.0",
  "url": "https://updates.yourdomain.com/MyApp-1.2.0.dmg",
  "pub_date": "2025-04-05T10:00:00Z",
  "sha512": "base64-encoded-checksum"
}

url : 下载链接，应指向 CDN 加速地址以提升用户体验；
sha512 : 使用 SHA-512 计算 .dmg 文件哈希，防止中间人篡改；
pub_date : 时间戳用于排序判断是否为最新版本。

表格：macOS 更新文件对比

文件格式	是否支持 Sparkle	是否推荐用于生产	备注
.dmg	✅	✅	用户交互良好，支持拖拽安装
.zip	✅	✅	易于自动化部署，但需手动解压
.pkg	❌	⚠️	通常用于系统级安装，不适合常规更新

🔐 安全提示：必须对 .dmg 进行代码签名（codesign）和公证（notarization），否则 macOS 会弹出“无法打开，因为来自未知开发者”警告。

3.2.3 Linux 平台 AppImage/Snap 包的更新适配问题

Linux 缺乏统一的包管理系统，导致自动更新实现较为复杂。目前主流方案包括 AppImage、Snap 和 Flatpak。

{
  "build": {
    "linux": {
      "target": ["AppImage", "snap"],
      "maintainer": "dev@example.com",
      "vendor": "Example Inc."
    }
  }
}

各格式更新机制对比：

格式	自动更新支持	实现方式	局限性
AppImage	⚠️ 有限	需自行集成检查脚本	无标准协议，依赖外部工具
Snap	✅	Ubuntu 商店自动推送	仅 Canonical 生态有效
Flatpak	✅	通过 OSTree 实现原子更新	需要额外运行时安装

💡 推荐做法：对于非 Snap 用户，可借助 electron-updater 的 GenericProvider 实现基于 HTTP 的更新检测，下载新的 AppImage 后替换旧文件并重启进程。

3.3 数字签名与完整性校验机制集成

数字签名是确保软件来源可信的关键环节，尤其在 Windows 和 macOS 上，缺少有效签名可能导致安装失败或安全警告。

3.3.1 Windows Authenticode 签名流程配置

要在 Windows 上签署 .exe 和 .dll 文件，需使用 EV（Extended Validation）证书并通过 signtool.exe 工具签名。

{
  "build": {
    "win": {
      "signingHashAlgorithms": ["sha256"],
      "certificateFile": "./certs/code-sign.pfx",
      "certificatePassword": "your-password"
    }
  }
}

参数说明：

signingHashAlgorithms : 推荐使用 sha256 ，兼容现代 UEFI 安全启动；
certificateFile : PFX/P12 格式的证书文件，包含私钥；
certificatePassword : 保护私钥的密码，建议通过环境变量注入而非明文存储。

签名执行流程：

# electron-builder 内部调用 signtool 的等效命令
signtool sign /f code-sign.pfx /p your-password /tr http://timestamp.digicert.com /td sha256 /fd sha256 MyApp Setup 1.0.0.exe

/tr : 指定时间戳服务器，防止证书过期后签名失效；
/td 和 /fd : 指定时间戳和文件摘要算法均为 SHA-256。

✅ 成功标志：右键查看属性 → “数字签名”标签可见有效签名信息。

3.3.2 macOS Gatekeeper 兼容性与 hardened runtime 设置

Apple 对第三方应用有严格的安全限制，必须满足以下条件才能顺利运行：

{
  "build": {
    "mac": {
      "identity": "Developer ID Application: Your Company",
      "entitlements": "./entitlements.mac.plist",
      "entitlementsInherit": "./entitlements.mac.plist",
      "hardenedRuntime": true
    }
  }
}

entitlements.mac.plist 示例：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
  </dict>
</plist>

⚠️ 注意：启用 hardenedRuntime 后，某些 Node.js 插件（如 ffi-napi ）可能因内存执行被禁用而崩溃，需添加相应权限白名单。

公证（Notarization）流程：

构建后自动提交至 Apple 服务器：
json "afterSign": "notarize.js"
使用 notarytool 提交 .dmg 文件；
Apple 扫描病毒并返回 UUID；
调用 stapler staple 将公证票据嵌入应用。

✅ 最终效果：用户首次打开时不出现红色警告框，提升信任度。

3.4 版本语义化管理与发布流程规范

良好的版本管理是持续交付的基础。 electron-builder 与 semver 规范紧密结合，支持自动化版本递增与发布脚本集成。

3.4.1 使用 semver 规范控制版本号递增

遵循 MAJOR.MINOR.PATCH 格式：

1.0.0 : 初始正式版；
1.1.0 : 新功能发布；
1.1.1 : Bug 修复补丁。

{
  "version": "1.1.1",
  "scripts": {
    "release:patch": "npm version patch && npm run build",
    "release:minor": "npm version minor && npm run build",
    "release:major": "npm version major && npm run build"
  }
}

每次 npm version 执行都会：
- 更新 package.json 中的 version 字段；
- 创建 Git tag（如 v1.1.1 ）；
- 触发 preversion/version/postversion 钩子。

3.4.2 构建后自动上传至 electron-autoupdate-server 的脚本编写

利用 afterAllArtifactBuild 钩子实现构建完成后自动上传：

// after-all-artifact-build.js
module.exports = async (context) => {
  const { appOutDir, packager } = context;
  const files = context.artifactPaths; // 所有生成的文件路径

  const upload = require('upload-client');
  const client = new upload.HttpUpload({
    url: 'https://updates.yourdomain.com/upload',
    files,
    headers: {
      Authorization: `Bearer ${process.env.UPLOAD_TOKEN}`
    }
  });

  await client.upload();
  console.log('✅ 所有文件已上传至更新服务器');
};

集成方式：

{
  "build": {
    "afterAllArtifactBuild": "./after-all-artifact-build.js"
  }
}

🔄 自动化建议：在 GitHub Actions 或 Jenkins 中设置 SECRET UPLOAD_TOKEN ，确保只有 CI 环境才能触发发布。

完整发布流程图（mermaid）：

graph LR
    A[修改代码] --> B[提交 PR]
    B --> C{CI 触发}
    C --> D[运行单元测试]
    D --> E[构建各平台包]
    E --> F[生成元数据 latest.yml/json]
    F --> G[执行 afterAllArtifactBuild]
    G --> H[上传至 electron-autoupdate-server]
    H --> I[通知运维上线]

该流程实现了从代码变更到更新服务就绪的端到端自动化，极大提升了发布效率与一致性。

4. electron-updater 客户端集成与事件监听

在 Electron 应用中实现自动更新功能，核心在于 electron-updater 模块的正确引入与深度控制。不同于原始的 autoUpdater （来自 electron 主模块）， electron-updater 是由 electron-builder 提供的一套更强大、跨平台兼容性更强的更新解决方案。它不仅支持 Windows 上基于 Squirrel.Windows 的安装器机制，还兼容 macOS 的 Sparkle 框架，并为 Linux 平台提供 AppImage 等格式的增量更新能力。本章节将系统讲解如何在主进程中安全地初始化 electron-updater ，精确监听各个更新生命周期事件，处理不同操作系统的行为差异，并通过封装抽象提升代码复用性和可维护性。

4.1 electron-updater 模块引入与初始化配置

4.1.1 替代默认 autoUpdater 的正确方式

Electron 原生提供了 autoUpdater 模块用于触发自动更新流程，但其在跨平台支持上存在明显短板——尤其是在 Windows 和 macOS 上依赖外部工具链且缺乏统一接口。因此，在使用 electron-builder 构建应用时，推荐完全替换原生模块，采用 electron-updater 实现标准化更新逻辑。

要启用 electron-updater ，首先需确保已安装 electron-builder 及其相关依赖：

npm install electron-updater --save

随后，在主进程入口文件（通常是 main.js 或 electron-main.js ）中进行导入和条件判断，避免在开发环境下误触更新请求：

const { app, dialog } = require('electron');
const { autoUpdater } = require('electron-updater');

// 仅在生产环境启用更新检查
if (app.isPackaged) {
  autoUpdater.logger = require('electron-log');
  autoUpdater.logger.transports.file.level = 'info';
}

上述代码中，我们通过 app.isPackaged 判断当前是否为打包后的生产环境。若处于开发模式，则跳过更新逻辑以防止干扰调试过程。此外， electron-log 被指定为日志输出工具，便于后续追踪更新行为。

配置项	说明
`autoUpdater.logger`	设置自定义日志记录器，用于捕获更新过程中的详细信息
`transports.file.level`	控制日志写入级别， `'info'` 表示记录常规操作， `'debug'` 更适合排查问题

graph TD
    A[启动 Electron 应用] --> B{isPackaged?}
    B -- false --> C[跳过更新初始化]
    B -- true --> D[设置 electron-updater 日志器]
    D --> E[准备 updateURL]
    E --> F[监听更新事件]

该流程图清晰展示了初始化阶段的关键决策路径：只有当应用被打包后才会进入更新配置流程，从而保障开发体验不受影响。

参数说明与逻辑分析

app.isPackaged ：这是 Electron 内置属性，返回布尔值，表示当前运行的应用是否经过打包（如使用 asar 打包或构建为 .exe/.dmg）。这是防止开发者本地运行时发起无效更新请求的核心判断。
electron-log ：这是一个强大的日志库，支持多传输通道（控制台、文件、远程等）。将其赋给 autoUpdater.logger 后，所有更新相关的网络请求、版本比对结果、错误堆栈都将被持久化记录，极大提升了线上问题排查效率。

注意：不要直接使用 console.log 来替代日志系统，因为在某些系统权限限制下，标准输出可能无法被捕获或保存。

4.1.2 设置 updateURL 并动态加载服务器元数据

electron-updater 依赖一个远程 HTTP/HTTPS 接口来获取最新的版本信息（即 latest.yml 或 latest-mac.json 文件）。这个地址必须通过 setFeedURL() 方法显式设置，否则更新机制不会生效。

假设你的 electron-autoupdate-server 部署在 https://updates.yourapp.com ，并且支持路径 /update/{platform}/{arch}/{version} ，则可以如下配置：

const serverUrl = 'https://updates.yourapp.com/update';
const platform = process.platform; // 'win32', 'darwin', 'linux'
const arch = process.arch;         // 'x64', 'arm64'
const currentVersion = app.getVersion();

autoUpdater.setFeedURL({
  provider: 'generic',
  url: `${serverUrl}/${platform}/${arch}/${currentVersion}`,
  channel: 'stable' // 可选：支持 beta、latest 等渠道
});

此配置告诉 electron-updater ：

使用通用 HTTP 提供者（ generic ），适用于大多数自建更新服务器；
构造请求 URL，包含平台、架构和当前版本号，以便服务端精准返回匹配的更新元数据；
指定发布频道，可用于灰度发布或 A/B 测试。

请求结构与响应解析机制

当调用 autoUpdater.checkForUpdates() 时，客户端会向指定 URL 发起 GET 请求，例如：

GET /update/darwin/x64/1.2.0 HTTP/1.1
Host: updates.yourapp.com
User-Agent: YourApp/1.2.0 (darwin; x64)
Accept: application/json

服务端应返回符合 latest.yml 格式的响应体（macOS 示例）：

{
  "version": "1.3.0",
  "releaseDate": "2025-04-05T08:00:00.000Z",
  "url": "https://updates.yourapp.com/download/v1.3.0/YourApp-1.3.0.dmg",
  "sha512": "base64-encoded-checksum-here=="
}

字段	类型	说明
`version`	string	最新可用版本号（semver 格式）
`releaseDate`	ISO8601 时间字符串	版本发布时间，用于 UI 显示
`url`	string	完整安装包下载地址
`sha512`	string	文件内容哈希值，用于完整性校验

一旦收到响应， electron-updater 将执行以下逻辑：
1. 解析 JSON/YAML 数据；
2. 比较 version 是否高于本地版本；
3. 若更高，则触发 update-available 事件；
4. 否则触发 update-not-available 。

autoUpdater.on('update-available', (info) => {
  console.log(`发现新版本: ${info.version}`);
  // 可在此处弹窗提示用户
});

这种设计实现了“松耦合”的更新架构：客户端只需知道基础 URL 模板，具体版本映射由服务端决定，便于后期灵活调整发布策略。

4.2 更新生命周期事件监听与用户交互设计

4.2.1 监听 checking-for-update、update-available、update-downloaded 等关键事件

electron-updater 提供了一组细粒度的事件钩子，允许开发者全面掌控更新流程。以下是最重要的几个事件及其用途：

事件名	触发时机	典型用途
`checking-for-update`	开始检查更新时	显示“正在检查更新…”提示
`update-available`	检测到新版本	提示用户并准备下载
`update-not-available`	当前已是最新版	通知用户“已是最新版本”
`error`	更新过程中发生异常	记录错误并提示重试
`download-progress`	下载过程中定期触发	更新进度条和预估时间
`update-downloaded`	下载完成，等待安装	弹出重启提示

完整监听示例：

autoUpdater.on('checking-for-update', () => {
  sendStatusToWindow('正在检查更新...');
});

autoUpdater.on('update-available', (info) => {
  sendStatusToWindow(`发现新版本 ${info.version}，开始下载...`);
});

autoUpdater.on('update-not-available', (info) => {
  sendStatusToWindow(`当前版本 ${info.version} 已是最新`);
});

autoUpdater.on('error', (err) => {
  sendStatusToWindow(`更新出错: ${err.message}`);
});

autoUpdater.on('download-progress', (progressObj) => {
  const percent = Math.round(progressObj.percent);
  const speed = (progressObj.bytesPerSecond / 1024).toFixed(2) + ' KB/s';
  sendStatusToWindow(`下载进度: ${percent}% (${speed})`);
});

autoUpdater.on('update-downloaded', (info) => {
  dialog.showMessageBox({
    type: 'question',
    title: '更新已准备好',
    message: `版本 ${info.version} 已下载完毕，是否立即重启应用？`,
    buttons: ['稍后', '立即重启'],
    cancelId: 0,
    defaultId: 1
  }).then(result => {
    if (result.response === 1) {
      autoUpdater.quitAndInstall();
    }
  });
});

逐行逻辑解读

sendStatusToWindow() ：自定义函数，通常通过 IPC 将状态发送至渲染进程，实现 UI 展示。
dialog.showMessageBox() ：调用原生对话框，提供更可信的操作确认。
autoUpdater.quitAndInstall() ：退出当前应用并启动安装程序（Windows 下执行 .exe ，macOS 替换 Bundle）。

这些事件构成了完整的更新状态机，如下所示：

stateDiagram-v2
    [*] --> Idle
    Idle --> Checking: checkForUpdates()
    Checking --> UpdateAvailable: found newer version
    Checking --> NotAvailable: no update
    UpdateAvailable --> Downloading: start download
    Downloading --> Downloaded: completed
    Downloaded --> Installed: user confirms restart
    Installed --> [*]
    note right of Downloading
      emit download-progress every ~500ms
    end note

该状态图揭示了从检测到安装的完整流转路径，每个节点均可绑定 UI 反馈动作。

4.2.2 实现进度条展示下载状态与预估剩余时间

用户体验的关键之一是可视化反馈。对于大体积应用（如超过 100MB），用户需要明确知道“还要等多久”。

利用 download-progress 事件携带的 progressObj 对象，我们可以实时计算下载速度与预计剩余时间：

let startTime;

autoUpdater.on('download-progress', (progressObj) => {
  if (!startTime) startTime = Date.now();

  const downloadedMB = (progressObj.transferred / 1024 / 1024).toFixed(2);
  const totalMB = (progressObj.total / 1024 / 1024).toFixed(2);
  const speedKBps = (progressObj.bytesPerSecond / 1024).toFixed(2);

  const elapsedSecs = (Date.now() - startTime) / 1000;
  const estimatedTotalSecs = progressObj.total / (progressObj.bytesPerSecond || 1);
  const remainingSecs = Math.max(0, estimatedTotalSecs - elapsedSecs);
  const eta = new Date(Date.now() + remainingSecs * 1000).toLocaleTimeString();

  const payload = {
    percent: progressObj.percent,
    speed: `${speedKBps} KB/s`,
    eta: remainingSecs > 0 ? `约 ${Math.ceil(remainingSecs)} 秒后完成` : '即将完成'
  };

  mainWindow.webContents.send('update-progress', payload);
});

参数说明

transferred : 已下载字节数；
total : 总大小字节数；
bytesPerSecond : 实时带宽速率；
percent : 百分比数值（浮点型）；

渲染进程中接收消息并更新 UI（React 示例）：

useEffect(() => {
  window.electron.ipcRenderer.on('update-progress', (payload) => {
    setProgress(payload.percent);
    setSpeed(payload.speed);
    setEta(payload.eta);
  });
}, []);

结合 HTML <progress> 或第三方组件（如 Ant Design 的 Progress），即可实现专业级下载面板。

4.2.3 强制更新与可选更新模式的 UI 切换逻辑

某些重大安全补丁或协议变更要求用户必须升级。此时应关闭“忽略”选项，强制进入更新流程。

可通过服务端返回的元数据扩展字段实现策略控制：

{
  "version": "1.5.0",
  "url": "...",
  "sha512": "...",
  "mandatory": true,
  "minRequiredVersion": "1.4.0"
}

客户端解析后调整行为：

autoUpdater.on('update-available', (info) => {
  const isMandatory = info.mandatory ?? false;

  if (isMandatory) {
    // 禁止取消，隐藏“稍后”按钮
    dialog.showMessageBox({
      type: 'warning',
      title: '重要更新',
      message: `必须升级至 ${info.version} 以继续使用`,
      buttons: ['确定'],
      noLink: true
    });
  } else {
    // 正常可选流程
  }
});

同时可在设置界面增加开关，让用户选择是否接收 beta 版本：

function switchUpdateChannel(channel) {
  const feedUrl = `https://updates.yourapp.com/update/${process.platform}/${process.arch}/${app.getVersion()}?channel=${channel}`;
  autoUpdater.setFeedURL({ provider: 'generic', url: feedUrl });
}

4.3 跨平台行为差异处理与兼容性优化

4.3.1 Windows 上静默安装与重启控制

Windows 平台使用 Squirrel.Windows 作为底层更新引擎。其特点是安装过程无需管理员权限（除非修改注册表项），但在重启时需调用 Update.exe --processStart 来恢复应用。

常见问题是：调用 quitAndInstall() 后应用未真正重启。原因包括：

安装程序尚未释放锁；
防病毒软件拦截了 .tmp 文件执行；
用户快速双击旧图标导致冲突。

解决方案：

autoUpdater.quitAndInstall(false, true); // quitAndInstall(relaunch, installArgs)

参数说明：

参数	类型	含义
`relaunch`	boolean	是否立即重新启动应用
`installArgs`	boolean/string/array	传递给安装程序的额外参数

建议始终传入 true 作为第二个参数，确保安装完成后自动拉起新版本。

4.3.2 macOS 上权限请求与应用程序终止策略

macOS 对应用自我替换有严格沙箱限制。 electron-updater 使用 Squirrel.Mac 工具进行静默更新，但仍需注意以下几点：

应用必须签名并启用 Hardened Runtime；
不得在 .app 外部存放可执行文件；
更新期间不得阻止 NSApplicationWillTerminateNotification 。

可通过监听即将关闭的通知提前清理资源：

// 在 main.m 中（或通过 node-ffi）
[[NSNotificationCenter defaultCenter] 
   addObserver:self 
   selector:@selector(appWillTerminate:) 
   name:NSApplicationWillTerminateNotification 
   object:nil];

Node.js 层也可监听：

app.on('before-quit', () => {
  console.log('应用将在更新前退出');
});

4.4 自定义更新逻辑封装与模块复用

4.4.1 封装 UpdaterManager 类统一管理更新流程

为提高代码组织性，建议将更新逻辑封装为独立类：

class UpdaterManager {
  constructor(mainWindow) {
    this.mainWindow = mainWindow;
    this.initializeUpdater();
  }

  initializeUpdater() {
    autoUpdater.logger = require('electron-log');
    autoUpdater.autoDownload = false; // 手动控制下载时机

    autoUpdater.on('update-available', () => {
      this.mainWindow.webContents.send('update-mode', 'available');
    });

    autoUpdater.on('update-downloaded', () => {
      this.mainWindow.webContents.send('update-mode', 'ready');
    });
  }

  checkForUpdates() {
    try {
      autoUpdater.checkForUpdates();
    } catch (err) {
      this.mainWindow.webContents.send('update-error', err.message);
    }
  }

  downloadUpdate() {
    autoUpdater.downloadUpdate();
  }

  installAndUpdate() {
    autoUpdater.quitAndInstall();
  }
}

module.exports = UpdaterManager;

主进程导入：

const UpdaterManager = require('./updater-manager');
const updater = new UpdaterManager(mainWindow);

4.4.2 结合 IPC 通信实现渲染进程状态同步

通过 ipcMain 和 ipcRenderer 实现双向通信：

// main.js
ipcMain.on('check-for-update', () => updater.checkForUpdates());
ipcMain.on('download-update', () => updater.downloadUpdate());

// renderer.js
window.electron.ipcRenderer.send('check-for-update');
window.electron.ipcRenderer.on('update-mode', (mode) => {
  // mode: 'available', 'ready', 'progress'
});

最终形成一个高内聚、低耦合的更新管理体系，适用于大型 Electron 项目长期演进。

5. 版本信息管理与更新 API 使用

在 Electron 桌面应用的自动更新体系中，版本信息的精确管理和更新接口的合理设计是实现高效、安全升级的关键环节。客户端能否正确识别新版本、服务端是否能精准返回适配的更新包，完全依赖于一套结构清晰、语义明确的元数据系统和 RESTful 接口协议。本章深入探讨 latest.yml 和 latest-mac.json 等核心元数据文件的组成逻辑，解析增量更新机制背后的差分补丁生成原理，并详细说明如何通过标准化 API 实现跨平台版本查询与响应控制。进一步地，还将介绍灰度发布与版本回滚策略的技术落地方式，为构建高可用、可调控的更新系统提供完整方案。

5.1 更新元数据格式解析与生成机制

Electron 应用的自动更新流程始于对远程服务器上“最新版本”元数据的获取。这些元数据以特定格式存储在静态资源目录中，通常命名为 latest.yml （Windows）或 latest-mac.json （macOS），由 electron-builder 在打包时自动生成并上传至指定服务器路径。理解其内部结构对于排查更新失败、验证签名完整性以及定制化发布逻辑至关重要。

5.1.1 latest.yml / latest-mac.json 文件结构详解

以 Windows 平台为例， latest.yml 是一个 YAML 格式的清单文件，包含当前稳定版的所有关键信息。以下是一个典型的 latest.yml 示例：

version: 2.3.1
files:
  - url: ExampleApp-2.3.1.exe
    size: 104857600
    sha512: NjFmYzJlNGEwMjUxZDkxNmIyNTBlNjUwYzA3MDAxMWVhZDkxZTc1YjQ1ODgwZjM3NjhiZjBjZjA5ZTA2ZTk2Yg==
    blockMapSize: 12345
path: ExampleApp-2.3.1.exe
sha512: NjFmYzJlNGEwMjUxZDkxNmIyNTBlNjUwYzA3MDAxMWVhZDkxZTc1YjQ1ODgwZjM3NjhiZjBjZjA5ZTA2ZTk2Yg==
releaseDate: '2025-04-03T10:20:00.000Z'

该文件主要字段含义如下表所示：

字段名	类型	描述
`version`	string	当前发布的语义化版本号，用于与本地版本比对
`files`	array	包含所有可下载文件的信息列表，支持多架构/语言包
`url`	string	相对于更新服务器根路径的下载地址
`size`	number	文件大小（字节），用于进度条预估和空间检测
`sha512`	string	Base64 编码的 SHA-512 哈希值，用于校验文件完整性
`blockMapSize`	number	差分更新所需的 block map 大小（仅 delta 包需要）
`path`	string	主安装程序路径，传统 NSIS 安装器使用
`releaseDate`	ISO date	发布时间戳，可用于判断更新时效性

而对于 macOS 平台， latest-mac.json 则采用 JSON 格式，结构略有不同：

{
  "name": "ExampleApp",
  "version": "2.3.1",
  "releaseDate": "2025-04-03T10:20:00.000Z",
  "url": "ExampleApp-2.3.1.dmg",
  "sha512": "NjFmYzJlNGEwMjUxZDkxNmIyNTBlNjUwYzA3MDAxMWVhZDkxZTc1YjQ1ODgwZjM3NjhiZjBjZjA5ZTA2ZTk2Yg=="
}

值得注意的是，macOS 使用 Sparkle 框架进行更新，因此其元数据更简洁，但必须确保 url 可访问且 HTTPS 加密，否则 Gatekeeper 将阻止下载。

为了直观展示两种格式的差异，以下使用 Mermaid 流程图表示客户端请求后元数据解析过程：

graph TD
    A[客户端发起 GET 请求] --> B{平台判断}
    B -->|Windows| C[获取 latest.yml]
    B -->|macOS| D[获取 latest-mac.json]
    C --> E[解析 YAML 结构]
    D --> F[解析 JSON 结构]
    E --> G[提取 version/sha512/url]
    F --> G
    G --> H[与本地版本比较]
    H --> I{有新版本?}
    I -->|是| J[触发下载]
    I -->|否| K[保持当前版本]

此流程体现了 Electron-updater 如何根据平台动态选择元数据源，并统一抽象为内部对象模型进行处理。

5.1.2 文件哈希值、大小、下载地址字段意义

元数据中的每一个字段都承担着实际功能职责，尤其在安全性与稳定性方面起决定作用。

sha512 字段 是防止中间人攻击的核心保障。当客户端下载完更新包后，会重新计算本地文件的 SHA-512 哈希并与元数据中的值比对。若不一致，则终止安装并抛出错误。以下是 Node.js 中模拟校验逻辑的代码示例：

const crypto = require('crypto');
const fs = require('fs');

function verifyFileIntegrity(filePath, expectedSha512Base64) {
  return new Promise((resolve, reject) => {
    const hash = crypto.createHash('sha512');
    const stream = fs.createReadStream(filePath);

    stream.on('data', (chunk) => {
      hash.update(chunk);
    });

    stream.on('end', () => {
      const computedHash = hash.digest('base64');
      if (computedHash === expectedSha512Base64) {
        resolve(true);
      } else {
        reject(new Error(`哈希校验失败: 期望=${expectedSha512Base64}, 实际=${computedHash}`));
      }
    });

    stream.on('error', reject);
  });
}

// 调用示例
verifyFileIntegrity('./downloads/app-update.exe', 'NjFmYzJlNGEwMjUxZDkxNmIyNTBlNjUwYzA3MDAxMWVhZDkxZTc1YjQ1ODgwZjM3NjhiZjBjZjA5ZTA2ZTk2Yg==')
  .then(() => console.log('✅ 文件完整'))
  .catch(err => console.error('❌', err.message));

逐行解读分析：

第 1–2 行：引入加密模块 crypto 和文件系统模块 fs 。

第 4 行：定义异步函数 verifyFileIntegrity ，接收文件路径和预期 Base64 编码的 SHA-512 值。

第 6 行：创建 SHA-512 哈希实例。

第 7 行：创建可读流读取大文件，避免内存溢出。

第 9–10 行：每当流读取到数据块时，将其送入哈希算法累加计算。

第 13–18 行：流结束时完成哈希摘要，转换为 Base64 格式并与传入值对比。

第 19–21 行：匹配则成功，否则拒绝 Promise 并携带错误信息。

第 25–28 行：调用测试，输出校验结果。

该机制确保即使攻击者篡改了更新包内容，也无法绕过校验。

size 字段 的作用体现在用户体验层面。在下载过程中，前端可通过 (已下载字节数 / totalSize) * 100 计算百分比进度。此外，在启动下载前还可检查磁盘剩余空间是否足够，避免中途失败。

url 字段 必须为相对路径或完整 HTTPS URL。建议部署时使用 CDN 或反向代理统一前缀，如 /updates/win/ExampleApp-2.3.1.exe ，便于后续迁移和负载均衡。

下表总结了常见字段的应用场景：

字段	安全用途	性能用途	用户体验用途
`sha512`	防止恶意篡改	——	提升信任感
`size`	——	断点续传偏移量计算	进度条渲染、预估剩余时间
`url`	配合 HTTPS 防止劫持	支持 CDN 分发加速	明确更新来源
`releaseDate`	版本生命周期管理	决定是否强制更新	显示“已于 X 天前发布”提示

综上所述，元数据不仅是版本描述工具，更是整个自动更新链路的安全锚点和技术基础。任何字段缺失或错误都将导致更新中断或安全隐患，因此必须由构建系统严格保证其准确性。

5.2 增量更新与差分补丁（delta update）支持

面对频繁迭代的应用，全量更新会导致大量带宽浪费和用户等待时间增加。为此，Electron 生态引入了基于 Squirrel 框架的增量更新机制——即只下载两个版本之间的差异部分（称为 delta 包），从而显著降低传输体积。

5.2.1 electron-builder 自动生成差分包条件分析

electron-builder 支持自动生成 .blockmap 文件和 delta 包，但前提是满足以下条件：

启用 publish 配置并连接远程服务器
上次发布版本的元数据仍可访问
当前构建基于相同的 target（如 NSIS）
启用了 generateUpdatesFilesForAllChannels: true

在 package.json 中配置如下：

{
  "build": {
    "publish": [
      {
        "provider": "generic",
        "url": "https://updates.example.com"
      }
    ],
    "win": {
      "target": "nsis",
      "generateUpdatesFilesForAllChannels": true
    }
  }
}

执行 electron-builder --publish always 后，除了生成 ExampleApp-2.3.1.exe ，还会额外输出：

ExampleApp-2.3.1.exe.blockmap ：记录原文件各数据块哈希的索引文件
ExampleApp-2.3.0-to-2.3.1-full.nupkg ：从 2.3.0 升级到 2.3.1 的完整差分包（Windows）
ExampleApp-2.3.0-to-2.3.1-delta.yml ：描述 delta 包的元数据

其中 .blockmap 文件是核心，它将原始安装包切分为多个固定大小的数据块（默认 ~1MB），并对每个块计算 SHA-256 哈希，结构如下（简化版）：

{
  "size": 104857600,
  "blocks": [
    "sha256-of-chunk-1",
    "sha256-of-chunk-2",
    ...
  ]
}

客户端在检查更新时，首先下载新版本的 .blockmap ，然后与本地旧版本的 .blockmap 对比，仅需下载内容发生变化的数据块，最终在本地拼接成完整的更新包。

5.2.2 服务端如何判断并返回最优更新包类型

服务端需具备智能路由能力，根据客户端上报的当前版本决定返回 full 包还是 delta 包。这通常通过扩展 /update 接口实现。

假设客户端请求如下：

GET /update/win/2.3.0 HTTP/1.1
User-Agent: MyApp/2.3.0

服务端收到后执行以下逻辑：

app.get('/update/:platform/:currentVersion', (req, res) => {
  const { platform, currentVersion } = req.params;
  const userAgent = req.headers['user-agent'];
  const match = userAgent.match(/MyApp\/([\d.]+)/);
  const clientVersion = match ? match[1] : currentVersion;

  const latestRelease = getLatestRelease(platform); // 获取最新版本元数据

  if (semver.lt(clientVersion, latestRelease.version)) {
    const deltaPackage = findDeltaPackage(platform, clientVersion, latestRelease.version);
    if (deltaPackage && shouldUseDeltaUpdate(req.connection.remoteAddress)) {
      res.setHeader('Content-Type', 'application/yaml');
      return res.sendFile(deltaPackage.path); // 返回 delta.yml
    }

    // 否则返回 full 包信息
    res.setHeader('Content-Type', 'application/yaml');
    res.sendFile(path.join(RELEASES_DIR, platform, 'latest.yml'));
  } else {
    res.status(304).send('No updates available');
  }
});

参数说明：

:platform : 动态路由参数，表示操作系统类型（win/mac/linux）

:currentVersion : 客户端声明的当前版本号

User-Agent : 用于双重验证真实版本，防止伪造请求

findDeltaPackage() : 查询是否存在从 A→B 的差分包

shouldUseDeltaUpdate() : 可基于 IP 地域、网络质量等策略控制是否启用 delta

该机制大幅提升了更新效率。实验数据显示，一次 100MB 的全量更新在版本变化较小时，delta 包可能仅为 10~20MB，节省高达 80% 带宽。

下表对比 full 与 delta 更新特性：

特性	Full Update	Delta Update
下载体积	大（完整安装包）	小（仅变更部分）
生成条件	总是可生成	需要前一版本存在且可达
构建耗时	正常	更长（需比对 blockmap）
安装复杂度	简单	需本地重组
网络容忍性	弱（断网需重下）	支持断点续传
适用场景	首次安装、大版本跳跃	小版本迭代、日常热更

结合 Mermaid 图展示差分更新工作流：

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: GET /update/win/2.3.0
    Server->>Client: 返回 latest.yml (v2.3.1)
    Client->>Server: 下载 v2.3.1.blockmap
    Client->>Client: 对比本地 v2.3.0.blockmap
    Client->>Server: 仅请求变更块 range=[start,end]
    Server-->>Client: 返回 partial content
    Client->>Client: 拼接生成完整 installer.exe
    Client->>Client: 开始安装

由此可见，增量更新不仅优化了网络开销，也增强了系统的弹性与可持续性。

5.3 RESTful 更新接口设计与调用流程

标准的更新接口是连接客户端与服务端的桥梁。遵循 RESTful 设计原则，能够提升接口可维护性和跨平台兼容性。

5.3.1 GET /update/:platform/:version 接口职责与响应内容

该接口是自动更新系统的核心入口点，负责响应客户端的版本查询请求。其设计应满足幂等性、无状态性和缓存友好性。

接口定义

Method : GET
Path : /update/:platform/:version
Headers :
Accept: application/yaml , application/json
User-Agent: MyApp/2.3.0 (Windows)
Response Codes :
200 OK : 存在新版本，返回更新元数据
304 Not Modified : 当前已是最新版
404 Not Found : 平台或版本无效
500 Internal Error : 服务异常

示例响应（Windows）

HTTP/1.1 200 OK
Content-Type: application/yaml
Cache-Control: max-age=300
Last-Modified: Wed, 03 Apr 2025 10:20:00 GMT

version: 2.3.1
files:
  - url: ExampleApp-2.3.1.exe
    size: 104857600
    sha512: NjFmYzJlNGEwMjUxZDkxNmIyNTBlNjUwYzA3MDAxMWVhZDkxZTc1YjQ1ODgwZjM3NjhiZjBjZjA5ZTA2ZTk2Yg==
path: ExampleApp-2.3.1.exe
releaseDate: '2025-04-03T10:20:00.000Z'

服务端实现时应注意：
- 使用 If-Modified-Since 头支持 304 缓存
- 对 :platform 做白名单校验（如 win, mac, linux）
- 对 :version 做 semver 解析，避免注入风险

5.3.2 客户端发起请求时携带 User-Agent 识别机制

客户端应在请求头中设置自定义 User-Agent，以便服务端识别应用名称、版本、平台等信息，用于日志追踪和灰度控制。

const { autoUpdater } = require('electron-updater');

autoUpdater.requestHeaders = {
  'User-Agent': `MySecureApp/${app.getVersion()} (${process.platform})`,
};

autoUpdater.setFeedURL({
  provider: 'generic',
  url: 'https://updates.example.com',
});

服务端解析示例：

function parseUserAgent(ua) {
  const regex = /([^\s]+)\/([\d.]+)\s*\((\w+)/;
  const match = ua.match(regex);
  if (!match) return null;
  return {
    appName: match[1],
    version: match[2],
    platform: match[3].toLowerCase()
  };
}

此举使得服务端可基于 UA 实现精细化运营，例如：
- 对 beta 渠道用户返回测试版
- 屏蔽低版本客户端访问
- 统计各版本活跃度

5.4 版本回滚与灰度发布策略实施

生产环境中，新版本可能存在未发现的严重 Bug，需快速回滚；同时新产品功能上线前往往需要逐步放量验证。

5.4.1 利用 channel 控制不同用户群获取更新

electron-builder 支持 channel 概念，可在 package.json 中设置：

{
  "build": {
    "publish": [
      {
        "provider": "generic",
        "url": "https://updates.example.com/stable",
        "channel": "stable"
      },
      {
        "provider": "generic",
        "url": "https://updates.example.com/beta",
        "channel": "beta"
      }
    ]
  }
}

客户端初始化时指定渠道：

autoUpdater.channel = app.isInBetaGroup() ? 'beta' : 'stable';
autoUpdater.checkForUpdates();

服务端据此返回对应目录下的 latest.yml ，实现分流。

5.4.2 服务端按比例放量更新版本的实现思路

通过 Redis 记录用户 ID 抽样决定是否推送新版：

function shouldRolloutNewVersion(userId) {
  const hash = crypto.createHash('md5').update(userId).digest('hex');
  const rollRate = 0.1; // 10% 用户可见
  return parseInt(hash.slice(0, 6), 16) / 0xFFFFFF < rollRate;
}

结合数据库标记用户组，即可实现灰度发布闭环。

最终形成灵活可控的发布体系，兼顾稳定性与创新速度。

6. 自动更新流程全流程实战（检测→下载→安装）

6.1 启动阶段触发更新检测的时机选择

在 Electron 应用中，自动更新的最佳触发时机直接影响用户体验和系统资源占用。常见的策略有两种： 应用启动时自动检测 和 用户手动触发检测 。

6.1.1 主进程启动后立即检查 vs 用户主动点击检查

推荐做法是在主进程完成窗口创建后，延迟 2–3 秒发起一次静默更新检查，避免阻塞 UI 渲染：

// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const { autoUpdater } = require('electron-updater');

let mainWindow;

app.on('ready', async () => {
  createWindow();

  // 延迟检查更新，防止影响启动性能
  setTimeout(() => {
    checkForUpdates();
  }, 3000);
});

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1024,
    height: 768,
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true,
      preload: `${__dirname}/preload.js`
    }
  });

  mainWindow.loadFile('index.html');
}

async function checkForUpdates() {
  try {
    await autoUpdater.checkForUpdatesAndNotify();
  } catch (error) {
    console.error('更新检查失败:', error.message);
    // 可通过 IPC 发送错误信息到渲染进程展示提示
  }
}

checkForUpdatesAndNotify() 是 electron-updater 提供的高级封装方法，自动处理“发现更新 → 下载 → 提示安装”全过程，并支持配置是否强制更新。

相比之下，用户主动点击“检查更新”按钮更适合对稳定性要求高的企业级应用：

// preload.js
const { ipcRenderer } = require('electron');

window.checkForUpdate = () => {
  return ipcRenderer.invoke('check-for-update');
};

// renderer process (React/Vue 等前端框架)
document.getElementById('check-update-btn').addEventListener('click', async () => {
  const result = await window.checkForUpdate();
  if (result === 'up-to-date') {
    alert('当前已是最新版本！');
  }
});

6.1.2 网络状态判断与重试机制加入

为提升健壮性，应在发起请求前校验网络连接状态，并设置指数退避重试逻辑：

const { net } = require('electron');

function isOnline() {
  return new Promise(resolve => {
    const request = net.request('https://www.google.com/generate_204');
    request.on('response', response => {
      resolve(response.statusCode === 204);
    });
    request.on('error', () => resolve(false));
    request.end();
  });
}

async function checkWithRetry(maxRetries = 3, delay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    const online = await isOnline();
    if (online) {
      try {
        await autoUpdater.checkForUpdates();
        return;
      } catch (err) {
        console.warn(`第 ${i + 1} 次检查失败`, err);
      }
    }

    if (i < maxRetries - 1) {
      await new Promise(r => setTimeout(r, delay * Math.pow(2, i))); // 指数退避
    }
  }
  // 通知渲染层网络异常
  mainWindow.webContents.send('update-error', '网络不稳定，无法完成更新检查');
}

触发方式	优点	缺点	适用场景
启动自动检测	用户无感知，及时性强	可能增加冷启动时间	消费类软件、频繁迭代产品
手动按钮触发	控制权交给用户，体验可控	易被忽略导致版本滞后	金融、医疗等高稳定需求系统
定时后台轮询	平衡及时性与性能	复杂度高，需管理定时器	IM 工具、协作平台

6.2 下载过程中的稳定性保障措施

6.2.1 断点续传支持验证与临时文件管理

electron-updater 默认基于 electron-dl 实现下载模块，底层使用 request 库支持 HTTP Range 请求，具备天然断点续传能力。其工作流程如下：

sequenceDiagram
    participant Client as Electron客户端
    participant Server as 更新服务器
    participant FS as 本地文件系统

    Client->>Server: GET /update/win/1.0.0/latest.yml
    Server-->>Client: 返回latest.yml元数据
    Client->>Server: HEAD /download/v1.1.0/MyApp-Setup-1.1.0.exe
    Server-->>Client: Content-Length, Accept-Ranges: bytes
    alt 支持断点续传
        Client->>FS: 查找.tmp临时文件
        FS-->>Client: 存在部分下载数据
        Client->>Server: Range: bytes=1048576-
        Server-->>Client: 返回剩余内容流
        Client->>FS: 追加写入并合并
    else 不支持或首次下载
        Client->>Server: 全量GET请求
        Server-->>Client: 流式传输完整二进制
        Client->>FS: 写入 MyApp-Setup-1.1.0.exe.tmp
    end
    Client->>FS: 重命名为正式安装包

可通过监听下载事件监控进度：

autoUpdater.on('download-progress', (progressObj) => {
  const { bytesPerSecond, percent, transferred, total } = progressObj;
  mainWindow.webContents.send('download-progress', {
    speed: formatBytes(bytesPerSecond) + '/s',
    percent: Math.round(percent),
    eta: calculateETA(transferred, bytesPerSecond)
  });
});

function formatBytes(bytes) {
  if (bytes === 0) return '0 B';
  const k = 1024;
  const sizes = ['B', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}

6.2.2 下载失败后的错误分类与用户提示策略

根据响应码进行精细化错误处理：

HTTP状态码	错误类型	用户提示文案建议
404	版本不存在	“暂无新版本可用”
403	权限拒绝	“您的账户无权获取此更新，请联系管理员”
429	请求过频	“更新请求过于频繁，请稍后再试”
500~599	服务端异常	“更新服务器异常，请稍后重试”
ECONNREFUSED/ECONNRESET	网络中断	“网络连接失败，请检查网络设置”
ENOTFOUND	DNS解析失败	“无法连接至更新服务器”

实现统一错误映射函数：

function mapUpdateError(error) {
  const code = error?.code || error?.statusCode;
  switch (code) {
    case 404:
      return { type: 'no-update', message: '当前版本已最新' };
    case 403:
      return { type: 'forbidden', message: '更新权限受限' };
    case 429:
    case 'TOO_MANY_REQUESTS':
      return { type: 'rate-limit', message: '请求频率过高，请稍后再试' };
    case /ECONN/.test(code):
      return { type: 'network', message: '网络连接异常，请检查网络环境' };
    default:
      return { type: 'unknown', message: '更新过程中发生未知错误' };
  }
}

6.3 安装执行与应用重启控制

6.3.1 Windows 上 installer.exe 执行权限获取

Windows 平台使用 NSIS 安装脚本打包时， autoUpdater.quitAndInstall() 将调用 Squirrel.Windows 的 Update.exe --processStart 命令完成替换：

autoUpdater.on('update-downloaded', () => {
  const dialogOpts = {
    type: 'question',
    buttons: ['现在重启', '稍后'],
    title: '应用更新已完成',
    message: `v${app.getVersion()} 已更新至最新版本，是否立即重启？`
  };

  dialog.showMessageBox(dialogOpts).then(({ response }) => {
    if (response === 0) autoUpdater.quitAndInstall();
  });
});

关键点：
- 必须以管理员权限运行才能覆盖 Program Files 目录下的旧程序。
- 若未获得权限，Squirrel 会尝试 UAC 提权；若失败则抛出 ERROR_ELEVATION_REQUIRED 。

可在构建配置中开启静默提权：

// package.json
"build": {
  "nsis": {
    "oneClick": false,
    "allowElevation": true,
    "perMachine": true
  }
}

6.3.2 macOS 上使用 Squirrel.Mac 进行静默替换

macOS 使用 Sparkle 风格更新机制，通过 Electron Framework 中的 Squirrel.Mac 模块实现：

/Applications/MyApp.app/Contents/Frameworks/Squirrel.framework/Versions/A/Resources/ShipIt \
--user-exit \
--child-path=/Applications/MyApp.app/Contents/MacOS/MyApp \
--reply-channel=...

该进程负责：
- 解压 .dmg 或 .zip 更新包
- 停止原应用（向 Dock 发送 quit 消息）
- 使用 ditto 或 rsync 替换 /Applications/MyApp.app
- 重新启动新版本

注意事项：
- Gatekeeper 要求应用必须经过 Apple 公证（Notarization），否则会被拦截。
- Hardened Runtime 需启用 com.apple.security.cs.disable-library-validation entitlements。

6.4 端到端调试与问题定位技巧

6.4.1 使用 DevTools 查看网络请求与响应头

在主进程中开启开发者工具便于查看更新请求细节：

mainWindow.webContents.openDevTools(); // 开启渲染进程 DevTools

// 在 network 标签页过滤：
// URL 包含 /update 或 /download
// 查看 latest.yml 是否返回正确 version 字段
// 验证 Content-Type 是否为 application/octet-stream

典型成功响应头示例：

HTTP/2 200 OK
Content-Type: application/octet-stream
Content-Length: 75432108
Last-Modified: Wed, 03 Apr 2025 08:23:10 GMT
ETag: "abc123def456"
Cache-Control: no-cache

6.4.2 模拟低版本客户端连接测试更新触发逻辑

可修改 app.getVersion() 模拟旧版本行为：

// 仅用于测试！生产环境禁止硬编码
Object.defineProperty(app, 'getVersion', {
  value: () => '1.0.0'
});

同时在服务端制造差异版本：

# latest.yml
version: 1.2.0
files:
  - url: MyApp-Setup-1.2.0.exe
    size: 75432108
    sha512: base64encodedhash==
path: MyApp-Setup-1.2.0.exe
sha512: base64encodedhash==
releaseDate: '2025-04-03T08:23:10.000Z'

6.4.3 日志追踪从客户端到服务端的完整调用链路

启用详细日志输出：

// main.js
autoUpdater.logger = require('electron-log');
autoUpdater.logger.transports.file.level = 'info';

electron-log 输出路径：
- Windows: %APPDATA%/AppName/logs/main.log
- macOS: ~/Library/Logs/AppName/main.log

常见日志片段分析：

[info] Checking for update
[info] Update available: 1.0.0 → 1.2.0
[info] Downloading update from https://update.example.com/download/v1.2.0/...
[info] Progress: 45%
[info] Update downloaded to /var/folders/.../MyApp-1.2.0-full.nupkg
[info] Install on quit: true
[info] Quitting app to install update...

结合服务端 Nginx 访问日志建立关联 ID 追踪：

log_format trace '$remote_addr - $http_user_agent [$time_local] '
                 '"$request" $status $body_bytes_sent '
                 'req_id=$http_x_request_id';

access_log /var/log/nginx/update.access.log trace;

客户端添加唯一请求标识：

autoUpdater.requestHeaders = {
  'X-Request-ID': generateTraceId(),
  'User-Agent': `MyApp/${app.getVersion()} (${process.platform})`
};

本文还有配套的精品资源，点击获取

开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

使用 vcpkg 将 pngquant 命令行移植到鸿蒙 PC（OpenHarmony ）

开源鸿蒙跨平台开发者社区

为开源鸿蒙跨平台应用全面集成动效能力，提升用户交互体验与流畅度

开源鸿蒙跨平台开发者社区

OpenHarmony签名指南：自动与手动详解

开源鸿蒙跨平台开发者社区

所有评论(0)

查看更多评论

莱财一哥

@weixin_42515392

已为社区贡献17条内容

基于 electron-autoupdate-server 的 Electron 应用自动更新后端搭建与实战

莱财一哥

1. Electron 自动更新机制原理详解

2. electron-autoupdate-server 服务端部署与配置

2.1 服务端环境搭建与依赖安装

2.1.1 Node.js 运行时环境准备与版本选择

2.1.2 npm 包管理与 electron-autoupdate-server 初始化

代码逻辑逐行解读：

2.2 核心配置项解析与自定义设置

2.2.1 存储路径、端口、静态资源目录设定

2.2.2 支持平台（Windows/macOS/Linux）识别规则配置

2.2.3 自动生成更新元数据文件策略

2.3 反向代理与生产级部署方案

2.3.1 Nginx 配置反向代理实现 HTTPS 终端卸载

2.3.2 Docker 容器化部署实践与 CI/CD 集成

2.4 服务健康监测与日志追踪

2.4.1 请求日志记录与客户端行为分析

2.4.2 错误码响应体系与监控告警机制建立

3. electron-builder 打包与自动更新支持

3.1 构建配置中启用自动更新功能

3.1.1 在 package.json 中配置 publish 属性指向更新服务器

代码逻辑分析：

3.1.2 设置发行渠道（stable/beta）与发布路径映射

发布路径映射规则表：

mermaid 流程图：客户端根据 channel 获取更新信息

3.2 多平台打包输出与更新文件生成

3.2.1 Windows 平台 NSIS 安装包与 RELEASES 文件生成

RELEASES 文件内容示例：

自动生成机制说明：

3.2.2 macOS 平台 DMG/ZIP 输出与 Sparkle 兼容性处理

关键参数解释：

更新元数据文件： latest-mac.json

表格：macOS 更新文件对比

3.2.3 Linux 平台 AppImage/Snap 包的更新适配问题

各格式更新机制对比：

3.3 数字签名与完整性校验机制集成

3.3.1 Windows Authenticode 签名流程配置

参数说明：

签名执行流程：

3.3.2 macOS Gatekeeper 兼容性与 hardened runtime 设置

entitlements.mac.plist 示例：

公证（Notarization）流程：

3.4 版本语义化管理与发布流程规范

3.4.1 使用 semver 规范控制版本号递增

3.4.2 构建后自动上传至 electron-autoupdate-server 的脚本编写

集成方式：

完整发布流程图（mermaid）：

4. electron-updater 客户端集成与事件监听

4.1 electron-updater 模块引入与初始化配置

4.1.1 替代默认 autoUpdater 的正确方式

参数说明与逻辑分析

4.1.2 设置 updateURL 并动态加载服务器元数据

请求结构与响应解析机制

4.2 更新生命周期事件监听与用户交互设计

4.2.1 监听 checking-for-update、update-available、update-downloaded 等关键事件

逐行逻辑解读

4.2.2 实现进度条展示下载状态与预估剩余时间

参数说明

4.2.3 强制更新与可选更新模式的 UI 切换逻辑

4.3 跨平台行为差异处理与兼容性优化

4.3.1 Windows 上静默安装与重启控制

4.3.2 macOS 上权限请求与应用程序终止策略

4.4 自定义更新逻辑封装与模块复用

4.4.1 封装 UpdaterManager 类统一管理更新流程

4.4.2 结合 IPC 通信实现渲染进程状态同步

5. 版本信息管理与更新 API 使用

5.1 更新元数据格式解析与生成机制

5.1.1 latest.yml / latest-mac.json 文件结构详解

5.1.2 文件哈希值、大小、下载地址字段意义

5.2 增量更新与差分补丁（delta update）支持

5.2.1 electron-builder 自动生成差分包条件分析

5.2.2 服务端如何判断并返回最优更新包类型

5.3 RESTful 更新接口设计与调用流程

5.3.1 GET /update/:platform/:version 接口职责与响应内容

接口定义

示例响应（Windows）

5.3.2 客户端发起请求时携带 User-Agent 识别机制

5.4 版本回滚与灰度发布策略实施

5.4.1 利用 channel 控制不同用户群获取更新

5.4.2 服务端按比例放量更新版本的实现思路

3.1.1 在 `package.json` 中配置 publish 属性指向更新服务器

更新元数据文件： `latest-mac.json`