electron-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Electron Production Build & Release Guide

Electron 生产构建与发布指南

This skill provides enterprise-grade best practices for building, signing, releasing, and distributing Electron applications with emphasis on security, reliability, performance, and user trust.

本Skill提供企业级最佳实践，用于Electron应用的构建、签名、发布和分发，重点关注安全性、可靠性、性能和用户信任。

Quick Reference

快速参考

Build Configuration: For electron-vite production config, bundle optimization, and pre-build checks.
Code Signing: Platform-specific signing for Windows (EV certificates), macOS (Developer ID + notarization), and Linux (GPG).
Auto-Updates: electron-updater configuration, staged rollouts, and update testing.
Release Workflows: GitHub Actions CI/CD pipelines for multi-platform builds.
Distribution: GitHub Releases, Cloudflare R2, or private server hosting.

构建配置：适用于electron-vite生产配置、打包优化和构建前检查。
代码签名：针对不同平台的签名方案：Windows（EV证书）、macOS（Developer ID + 公证）、Linux（GPG）。
自动更新：electron-updater配置、分阶段推送和更新测试。
发布工作流：用于多平台构建的GitHub Actions CI/CD流水线。
分发：GitHub Releases、Cloudflare R2或私有服务器托管。

Core Principles

核心原则

Security First: All production builds must be code-signed; macOS builds must be notarized.
Pre-Build Verification: Always run
```
pnpm audit
```
,
```
pnpm run typecheck
```
,
```
pnpm run lint
```
, and
```
pnpm run test
```
before builds.
Semantic Versioning: Follow SemVer strictly (MAJOR.MINOR.PATCH).
Staged Rollouts: Release to a percentage of users first, then expand gradually.

安全优先：所有生产构建必须完成代码签名；macOS构建必须通过公证。

构建前校验：构建前务必执行

pnpm audit

、

pnpm run typecheck

、

pnpm run lint

和

pnpm run test

。

语义化版本控制：严格遵循SemVer规范（MAJOR.MINOR.PATCH）。
分阶段推送：先向一定比例的用户发布更新，再逐步扩大覆盖范围。

Build Strategy

构建策略

Pre-Build Checklist

构建前检查清单

Before every production build:

Check dependencies for vulnerabilities:
```
pnpm audit
```
Verify code quality:
```
pnpm run typecheck && pnpm run lint
```
Run test suite:
```
pnpm run test && pnpm run test:e2e
```
Check bundle size:
```
pnpm run build:analyzer
```
Verify environment configuration

每次生产构建前需完成以下检查：

检查依赖漏洞：
```
pnpm audit
```
校验代码质量：
```
pnpm run typecheck && pnpm run lint
```
运行测试用例：
```
pnpm run test && pnpm run test:e2e
```
检查打包体积：
```
pnpm run build:analyzer
```
校验环境配置

Production Build Optimization

生产构建优化

Remove all
```
console.log
```
and
```
debugger
```
statements
Tree-shake unused dependencies
Split vendor chunks (React, UI libraries)
Compress images and assets
Lazy load non-critical modules
Disable source maps for distribution (ship separately if needed)
Use production-mode build flags

移除所有
```
console.log
```
和
```
debugger
```
语句
Tree-shake剔除未使用的依赖
拆分第三方依赖 chunk（React、UI库等）
压缩图片和静态资源
懒加载非核心模块
分发版本禁用source map（如有需要可单独提供）
使用生产模式构建标识

Target Bundle Sizes

目标打包体积

Component	Target
Main process	< 2 MB
Renderer	< 5 MB
Total package	< 150 MB
Install size	< 250 MB

组件	目标大小
主进程	< 2 MB
渲染进程	< 5 MB
完整安装包	< 150 MB
安装后体积	< 250 MB

Code Signing

代码签名

Windows (EV Certificate Required)

Windows（需EV证书）

Microsoft requires Extended Validation (EV) certificates since June 2023.

Recommended: Use cloud-based signing (DigiCert KeyLocker or Azure Trusted Signing).

Never use self-signed certificates for distribution.

微软自2023年6月起要求使用扩展验证（EV）证书。

推荐方案：使用云端签名服务（DigiCert KeyLocker或Azure可信签名）。

切勿使用自签名证书用于正式分发。

macOS (Developer ID + Notarization)

macOS（Developer ID + 公证）

Two-step process:

Code Signing: Uses Developer ID Certificate
Notarization: Apple scans for malware (required for distribution)

Key requirements:

```
hardenedRuntime: true
```
in electron-builder config
Valid entitlements.mac.plist
APPLE_TEAM_ID, APPLE_ID, and APPLE_APP_SPECIFIC_PASSWORD environment variables

分为两步流程：

代码签名：使用Developer ID证书签名
公证：苹果扫描恶意代码（正式分发必需步骤）

核心要求：

electron-builder配置中设置
```
hardenedRuntime: true
```
有效的entitlements.mac.plist文件
配置APPLE_TEAM_ID、APPLE_ID和APPLE_APP_SPECIFIC_PASSWORD环境变量

Linux (GPG)

Linux（GPG）

Sign release artifacts with GPG:

bash

