Electron开发打包踩坑指南

框架选择

electron-vite 、react 、npm

依赖安装相关

安装依赖时一定要分清楚哪些是生产依赖，哪些是开发依赖，只有生产依赖会被打包进 app 包中，如果运行时用到的工具被安装在了开发依赖中，打包后则会造成依赖丢失的问题

私有协议注册

开发配置

踩坑记录:

一开始使用 pnpm 导致 electron 可执行程序是软连地址，导致 setAsDefaultProtocolClient 的 execPath 参数不生效，私有协议无法唤器 应用

• 主线程入口文件进行协议注册

• 开发环境需要注册伪协议，通过传递额外参数指定。

• 生产打包需额外在 electron-builder.yml 中添加配置

function setAppProtocol() {
  // 确保单实例和协议处理在应用启动之前设置
  const gotTheLock = app.requestSingleInstanceLock()
  if (!gotTheLock) {
    console.log('Another instance is already running, quitting...')
    // 如果没有获得锁，说明已有实例在运行，退出当前实例
    app.quit()
    return
  }

  console.log('Got single instance lock')

  // 注册自定义协议
  app.removeAsDefaultProtocolClient('yiye')
  const isAlreadyDefault = app.isDefaultProtocolClient('yiye')
  console.log('Is already default protocol client for yiye:', isAlreadyDefault)

  if (!isAlreadyDefault) {
    // 在开发环境中，需要指定可执行文件路径和参数
    if (process.platform === 'darwin' && !app.isPackaged) {
      console.log('Setting protocol client for macOS development with execPath:', process.execPath)
      app.setAsDefaultProtocolClient('yiye', process.execPath, [process.argv[1]])
    } else if (process.platform === 'win32' && !app.isPackaged) {
      app.setAsDefaultProtocolClient('yiye', process.execPath, [process.argv[1]])
    } else {
      console.log('Setting protocol client for production or non-macOS')
      app.setAsDefaultProtocolClient('yiye')
    }
  } else {
    console.log('Already registered as default protocol client')
  }
}

app.whenReady().then(async () => {
  // 设置协议
  setAppProtocol()
})

打包配置 electron-builder.yml

# 自定义协议
protocols:
  - name: yiye
    schemes:
      - yiye

MAC 相关配置

• target 打包产出文件格式：zip、dmg

• identity 参数配置打包签名证书：null 自动选择，false 则不进行签名，[证书 ID] 指定使用特定证书签名

• hardenedRuntime 打包代码完整性保护， 如果要公证必须为 true

• icon 配置 app 图标

appId: com.yiye-ai-studio.app 
productName: 一叶 AI Studio
mac:
  target:
    - target: dmg
      arch: arm64
  identity: false # cerId # 签名证书； 设为 null 为自动选择
  hardenedRuntime: true # 开启公正必须设为 true
  gatekeeperAssess: false # 跳过 Gatekeeper 评估
  icon: build/icon.icns
  entitlements: build/entitlements.mac.plist # 主应用权限
  entitlementsInherit: build/entitlements.mac.plist # 子进程权限
  extendInfo:
    NSCameraUsageDescription: Application requests access to the device's camera.
    NSMicrophoneUsageDescription: Application requests access to the device's microphone.
    NSDocumentsFolderUsageDescription: Application requests access to the user's Documents folder.
    NSDownloadsFolderUsageDescription: Application requests access to the user's Downloads folder.
  notarize: false # 打包完成后使用自定义脚本进行公正
dmg:
  artifactName: ${name}-${arch}-${version}.${ext}

• 自定义公证脚本：使用 @electron/notarize 工具进行公证

import { notarize } from '@electron/notarize'
import path from 'path'

// appPath 为打包产出文件夹内 要公证的 app路径
const appPath = path.join(process.cwd(), 'dist', 'mac-arm64', ${productName})
const appleId = '开发者账号'
const appleIdPassword = 'App 开发专用密码，非 Apple 账号密码'
const teamId = '组织 ID; 个人开发者使用证书 ID '
const appBundleId = 'app ID 即 electron-builder.yml 文件中的 appId'

console.log('=== notarize arm64 start ===')

await notarize({
  appPath,
  appleId,
  appBundleId,
  appleIdPassword,
  teamId
})

console.log('=== notarize arm64 OK ===')

Win 相关配置

• executableName app 名称

• target 打包产出文件格式：zip 、nsis

• artifactName 名称配置

• icon app 图标

win:
  executableName: YiyeAIStudio
  target:
    - target: zip
      arch: x64
  artifactName: ${name}-${arch}-${version}-win.${ext}
  icon: build/icon.ico
  sign: false
nsis:
  oneClick：true # 是否为一键安装（默认 true）
  allowToChangeInstallationDirectory：true # 是否允许用户更改安装目录
  installerIcon：# 安装程序图标
  uninstallerIcon：# 卸载程序图标
  installerHeader：# 安装程序头部图片
  license：# 许可协议文件路径