Web Locks API 的 ifAvailable 模式避免长时间等待

ifAvailable: true 会把 Web Locks API 的“排队等锁”改成“一次异步立即尝试”。锁能直接授予时，回调收到 Lock；锁正被占用或当前请求不能立即授予时，回调仍会执行，但参数是 null，因此页面可以立刻选择跳过、提示忙碌或稍后再试。

ifAvailable 不是同步 API，也不会抛出“锁忙”异常。正确分支写在 callback 内：先判断 lock === null，再决定是否执行受保护任务。

普通 request 会排队，ifAvailable 不进入等待

Web Locks 用资源名协调同一存储桶中的页面与 Worker。普通的 navigator.locks.request() 在锁不能授予时进入队列，直到前一个持有者释放。回调返回的 Promise 完成后，锁会自动释放，请求本身返回的 Promise 再取得回调结果。

加入 ifAvailable: true 后，语义发生了一个关键变化：请求只接受“无需额外等待即可授予”的结果。若条件不满足，它不会留在队列里，而是安排 callback 接收 null。规范同时提醒，这仍可能涉及跨进程通信，所以结果始终通过 Promise 异步返回。

最小封装要返回“完成、忙碌、不可用”三种结果

不要让调用方通过异常猜测“锁忙”。下面的封装把三种结果显式返回：浏览器不支持时为 unsupported，锁被占用时为 busy，任务完成时为 done。

async function trySyncOutbox() {
  if (!("locks" in navigator)) {
    return { status: "unsupported" }; // 中文注释：旧环境由上层选择降级策略
  }

  return navigator.locks.request(
    "outbox-sync",
    { mode: "exclusive", ifAvailable: true },
    async (lock) => {
      if (lock === null) {
        return { status: "busy" }; // 中文注释：锁不可立即授予，不排队等待
      }

      await syncPendingRecords(); // 中文注释：Promise 未完成前锁保持占用
      return { status: "done" };  // 中文注释：回调结束后浏览器自动释放锁
    },
  );
}

这里显式写出 mode: "exclusive" 便于阅读；exclusive 本身是默认模式。锁名由应用定义，但不要以连字符 - 开头，否则规范要求请求以 NotSupportedError 拒绝。

把快速失败接到用户能理解的状态

ifAvailable 适合“重复执行也没有价值”的任务，例如多个标签页同时触发本地离线队列同步、后台缓存刷新或一次性索引整理。如果另一个上下文已经在做，当前上下文可以直接复用旧数据或展示轻量提示。

syncButton.addEventListener("click", async () => {
  syncButton.disabled = true; // 中文注释：避免同一页面连续触发重复请求

  try {
    const result = await trySyncOutbox();

    if (result.status === "busy") {
      showMessage("另一个标签页正在同步，请稍后刷新"); // 中文注释：忙碌是预期分支
      return;
    }
    if (result.status === "unsupported") {
      showMessage("当前环境不支持跨标签页锁"); // 中文注释：不伪装成本地锁成功
      return;
    }

    showMessage("同步完成"); // 中文注释：只有受保护任务完成后显示成功
  } catch (error) {
    reportSyncError(error); // 中文注释：业务异常仍按失败处理，不与 busy 混淆
  } finally {
    syncButton.disabled = false; // 中文注释：无论结果如何都恢复按钮状态
  }
});

这段代码特意把 busy 与异常分开。callback 收到 null 是条件获取的正常结果；真正的网络、IndexedDB 或业务错误，仍会让 callback 的 Promise 拒绝，并传递到外层 catch。

ifAvailable、signal 和 steal 不能随意混用

ifAvailable 表达“完全不等”；signal 表达“允许等待，但可以取消”；steal 则会抢占同名锁。它们解决的是不同问题。当前规范明确限制以下组合：

• ifAvailable: true 与 signal 同时出现，会以 NotSupportedError 拒绝。
• ifAvailable: true 与 steal: true 同时出现，也会以 NotSupportedError 拒绝。
• steal 只允许 exclusive 模式，而且被抢占代码可能继续执行，因此不能把它当作普通快速失败方案。

如果需求是“最多等 300 毫秒”，应单独使用 signal，而不是再加 ifAvailable：

async function syncWithTimeout() {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 300); // 中文注释：限制排队等待时间

  try {
    return await navigator.locks.request(
      "outbox-sync",
      { signal: controller.signal },
      async () => syncPendingRecords(), // 中文注释：获得锁后执行完整同步任务
    );
  } finally {
    clearTimeout(timer); // 中文注释：无论成功或失败都清理计时器
  }
}

两种方案的产品体验不同：ifAvailable 更像“有空就做”，timeout 更像“愿意稍等，但不能无限等”。先确定任务能否被跳过，再选择 API 参数。

兼容降级不要用 localStorage 冒充原子锁

Web Locks 只在安全上下文中提供，并且应先做能力检测。旧浏览器、部分嵌入式 WebView 或非安全页面可能没有 navigator.locks。此时不要简单用“先读 localStorage、再写 localStorage”代替，因为这两步不是一个原子操作，多个标签页仍可能同时认为自己拿到了锁。

更稳妥的降级方式取决于任务：

• 可跳过的后台刷新：返回 unsupported，仅在当前页面内执行一次节流。
• 必须保证一致的写操作：把幂等键、版本号或条件更新放到服务端。
• 只需要单页面互斥：使用页面内状态即可，不宣称跨标签页互斥。

Web Locks 是浏览器上下文之间的协作机制，不是跨设备分布式锁，也不能替代服务端事务和权限检查。

最小验证清单

• 在安全上下文中确认 "locks" in navigator 为真。
• 让标签页 A 持有同名 exclusive 锁，再从标签页 B 发起 ifAvailable 请求。
• 确认标签页 B 的 callback 收到 null，并进入 busy 分支而不是异常分支。
• 释放标签页 A 的锁后再次触发，确认 callback 收到 Lock 并执行任务。
• 确认受保护 callback 完成前锁不会释放，完成或抛错后会自动释放。
• 检查代码没有同时传入 ifAvailable 与 signal 或 steal。

最终判断很简单：必须执行的任务继续使用普通排队或带 signal 的限时等待；允许跳过的任务才使用 ifAvailable。把 null 当作正常业务结果处理，就能避免页面为了一个非关键任务长时间挂在锁队列中。

常见问题

ifAvailable 会同步返回结果吗？

不会。它只表示不进行额外等待，锁状态检查和 callback 调用仍是异步过程，调用方继续使用 Promise 或 await。

锁不可用时 request Promise 会 reject 吗？

不会因为“忙碌”而 reject。callback 会收到 null，Promise 最终使用 callback 的返回值完成。参数错误或 callback 自身抛错则是另一回事。

可以在 Web Worker 中使用吗？

可以。规范将该 API 暴露给 Window 和 Worker，但仍受安全上下文、存储桶和浏览器支持条件约束。

共享锁也能配合 ifAvailable 吗？

可以。是否能立即授予取决于当前同名锁模式：多个 shared 锁可以并存，但已有 exclusive 锁时不能授予 shared 请求。

参考资料

• W3C Web Locks API Working Draft
• MDN：Web Locks API
• MDN：LockManager.request()