Web Bluetooth需满足HTTPS（或localhost）、用户手势触发、服务过滤三前提；用!!navigator.bluetooth判断支持性，false或undefined即不支持；requestDevice()失败主因是无手势、filters不当或设备未广播匹配服务；GATT连接后须确认connected为true且特征值支持read权限，读取结果需用DataView等解包。
Web Bluetooth 在现代 Chromium 浏览器中可用，但不是“写个 <script></script> 就连上”，必须满足 HTTPS（或 localhost）、用户手势触发、设备服务过滤三个硬性前提，缺一不可。
怎么判断浏览器支持 navigator.bluetooth
别靠猜，直接在控制台执行：!!navigator.bluetooth。返回 true 才继续；若为 false 或报 undefined，说明当前环境不满足条件——常见于 Firefox、Safari、非 Chromium Edge、HTTP 非本地页面，或 Chrome 未启用实验性功能（v89+ 默认开启，但企业策略可能禁用）。
检查时注意：http://127.0.0.1 可以，http://0.0.0.0 或 file:// 协议绝对不行。
navigator.bluetooth.requestDevice() 总是失败或没反应？
这是最常卡住的环节，失败原因高度集中：
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
立即学习“前端免费学习笔记（深入）”；
- 没用用户点击等手势触发：把
requestDevice()放在setTimeout、DOMContentLoaded或自动轮询里，浏览器会直接拒绝，错误类型通常是SecurityError -
filters配置不当：设{ acceptAllDevices: true }在真实设备多的环境里等于给用户扔出上百个陌生设备，极易误点或放弃；更糟的是漏写filters（空对象 {} 不生效），浏览器可能静默失败 - 目标设备没广播指定服务：比如你填
services: ['battery_service']，但设备实际只广播0000180f-0000-1000-8000-00805f9b34fb（标准电池服务 UUID），而浏览器对缩写名（如'battery_service'）的支持依赖内部映射，某些版本可能不识别，建议优先用完整 UUID 字符串
连上设备后读不到 battery_level 怎么办
连接成功 ≠ 数据可读。GATT 层有明确访问权限控制：
-
device.gatt.connect()返回的 Promise 解析后，必须确认device.gatt.connected === true，否则后续操作全抛InvalidStateError -
service.getCharacteristic('battery_level')返回的BluetoothCharacteristic对象，需检查其properties.read === true，否则readValue()必然失败 - 读取结果是
ArrayBuffer，不能直接console.log(value)：要用new DataView(value)或value.getUint8(0)解包，否则看到的是空对象或乱码 - 某些设备要求先使能通知（
characteristic.startNotifications()）才能读，尤其是心率、温度类动态数据，静态电量反而常支持直接读
HTTPS 本地开发用 localhost 还是 127.0.0.1
两者都行，但行为有差异：
-
localhost是白名单域名，所有 Chromium 版本均无条件允许 Web Bluetooth -
127.0.0.1从 Chrome 110+ 开始才被加入安全上下文白名单；旧版（如 v105）会报NotAllowedError，即使端口开放、服务正常 - 用
ngrok或localtunnel做临时 HTTPS 映射时，务必确认隧道域名是否出现在 Chrome 的chrome://flags/#unsafely-treat-insecure-origin-as-secure列表里，否则 API 仍不可用
真机调试时最容易忽略的是：手机浏览器访问 PC 上的 localhost，其实连的是手机自己的 localhost，不是你的开发机——必须用局域网 IP（如 https://192.168.x.x:3000）并确保证书可信，否则 navigator.bluetooth 直接消失。
