electron-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Electron Release Guide

Electron应用发布指南

Complete release workflow for Electron applications with auto-update support.

包含自动更新支持的Electron应用完整发布工作流。

Supported Configurations

支持的配置

Stack	Platform	Build Type	Status
Vite + electron-builder	macOS	Local	✅ Documented
Other configurations	-	-	📝 To be added

技术栈	平台	构建类型	状态
Vite + electron-builder	macOS	本地	✅ 已文档化
其他配置	-	-	📝 待添加

Quick Start (macOS + Vite + electron-builder)

快速开始（macOS + Vite + electron-builder）

bash

undefined

bash

undefined

1. Build with notarization

APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac

2. Rename ZIPs (GitHub converts spaces to dots)

cp "dist/App Name-X.Y.Z-arm64-mac.zip" "dist/App-Name-X.Y.Z-arm64-mac.zip" cp "dist/App Name-X.Y.Z-mac.zip" "dist/App-Name-X.Y.Z-mac.zip"

3. Create release with ALL files

gh release create vX.Y.Z
dist/latest-mac.yml
"dist/App-Name-X.Y.Z-arm64-mac.zip"
"dist/App-Name-X.Y.Z-mac.zip"
dist/app-name-X.Y.Z-arm64.dmg
dist/app-name-X.Y.Z-x64.dmg
--title "vX.Y.Z" --notes "Release notes..."

undefined

undefined

Complete Workflow

完整工作流

Phase 1: Pre-Release

阶段1：发布前准备

Update version in
```
package.json
```

Commit version bump:

bash

git add package.json
git commit -m "chore(release): bump version to X.Y.Z"
git push origin main

在
```
package.json
```
中更新版本号

提交版本号更新:

bash

git add package.json
git commit -m "chore(release): bump version to X.Y.Z"
git push origin main

Phase 2: Build

阶段2：构建

Build with notarization:

bash

APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac

Env Var	Purpose
`APPLE_KEYCHAIN_PROFILE`	Keychain profile for notarization
Alternative: `APPLE_ID` , `APPLE_APP_SPECIFIC_PASSWORD` , `APPLE_TEAM_ID`	Direct credentials

Verify build output:

bash

