electron-release

Electron 发布指南

Codex 兼容性

在 Codex 中运行此技能时，请在执行前将仅适用于 Claude Code 的原语转换为：AskUserQuestion -> chat/request_user_input，TodoWrite -> update_plan，Task/TaskCreate/TeamCreate/SendMessage -> 在可用且获准时使用 spawn_agent/send_input/wait_agent，以及 EnterPlanMode/ExitPlanMode -> 简洁的聊天计划加明确批准。 将 Read/Write/Edit/Bash/WebSearch/WebFetch 对应到 Codex 文件/命令行/网页工具；除非任务明确针对 Claude Code，否则将 ~/.claude/... 路径映射到 ~/.agents/... 或 ~/.codex/...。

Cursor 兼容性

在 Cursor Agent 中运行此技能时，请在执行前将仅适用于 Claude Code 的原语转换为：AskUserQuestion -> AskQuestion；TodoWrite -> Cursor TodoWrite 或等效的清单；Task/TaskCreate/TeamCreate/SendMessage/多 Agent 工作流 -> Cursor Task（子 Agent）、并行 Tasks，或在获准时使用 run_in_background（TeamCreate/SendMessage 可能没有完全对应的功能）；EnterPlanMode/ExitPlanMode -> Plan 模式（SwitchMode / CreatePlan）加明确的用户批准。 通过 Cursor Composer 或 Agent 的对应功能处理 Read/Write/Edit/StrReplace/Bash/网页/搜索/MCP。通常，写作 mcp__server__tool 的 MCP 名称对应配置的服务标识符下的 call_mcp_tool。除非任务明确针对 Claude Code，否则将 ~/.claude/... 映射到 ~/.cursor/skills/、.cursor/skills/ 和 .cursor/rules/。

为支持自动更新的 Electron 应用完成发布工作流。

自动更新验证范围

标准发布流程在验证已发布的资源和 latest-mac.yml 元数据后即结束。不要在此技能中安装或启动旧版应用、触发其更新器、下载更新、重启并进入更新后的版本，也不要测试 ShipIt。只有在用户明确要求，或要求调查已报告的更新故障时，才执行端到端自动更新 QA。

支持的配置

技术栈	平台	构建类型	状态
Vite + electron-builder	macOS	本地	✅ 已记录
其他配置	-	-	📝 待补充

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

# 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..."

完整工作流

阶段 1：发布前

1. 更新版本号，位于 package.json
2. 提交版本号变更：

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

阶段 2：构建

3. 使用公证进行构建：

   APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac
   

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

4. 验证构建输出：

   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 安装程序

阶段 3：准备发布资源

5. 重命名 ZIP 文件（自动更新的关键步骤）：

   # 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"
   

6. 验证 latest-mac.yml 中的 URL 与重命名后的文件相符：

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

阶段 4：GitHub 发布

7. 创建包含所有必需文件的发布版本：

   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
   )"
   

8. 验证发布资源：

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

自动更新所需文件

文件	用途	缺失时的结果
latest-mac.yml	版本号 + SHA512 哈希值	“没有可用更新”
*-arm64-mac.zip	ARM64 更新载荷	M1/M2/M3 上下载失败
*-mac.zip	x64 更新载荷	Intel 上下载失败
*.dmg	手动下载	没有手动安装选项

常见错误

错误	症状	修复方法
只有 DMG，没有 ZIP	自动更新静默失败	上传所有 ZIP 文件
缺少 latest-mac.yml	“没有可用的更新”	上传 latest-mac.yml
ZIP 文件名错误	下载错误	重命名，使其与 latest-mac.yml 中的 URL 相符
未设置公证环境变量	Gatekeeper 阻止应用运行	设置 APPLE_KEYCHAIN_PROFILE
文件名中包含空格	下载时出现 404 错误	重命名：将空格替换为连字符

故障排除

自动更新时出现“下载错误”

# 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

“没有可用的更新”

# Verify latest-mac.yml is uploaded
gh release view vX.Y.Z --json assets --jq '.assets[].name' | grep yml

Gatekeeper 阻止应用运行

# Rebuild with notarization
APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac
# Check build log for "notarization successful"

electron-builder.yml 参考

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

成功标准

• 构建完成，并显示“公证成功”
• 所有 5 个文件均已上传到 GitHub Release
• ZIP 文件名与 latest-mac.yml 中的 URL 完全一致