gpg --detach-sign -u YOUR_KEY_ID dist/packages/*.AppImage
gpg --detach-sign -u YOUR_KEY_ID dist/packages/*.deb

使用GPG签名发布产物：

bash

gpg --detach-sign -u YOUR_KEY_ID dist/packages/*.AppImage
gpg --detach-sign -u YOUR_KEY_ID dist/packages/*.deb

Auto-Update Implementation

自动更新实现

electron-updater Configuration

electron-updater配置

Configure publish provider in electron-builder.yml:

yaml

publish:
  provider: github
  owner: your-username
  repo: your-repo
  releaseType: release

在electron-builder.yml中配置发布提供商：

yaml

publish:
  provider: github
  owner: your-username
  repo: your-repo
  releaseType: release

Staged Rollout Strategy

分阶段推送策略

Reduce risk by gradually rolling out updates:

Day 1: 10% of users
Day 2: 25% of users
Day 3: 50% of users
Day 4: 100% of users

If issues detected:

Do NOT release same version again (users will ignore update)
Release a higher version (e.g., 1.0.1 -> 1.0.2)
Consider reverting to previous version if critical bug

通过逐步推送更新降低风险：

第1天：推送给10%的用户
第2天：推送给25%的用户
第3天：推送给50%的用户
第4天：全量推送

如果发现问题：

不要重新发布同一个版本（用户会忽略重复更新）
发布更高版本（例如从1.0.1升级到1.0.2）
如遇严重bug可考虑回滚到上一个稳定版本

Testing Auto-Update Locally

本地测试自动更新

Use

dev-app-update.yml

for local testing. Test the full update cycle before releasing.

使用

dev-app-update.yml

进行本地测试，发布前务必测试完整的更新流程。

Release Workflow

发布工作流

Manual Release Checklist

手动发布检查清单

Before creating release tag:

Merge all PRs for this version
Bump version in
```
package.json
```
Update
```
CHANGELOG.md
```
Run full test suite
Run bundle analysis
Test build locally
Verify app starts and basic features work
Test auto-update mechanism

创建发布标签前完成以下检查：

合并当前版本的所有PR
升级
```
package.json
```
中的版本号
更新
```
CHANGELOG.md
```
运行完整测试用例
运行打包体积分析
本地测试构建是否正常
验证应用可正常启动且基础功能可用
测试自动更新机制

Creating a Release

创建发布

bash

git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

GitHub Actions automatically handles:

Building for Windows, macOS, Linux
Code signing
Notarization (macOS)
Creating GitHub Release
Publishing artifacts

bash

git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

GitHub Actions会自动完成以下流程：

构建Windows、macOS、Linux三个平台的安装包
代码签名
macOS公证
创建GitHub Release
上传发布产物

Distribution Options

分发选项

GitHub Releases (Recommended)

GitHub Releases（推荐）

Free and reliable
Built-in auto-update support
Version management
Release notes

免费且稳定可靠
内置自动更新支持
版本管理能力
支持发布说明

Cloudflare R2

S3-compatible storage with R2 endpoint. Configure environment variables:

R2_BUCKET_NAME
R2_ACCOUNT_ID
R2_ACCESS_KEY_ID
R2_SECRET_ACCESS_KEY
UPDATE_FEED_URL

兼容S3的存储服务，支持R2端点，需配置以下环境变量：

R2_BUCKET_NAME
R2_ACCOUNT_ID
R2_ACCESS_KEY_ID
R2_SECRET_ACCESS_KEY
UPDATE_FEED_URL

Private Server (Generic HTTP)

私有服务器（通用HTTP）

Requires serving

latest.yml

latest-mac.yml

, and all artifacts via HTTPS.

需要通过HTTPS提供

latest.yml

、

latest-mac.yml

和所有发布产物的访问。

Security Checklist

安全检查清单

Before release, verify:

Dependencies audited (
```
pnpm audit
```
)
No hardcoded secrets in code
IPC channels validated
CSP properly configured
Context isolation enabled
Node integration disabled in renderer
Sandbox enabled for all windows
Auto-update tested end-to-end
Code signing certificates valid
macOS app notarized
All communications over HTTPS
No sensitive data in logs or error messages

发布前校验以下项：

依赖审计通过（
```
pnpm audit
```
）
代码中无硬编码密钥
IPC通道已校验
CSP已正确配置
上下文隔离已启用
渲染进程中Node集成已禁用
所有窗口已启用沙箱
自动更新全流程测试通过
代码签名证书有效
macOS应用已完成公证
所有通信使用HTTPS协议
日志或错误信息中无敏感数据

Troubleshooting

故障排查

Issue	Solution
Auto-update not triggering	Verify `latest.yml` exists, check GitHub releases config
Code signing fails	Renew certificate, verify fingerprint
Windows SmartScreen warning	Distribute widely, file with Microsoft for reputation
macOS "cannot verify developer"	Re-notarize, check team ID and certificate
Large app download	Analyze with `ANALYZE=true pnpm run build` , enable compression
Blank screen in production	Use relative paths ( `base: './'` ), verify build output

问题	解决方案
自动更新未触发	确认 `latest.yml` 存在，检查GitHub Releases配置
代码签名失败	续费证书，校验证书指纹
Windows SmartScreen警告	扩大分发范围，向微软提交申请提升信誉
macOS提示“无法验证开发者”	重新提交公证，检查团队ID和证书是否有效
应用安装包体积过大	使用 `ANALYZE=true pnpm run build` 分析体积，开启压缩
生产环境打开白屏	使用相对路径（ `base: './'` ），校验构建输出产物

Validation Checklist

验证清单

Before finishing a task involving Electron releases:

Pre-build checks pass (audit, typecheck, lint, test)
Bundle sizes within targets
Code signing configured for all platforms
macOS notarization configured
Auto-update mechanism implemented and tested
Staged rollout strategy defined
Security checklist completed
Release notes prepared

For detailed configuration examples, code samples, and GitHub Actions workflows, refer to

references/patterns.md

完成Electron发布相关任务前确认：

构建前检查全部通过（审计、类型检查、语法检查、测试）
打包体积符合目标要求
所有平台的代码签名已配置
macOS公证已配置
自动更新机制已实现并测试通过
分阶段推送策略已明确
安全检查清单全部完成
发布说明已准备完毕

如需详细配置示例、代码样例和GitHub Actions工作流，请参考

references/patterns.md

。