Electron无法使用蓝牙，调用requestDevice触发用户手势相关报错

Failed to execute 'requestDevice' on 'Bluetooth': Must be handling a user gesture to show a permission request.
报错释义：在Bluetooth接口上执行requestDevice操作失败，必须在用户手势的处理逻辑中才能发起权限请求。

该报错是Web Bluetooth API的内核级安全限制，Electron底层依赖的Chromium内核明确要求navigator.bluetooth.requestDevice必须由用户主动交互行为（点击、触摸、键盘按下等明确的用户操作）触发，不能脱离用户手势上下文调用，否则会直接抛出权限异常。

1. 调整调用时机 #

将requestDevice的调用逻辑直接绑定到用户主动交互事件的同步回调中，不要嵌套到非手势触发的异步逻辑（定时器、接口请求回调、Promise异步链深层等）中，参考正确写法：

// 渲染层代码示例
const searchBluetoothBtn = document.getElementById('search-btn')
searchBluetoothBtn.addEventListener('click', async () => {
  try {
    const targetDevice = await navigator.bluetooth.requestDevice({
      // 可自定义设备过滤规则
      acceptAllDevices: true
    })
    console.log('已选择蓝牙设备：', targetDevice)
  } catch (error) {
    console.error('蓝牙设备搜索失败：', error)
  }
})

2. 配置Electron主进程蓝牙权限 #

在主进程中开启Web Bluetooth支持，同时处理设备选择回调：

// 主进程代码示例
const { app, BrowserWindow } = require('electron')
const path = require('path')
let mainWindow

// 启动时开启蓝牙支持开关
app.commandLine.appendSwitch('enable-web-bluetooth')

function createWindow () {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      // 按需配置上下文隔离、预加载脚本等
      contextIsolation: true,
      preload: path.join(__dirname, 'preload.js')
    }
  })

  // 处理蓝牙设备选择请求
  mainWindow.webContents.on('select-bluetooth-device', (event, devices, callback) => {
    event.preventDefault()
    // 可自定义匹配逻辑筛选需要的设备，此处示例返回第一个搜索到的设备
    if (devices.length > 0) {
      callback(devices[0].deviceId)
    }
  })

  mainWindow.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()
})

3. 规避常见错误写法 #

以下写法会丢失用户手势上下文，直接触发报错，需避免：

// 错误1：页面加载时自动调用，无用户手势触发
window.addEventListener('DOMContentLoaded', () => {
  navigator.bluetooth.requestDevice({ acceptAllDevices: true })
})

// 错误2：用户点击后嵌套异步逻辑再调用，手势上下文已失效
searchBtn.addEventListener('click', () => {
  // 模拟后端请求获取过滤规则的异步操作
  fetch('/api/bluetooth/filters').then(res => res.json()).then(filters => {
    // 此处已脱离用户手势上下文，调用会报错
    navigator.bluetooth.requestDevice({ filters })
  })
})

如果必须依赖异步返回的参数再搜索设备，可在异步逻辑执行完成后，弹出二次确认按钮，在用户点击确认的回调中再调用requestDevice即可。

4. 版本兼容检查 #

如果上述配置都正确仍报错，检查Electron版本，建议升级到14.0+版本，旧版本对Web Bluetooth API的支持存在较多兼容性问题。

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