前端怎样查询当前 Web Lock 持有者

要判断当前 Web Lock 被谁持有，核心不是重新申请一次锁，而是读取 navigator.locks.query() 返回的状态快照。结果中的 held 列出当前上下文可见的已持有锁，pending 列出正在等待的请求；每项通常关注 name、mode 和 clientId。

官方参考：https://developer.mozilla.org/en-US/docs/Web/API/LockManager/query

LockManager.query() 返回的快照包含什么

query() 不接收参数，解析后得到一个对象。它适合诊断“某个资源为什么一直等不到”的现场状态，但不能把这次读取当成实时订阅：查询结束后，其他页面可能立即释放或申请同名锁。

用 held 和 pending 区分持有者与等待者

下面的函数把两组结果整理成适合日志或诊断面板使用的数据。代码只读取快照，不修改锁，也不会打断正在运行的临界区。

async function readWebLockState() {
  // 先判断 API 是否存在，避免在不支持的浏览器中直接抛出 TypeError
  if (!navigator.locks || typeof navigator.locks.query !== "function") {
    return { supported: false, held: [], pending: [] };
  }

  try {
    // query() 没有参数，返回当前上下文能观察到的一次状态快照
    const snapshot = await navigator.locks.query();
    const describe = (lock) => ({
      name: lock.name,
      mode: lock.mode,
      clientId: lock.clientId ?? "未知"
    });

    // held 表示已经持有，pending 表示正在排队，两者不要混为一谈
    return {
      supported: true,
      held: snapshot.held.map(describe),
      pending: snapshot.pending.map(describe)
    };
  } catch (error) {
    // 保留异常类型，便于区分页面生命周期问题与环境不可用问题
    return { supported: true, error: error.name, held: [], pending: [] };
  }
}

当 held 中出现 report-cache，说明这个查询快照里已有上下文持有该锁；如果同名项目出现在 pending，则代表请求还没有获得访问权。clientId 适合做关联线索，不应当被当成业务用户 ID。

把查询结果用于排查等待中的锁

排查时先按锁名分组，再结合 mode 看是否存在互斥关系。共享锁之间可以并存，而独占锁会与同名的其他请求形成等待关系。一次查询只能回答“读取瞬间看到什么”，不能证明某个请求永远不会改变。

如果页面需要持续展示状态，可以在业务允许的频率下重复调用诊断函数，并在界面上标出读取时间；不要把一次快照缓存成永久事实。真正的资源协调仍由 navigator.locks.request() 负责，query() 只是观察入口。

安全上下文与异常边界

Web Locks API 依赖安全上下文，生产页面应使用 HTTPS；它也可以在支持该 API 的 Web Worker 中使用。调用时常见的失败原因包括：

• InvalidStateError：当前执行环境的文档还没有完全激活，页面切换或生命周期边界上尤其要注意。
• SecurityError：当前环境无法取得可用的锁管理器，先检查安全上下文和浏览器支持情况。
• navigator.locks 不存在：不要继续调用，应该降级为不展示锁诊断，或使用应用自己的状态通道。

实战中建议把“API 不存在”“查询成功但数组为空”“查询 Promise 被拒绝”记录为三种不同状态。空数组只表示本次快照没有观察到对应对象，不等于系统从未申请过锁。

相关问题

query() 能直接返回唯一持有者吗？

它返回的是锁信息数组，不是一个专门的“当前负责人”字段。对同名项目过滤后，还要结合 mode 和 clientId 自己解释。

为什么 pending 一直不为空？

通常是同名独占锁仍被持有，或者请求的回调没有及时结束。先看 held 中的同名锁，再检查持有锁的回调是否等待了网络或其他不会结束的任务。

query() 会通知状态变化吗？

不会。它返回读取时刻的 Promise 快照，需要持续观察时自行安排再次查询，并接受查询间隔造成的延迟。