ls -la dist/*.dmg dist/*.zip dist/*.yml

Expected files:

```
latest-mac.yml
```
- Auto-update metadata
```
App Name-X.Y.Z-arm64-mac.zip
```
- ARM64 update payload
```
App Name-X.Y.Z-mac.zip
```
- x64 update payload
```
app-name-X.Y.Z-arm64.dmg
```
- ARM64 installer
```
app-name-X.Y.Z-x64.dmg
```
- x64 installer

带公证的构建:

bash

APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac

环境变量	用途
`APPLE_KEYCHAIN_PROFILE`	用于公证的钥匙串配置文件
替代方案： `APPLE_ID` , `APPLE_APP_SPECIFIC_PASSWORD` , `APPLE_TEAM_ID`	直接凭证

验证构建输出:

bash

ls -la dist/*.dmg dist/*.zip dist/*.yml

预期生成的文件:

```
latest-mac.yml
```
- 自动更新元数据
```
App Name-X.Y.Z-arm64-mac.zip
```
- ARM64更新包
```
App Name-X.Y.Z-mac.zip
```
- x64更新包
```
app-name-X.Y.Z-arm64.dmg
```
- ARM64安装程序
```
app-name-X.Y.Z-x64.dmg
```
- x64安装程序

Phase 3: Prepare Release Assets

阶段3：准备发布资产

Rename ZIP files (critical for auto-update):

bash

# GitHub converts spaces to dots, but latest-mac.yml expects hyphens
cp "dist/App Name-X.Y.Z-arm64-mac.zip" "dist/App-Name-X.Y.Z-arm64-mac.zip"
cp "dist/App Name-X.Y.Z-mac.zip" "dist/App-Name-X.Y.Z-mac.zip"

Verify
latest-mac.yml
URLs match renamed files:

bash

cat dist/latest-mac.yml
# Check that 'url:' entries match your renamed ZIP filenames

重命名ZIP文件（对自动更新至关重要）:

bash

# GitHub converts spaces to dots, but latest-mac.yml expects hyphens
cp "dist/App Name-X.Y.Z-arm64-mac.zip" "dist/App-Name-X.Y.Z-arm64-mac.zip"
cp "dist/App Name-X.Y.Z-mac.zip" "dist/App-Name-X.Y.Z-mac.zip"

验证
latest-mac.yml
中的URL与重命名后的文件匹配:

bash

cat dist/latest-mac.yml
# Check that 'url:' entries match your renamed ZIP filenames

Phase 4: GitHub Release

阶段4：GitHub发布

Create release with all required files:

bash

gh release create vX.Y.Z \
  dist/latest-mac.yml \
  "dist/App-Name-X.Y.Z-arm64-mac.zip" \
  "dist/App-Name-X.Y.Z-mac.zip" \
  dist/app-name-X.Y.Z-arm64.dmg \
  dist/app-name-X.Y.Z-x64.dmg \
  --title "vX.Y.Z" \
  --notes "$(cat <<'EOF'
## What's Changed
- Feature 1
- Bug fix 2
EOF
)"

Verify release assets:

bash

gh release view vX.Y.Z --json assets --jq '.assets[].name'

上传所有必要文件创建发布:

bash

gh release create vX.Y.Z \
  dist/latest-mac.yml \
  "dist/App-Name-X.Y.Z-arm64-mac.zip" \
  "dist/App-Name-X.Y.Z-mac.zip" \
  dist/app-name-X.Y.Z-arm64.dmg \
  dist/app-name-X.Y.Z-x64.dmg \
  --title "vX.Y.Z" \
  --notes "$(cat <<'EOF'
## What's Changed
- Feature 1
- Bug fix 2
EOF
)"

验证发布资产:

bash

gh release view vX.Y.Z --json assets --jq '.assets[].name'

Required Files for Auto-Update

自动更新所需文件

File	Purpose	Missing =
`latest-mac.yml`	Version + SHA512 hashes	"No updates available"
`*-arm64-mac.zip`	ARM64 update payload	Download fails on M1/M2/M3
`*-mac.zip`	x64 update payload	Download fails on Intel
`*.dmg`	Manual download	No manual install option

文件	用途	缺失会导致
`latest-mac.yml`	版本信息 + SHA512哈希	显示“无可用更新”
`*-arm64-mac.zip`	ARM64更新包	M1/M2/M3设备上下载失败
`*-mac.zip`	x64更新包	Intel设备上下载失败
`*.dmg`	手动下载包	无手动安装选项

Common Mistakes

常见错误

Mistake	Symptom	Fix
DMG only, no ZIP	Auto-update silently fails	Upload all ZIP files
Missing `latest-mac.yml`	"No updates available"	Upload `latest-mac.yml`
Wrong ZIP filename	Download error	Rename to match `latest-mac.yml` URLs
No notarization env var	Gatekeeper blocks app	Set `APPLE_KEYCHAIN_PROFILE`
Spaces in filename	404 on download	Rename: spaces → hyphens

错误操作	症状	解决方法
仅上传DMG，未上传ZIP	自动更新静默失败	上传所有ZIP文件
缺失 `latest-mac.yml`	显示“无可用更新”	上传 `latest-mac.yml`
ZIP文件名错误	下载错误	重命名以匹配 `latest-mac.yml` 中的URL
未设置公证环境变量	Gatekeeper阻止应用运行	设置 `APPLE_KEYCHAIN_PROFILE`
文件名包含空格	下载时出现404错误	重命名：空格替换为连字符

Troubleshooting

故障排查

"Download error" on auto-update

自动更新时出现"下载错误"

bash

undefined

bash

undefined

Check if filenames match

cat dist/latest-mac.yml | grep url: gh release view vX.Y.Z --json assets --jq '.assets[].name'

URLs in yml must exactly match asset names

undefined

undefined

"No updates available"

显示“无可用更新”

bash

undefined

bash

undefined

Verify latest-mac.yml is uploaded

gh release view vX.Y.Z --json assets --jq '.assets[].name' | grep yml

undefined

gh release view vX.Y.Z --json assets --jq '.assets[].name' | grep yml

undefined

Gatekeeper blocks app

Gatekeeper阻止应用运行

bash

undefined

bash

undefined

Rebuild with notarization

APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac

Check build log for "notarization successful"

undefined

undefined

electron-builder.yml Reference

electron-builder.yml 参考配置

yaml

mac:
  target:
    - target: dmg
      arch: [arm64, x64]
    - target: zip
      arch: [arm64, x64]
  notarize: true
  hardenedRuntime: true

publish:
  provider: github
  owner: your-org
  repo: your-repo

yaml

mac:
  target:
    - target: dmg
      arch: [arm64, x64]
    - target: zip
      arch: [arm64, x64]
  notarize: true
  hardenedRuntime: true

publish:
  provider: github
  owner: your-org
  repo: your-repo

Success Criteria

成功标准

Build completes with "notarization successful"
All 5 files uploaded to GitHub Release
ZIP filenames match
```
latest-mac.yml
```
URLs exactly
Test: older version detects update
Test: download and install succeeds

构建完成并显示“notarization successful”
所有5个文件已上传至GitHub Release
ZIP文件名与
```
latest-mac.yml
```
中的URL完全匹配
测试：旧版本能检测到更新
测试：下载和安装成功