请求讲解Electron-builder Windows代码签名流程及实操步骤

一、证书基础认知 #

Windows 代码签名分两种：

• 普通代码签名证书：以PFX文件形式发放，需配合密码使用，适合常规发布场景
• EV代码签名证书：多为USB加密狗（dongle）形式，插入后系统自动识别，能快速通过Windows Defender SmartScreen验证，适合企业级发布

二、零成本预验证流程（避免盲目采购证书） #

你可以先通过自签名证书验证electron-builder的签名逻辑是否正常，无需采购正式证书：

1. 生成自签名证书：
   打开PowerShell执行：

   New-SelfSignedCertificate -Type CodeSigningCert -Subject "CN=Test Electron Signing" -CertStoreLocation Cert:\CurrentUser\My
   

2. 配置package.json：
   在现有build配置中添加：

   "build": {
     "win": {
       // 原有target、icon等配置...
       "certificateSubjectName": "CN=Test Electron Signing"
     }
   }
   

3. 执行构建：
   运行项目的构建命令（如npm run build），完成后查看生成的exe属性→数字签名，若能看到签名条目，说明签名流程逻辑正常。

另外，检查项目的.env文件、CI/CD脚本（如GitHub Actions、Jenkins），原同事可能把证书配置放在环境变量中（比如CSC_LINK、CSC_KEY_PASSWORD、WIN_CSC_SUBJECT_NAME），这些是electron-builder默认读取的环境变量。

三、正式证书的配置与签名步骤 #

1. 证书准备 #

• 普通证书：从正规CA（如DigiCert、GlobalSign）购买后，下载PFX格式证书文件并记录密码；可选择导入到本地证书存储（运行certmgr.msc，导入到「个人」目录），或直接保留文件。
• EV证书：收到USB dongle后插入电脑，系统会自动安装驱动；打开certmgr.msc确认证书已在「个人」存储中，复制证书的主题名称（如CN=你的公司名称, O=你的组织名）。

2. Electron-builder 配置 #

推荐用环境变量配置（避免硬编码敏感信息）：

• 普通证书：

  # PowerShell
  $env:CSC_LINK = "D:/certs/your-cert.pfx"
  $env:CSC_KEY_PASSWORD = "你的证书密码"
  

  # 命令提示符
  set CSC_LINK=D:/certs/your-cert.pfx
  set CSC_KEY_PASSWORD=你的证书密码
  

• EV证书：

  $env:WIN_CSC_SUBJECT_NAME = "CN=你的公司主题名称"
  

  配置完成后直接运行构建命令，electron-builder会自动识别证书完成签名。

若要写入package.json（不推荐，密码会暴露）：

"build": {
  "win": {
    // 原有配置...
    // 普通证书配置
    "certificateFile": "path/to/your-cert.pfx",
    "certificatePassword": "your-password",
    // EV证书配置（二选一）
    "certificateSubjectName": "CN=你的公司主题名称"
  }
}

3. 验证签名结果 #

构建完成后，右键生成的exe→属性→数字签名，查看签名的有效性和证书信息。

四、常见问题排查 #

• 找不到证书：检查证书主题名是否完全匹配，或PFX文件路径是否正确
• EV证书签名失败：确认USB dongle已插入、驱动正常，且当前用户有设备访问权限
• 签名后被杀毒软件拦截：自签名证书会触发拦截，正式EV证书可大幅降低此类情况

内容的提问来源于stack exchange，提问作者tklodd