如何用Electron Builder在安装时为Electron30应用注册'tel'协议？

环境与需求回顾 #

• 环境：Electron 30，Electron Builder 25.0.0-alpha.9
• 需求：应用安装时完成tel协议注册，使其出现在系统支持该协议的应用列表中

已尝试操作（用户提供） #

Windows端 #

1. 在Electron Builder配置的win节点及顶层添加协议配置：

protocols: [
  {
    name: 'tel',
    schemes: ['tel'],
  }
]

2. 考虑使用安装后脚本，但未找到Electron Builder中指定脚本路径的配置项

Mac端 #

1. 手动修改info.plist添加协议相关配置，但格式不完整

问题现象 #

Windows下按Win+R输入tel://后，应用未出现在可选应用列表；Mac端配置同样未生效

Windows端修复方案 #

1. 完善Electron Builder协议配置

仅指定schemes和name不足以让系统识别，需补充protocol字段，并在win节点下明确注册表写入规则。完整配置示例（可放在package.json的build字段或单独的electron-builder.json中）：

{
  "protocols": [
    {
      "name": "Tel Protocol Handler",
      "schemes": ["tel"],
      "protocol": "tel"
    }
  ],
  "win": {
    "protocols": [
      {
        "name": "Tel Protocol Handler",
        "schemes": ["tel"],
        "protocol": "tel",
        "registry": {
          "urlProtocol": "tel://"
        }
      }
    ]
  }
}

注意：name建议使用描述性名称，避免与系统默认协议名冲突

2. 验证注册表写入

安装应用后，检查注册表路径HKEY_CLASSES_ROOT\tel：

• 默认值需为URL:Tel Protocol
• URL Protocol键值为空字符串
• shell\open\command下的默认值为应用启动命令（需包含%1参数以接收协议链接）

如果注册表项缺失，优先检查Electron Builder配置是否正确，而非手动修改。

3. 安装后脚本兜底（可选）

若配置仍不生效，可通过Electron Builder的afterInstall脚本强制写入注册表：

1. 在package.json中添加配置：

"build": {
  "win": {
    "afterInstall": "scripts/registerTelProtocol.js"
  }
}

2. 编写脚本scripts/registerTelProtocol.js：

const { execSync } = require('child_process');
const appPath = process.env.APP_PATH || process.execPath;

try {
  execSync(`reg add HKCR\\tel /ve /d "URL:Tel Protocol" /f`);
  execSync(`reg add HKCR\\tel /v "URL Protocol" /d "" /f`);
  execSync(`reg add HKCR\\tel\\shell\\open\\command /ve /d "\"${appPath}\" \"%1\"" /f`);
  console.log('tel协议注册成功');
} catch (err) {
  console.error('tel协议注册失败:', err);
}

Mac端修复方案 #

1. 通过Electron Builder自动生成info.plist配置

手动修改info.plist容易被打包过程覆盖，建议通过mac.extendInfo配置自动生成：

{
  "mac": {
    "extendInfo": {
      "CFBundleURLTypes": [
        {
          "CFBundleURLName": "Tel Protocol Handler",
          "CFBundleURLSchemes": ["tel"],
          "CFBundleTypeRole": "Editor"
        }
      ]
    }
  }
}

关键：必须添加CFBundleTypeRole字段，指定应用角色（Editor或Viewer），这是Mac系统识别协议处理程序的必要条件

2. 强制刷新系统协议关联

安装应用后，若tel协议仍未关联，可通过终端执行以下命令刷新：

/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -f /Applications/你的应用名称.app

3. 验证关联状态

打开系统设置→桌面与 Dock→文件和文件夹→协议，查看tel协议是否已关联到你的应用。若未出现，尝试重启系统后再检查。

通用注意事项 #

1. 使用正式安装包测试：开发模式（electron .）无法测试协议注册，必须使用Electron Builder打包后的安装程序
2. 应用签名：Mac端未签名的应用可能被系统拦截协议注册；Windows端建议对安装包进行代码签名
3. 处理协议参数：在Electron主进程中监听对应事件，确保能接收并处理tel://链接：

const { app } = require('electron');

// Windows：处理二次启动时的协议链接
app.on('second-instance', (event, commandLine) => {
  const telUrl = commandLine.find(arg => arg.startsWith('tel://'));
  if (telUrl) {
    console.log('收到tel链接:', telUrl);
    // 这里添加你的业务处理逻辑
  }
});

// Mac：处理协议启动事件
app.on('open-url', (event, url) => {
  event.preventDefault();
  if (url.startsWith('tel://')) {
    console.log('收到tel链接:', url);
    // 这里添加你的业务处理逻辑
  }
});

// 确保单实例运行（可选，避免多窗口）
if (!app.requestSingleInstanceLock()) {
  app.quit();
}

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