如何实现从网页一键启动你的 Electron 桌面应用（zxjapp://）

在现代桌面应用开发中，Electron 凭借其跨平台能力和前端友好的特性，受到了越来越多开发者的青睐。但你是否想过，如何让用户从网页上一键启动你本地的 Electron 应用？比如像某些云盘客户端那样，点击网页上的按钮就能直接唤起桌面程序？

本文将手把手教你如何通过自定义协议（URL Scheme）的方式，实现从网页一键唤醒你的 Electron 应用 —— zxjapp://。

---

我们希望达到的效果是：

• 在网页中放置一个按钮；
• 用户点击后尝试打开本地安装的 Electron 应用；
• 如果未安装，则提示用户下载；
• 支持 Windows 和 macOS 平台；
• 可扩展：未来可支持传参、深度链接等功能。

---

二、实现原理概述

要实现网页调起本地应用，核心在于 注册一个自定义的 URL 协议，例如 zxjapp://，然后让系统知道这个协议应该由我们的 Electron 应用来处理。

Electron 提供了 app.setAsDefaultProtocolClient() 方法，可以让我们轻松地为指定协议设置默认处理程序。

---

三、具体实现步骤

1. 修改主进程代码（main.js）

首先，在你的 Electron 主进程文件中添加如下代码，用于注册协议和监听请求。

const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');let mainWindow;function createWindow() {mainWindow = new BrowserWindow({width: 800,height: 600,webPreferences: {preload: path.join(__dirname, 'preload.js'),contextIsolation: true,enableRemoteModule: false,nodeIntegration: false}});mainWindow.loadFile('index.html');// 打开开发者工具（可选）// mainWindow.webContents.openDevTools();mainWindow.on('closed', () => {mainWindow = null;});
}// 注册 zxjapp:// 协议
if (require('electron-squirrel-startup')) return;const gotTheLock = app.requestSingleInstanceLock();if (!gotTheLock) {app.quit();
} else {app.on('second-instance', (event, commandLine, workingDirectory) => {if (mainWindow) {if (mainWindow.isMinimized()) mainWindow.restore();mainWindow.focus();}});app.whenReady().then(() => {createWindow();// 设置默认协议处理器const protocol = require('electron').protocol;protocol.registerSchemesAsPrivileged([{ scheme: 'zxjapp', privileges: { bypassCSP: true } }]);app.setAsDefaultProtocolClient('zxjapp');app.on('activate', () => {if (BrowserWindow.getAllWindows().length === 0) createWindow();});});
}app.on('window-all-closed', () => {if (process.platform !== 'darwin') app.quit();
});

⚠️ 注意：如果你使用的是 electron-builder 打包，确保 package.json 中配置了 appId，否则协议可能无法正确注册。

{"build": {"appId": "com.zxj.app"}
}

---

2. 处理协议调用（可选增强体验）

为了能在应用被调用时做一些事情，比如显示某个页面或传递参数，我们可以监听 open-url 事件：

app.on('will-finish-launching', () => {app.on('open-url', (event, url) => {event.preventDefault();console.log('收到协议调用:', url);if (mainWindow) {mainWindow.webContents.send('protocol-url', url);}});
});

并在渲染进程中监听这个事件：

const { ipcRenderer } = require('electron');ipcRenderer.on('protocol-url', (event, url) => {alert('收到协议地址: ' + url);// 可以解析并跳转到特定页面
});

---

3. 网页端添加触发按钮

现在我们在网页中添加一个按钮，点击后尝试打开 zxjapp:// 协议。

// 打开绑卡APP
const openDesktopApp = () => {// 创建一个隐藏的iframe来尝试打开应用const iframe = document.createElement('iframe');iframe.style.display = 'none';document.body.appendChild(iframe);// 设置超时时间const timeout = 2000;const startTime = Date.now();// 尝试打开应用iframe.src = 'runbayun://';// 监听页面可见性变化document.addEventListener('visibilitychange', function handler() {if (document.hidden) {// 如果页面隐藏，说明应用已安装并成功打开document.removeEventListener('visibilitychange', handler);document.body.removeChild(iframe);return;}// 如果超时且页面仍然可见，说明应用未安装if (Date.now() - startTime > timeout) {document.removeEventListener('visibilitychange', handler);document.body.removeChild(iframe);ElMessage.warning('请先安装润吧云桌面应用');}});
};

---

四、注意事项与常见问题

1. Windows 注册表自动写入

Electron 的 setAsDefaultProtocolClient() 方法会在 Windows 上自动修改注册表项，使 zxjapp:// 关联到你的应用。无需手动编辑注册表。

2. macOS 下需要沙盒权限

如果你的应用启用了沙盒（macOS App Sandbox），你需要在 entitlements.plist 文件中添加如下权限：

<key>com.apple.security.protocol-messaging</key>
<true/>