Mac端Capacitor Electron深度链接错误启动非目标应用问题

可能的核心原因 #

• 系统协议关联错误：macOS中深度链接的协议关联指向了错误的应用路径（比如旧版本应用、未打包的开发版应用），导致点击链接时启动了无关实例。
• 单实例机制未生效：Capacitor Electron的单实例锁未正确配置，新启动的进程无法检测到已有运行实例，也无法触发second-instance事件。
• 监听器注册时机/方式错误：在Capacitor的Electron生命周期中，监听器注册过晚，或者未通过Capacitor提供的接口绑定，导致open-url等事件无法被捕获。
• 沙箱权限限制：打包时开启了macOS沙箱，但未配置相应权限，导致应用无法接收深度链接事件或与其他进程通信。

具体解决步骤 #

1. 检查并修复系统协议关联 #

在终端执行以下命令，查看当前协议的关联应用：

defaults read com.apple.LaunchServices/com.apple.launchservices.secure | grep -A 5 -B 5 "your-protocol"

• 如果输出的应用路径不是你当前打包后的.app路径，执行以下命令重置协议关联：

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -R -f /path/to/your/packaged/app.app

• 重置后重启电脑，确保协议指向正确的应用。

2. 正确配置单实例锁 #

在Electron主进程的index.ts中，在app.whenReady()之前初始化单实例锁，并绑定second-instance事件：

import { app } from 'electron';
import { CapacitorElectronApp } from '@capacitor-community/electron';

// 单实例锁初始化
const gotTheLock = app.requestSingleInstanceLock();
if (!gotTheLock) {
  app.quit();
} else {
  app.on('second-instance', (event, commandLine) => {
    // 从命令行参数中提取深度链接URL
    const deepLinkUrl = commandLine.find(arg => arg.startsWith('your-protocol://'));
    if (deepLinkUrl) {
      const mainWindow = CapacitorElectronApp.getMainWindow();
      if (mainWindow) {
        // 恢复窗口并聚焦
        if (mainWindow.isMinimized()) mainWindow.restore();
        mainWindow.focus();
        // 将URL发送到渲染进程处理
        mainWindow.webContents.send('deep-link-received', deepLinkUrl);
      }
    }
  });
}

// 后续的Capacitor初始化逻辑
app.whenReady().then(async () => {
  await CapacitorElectronApp.init();
  // ...其他初始化代码
});

3. 调整监听器注册方式与时机 #

在app.whenReady()回调中，通过Capacitor的实例绑定open-url事件：

app.whenReady().then(async () => {
  await CapacitorElectronApp.init();
  
  // 监听应用启动时的深度链接
  app.on('open-url', (event, url) => {
    event.preventDefault();
    const mainWindow = CapacitorElectronApp.getMainWindow();
    mainWindow.webContents.send('deep-link-received', url);
    mainWindow.focus();
  });
});

同时，在渲染进程中监听deep-link-received事件处理链接逻辑：

// 渲染进程代码（比如src/main.ts）
import { ipcRenderer } from 'electron';

ipcRenderer.on('deep-link-received', (event, url) => {
  // 处理深度链接，比如路由跳转
  console.log('Received deep link:', url);
});

4. 同步打包配置与Capacitor配置 #

确保capacitor.config.ts中的深度链接配置正确：

import { defineConfig } from '@capacitor/cli';

export default defineConfig({
  appId: 'com.your.app.id',
  appName: 'Your App',
  // ...其他配置
  electron: {
    deepLinkingEnabled: true,
    deepLinkingCustomProtocol: 'your-protocol',
  },
});

如果使用electron-builder打包，在package.json的build字段中补充协议配置：

{
  "build": {
    "mac": {
      "protocols": [
        {
          "name": "Your App Deep Link",
          "schemes": ["your-protocol"]
        }
      ],
      "extendInfo": {
        "CFBundleURLTypes": [
          {
            "CFBundleURLSchemes": ["your-protocol"],
            "CFBundleURLName": "Your App Name"
          }
        ]
      }
    }
  }
}

5. 检查沙箱权限（若开启） #

如果打包时启用了macOS沙箱，需要在entitlements.mac.plist中添加必要权限：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.network.client</key>
  <true/>
  <key>com.apple.security.application-groups</key>
  <array>
    <string>YOUR_TEAM_ID.com.your.app.id</string>
  </array>
</dict>
</plist>

并在package.json的build字段中指定该文件：

{
  "build": {
    "mac": {
      "entitlements": "electron/entitlements.mac.plist"
    }
  }
}

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