Service Worker registration.update 怎么判断新脚本已经下载

Service Worker 更新最容易误判的地方，是把 registration.update() 返回的 Promise 当成“新脚本已经下载并生效”。实际上，它只代表一次更新检查完成；真正要判断新脚本是否到位，应观察 updatefound、新 worker 的 statechange，再结合 waiting、active 和当前页面的 controller。

registration.update() 返回值为什么不能直接当成新脚本已下载

update() 会请求 Service Worker 脚本；只有新脚本与当前版本的字节内容不一致，浏览器才会创建新的 worker 并进入安装过程。它返回的仍然是 ServiceWorkerRegistration，不是“下载完成”的布尔值，也不承诺当前页面已经切换到新版本。

我在排查离线页面时，会把一次检查拆成三个可观测槽位：更新检查本身、脚本安装状态、页面控制状态。这样一次记录最多包含一个 Promise 结果、一个 worker 状态和一个页面 controller，数据比只打印“update success”更有用。

用 updatefound 和 statechange 判断新脚本是否安装完成

updatefound 只说明 installing 获得了新的 Service Worker，不能单独当作下载完成信号。要得到可操作的结论，还要监听这个 worker 的状态变化：进入 installed 时，可认为新脚本已经完成安装；进入 redundant 则说明它没有成为可用版本。

下面的写法把“没有变化”和“发现新脚本”分开返回。超时时间不是浏览器规则，而是业务层的观测窗口；生产环境可以换成自己的日志或页面提示策略。

function waitForInstall(worker) {
  return new Promise((resolve) => {
    const onStateChange = () => {
      // installed 表示安装完成，redundant 表示该 worker 已失效或被替换
      if (["installed", "activated", "redundant"].includes(worker.state)) {
        worker.removeEventListener("statechange", onStateChange);
        resolve(worker.state);
      }
    };
    worker.addEventListener("statechange", onStateChange);
    onStateChange(); // worker 可能在绑定监听器前已经发生状态变化
  });
}

async function checkServiceWorkerUpdate() {
  const registration = await navigator.serviceWorker.getRegistration("/");
  if (!registration) {
    throw new Error("当前作用域没有 Service Worker 注册记录");
  }

  // update() 负责发起检查，返回值仍然是 registration
  const updated = await registration.update();
  const worker = updated.installing || updated.waiting;

  // 没有 installing/waiting，通常表示这次没有发现不同脚本
  if (!worker) {
    return { status: "unchanged", downloaded: false };
  }

  const state = await waitForInstall(worker);
  return {
    status: state,
    downloaded: state === "installed" || state === "activated",
    waiting: !!updated.waiting,
    active: !!updated.active
  };
}

这个判断的关键不是 Promise 的名字，而是 worker 的状态。若脚本很快从 installed 进入 activated，返回值仍然可以判定为已完成；若返回 redundant，则应记录为失败或被更新覆盖，而不是提示用户刷新。

waiting、active 和 controller 如何说明页面是否真的换版本

新脚本安装完成后，常见状态是 registration.waiting 有值。这表示它已经准备好，但仍可能因为旧客户端存在而等待激活。如果 Service Worker 没有主动调用 skipWaiting()，此时直接说“页面已经更新”是不准确的。

即使 registration.active 已经指向新 worker，当前页面也应检查 navigator.serviceWorker.controller。前者描述注册对象的激活槽位，后者描述这个页面当前收到 fetch 控制的 worker。对用户提示“刷新后生效”时，通常应把 waiting 作为提示依据，把 controller 作为刷新后的确认依据。

function readWorkerVersion(registration) {
  const waiting = registration.waiting;
  const active = registration.active;
  const controller = navigator.serviceWorker.controller;

  // waiting 有值：新脚本已安装，但还没有接管旧客户端
  if (waiting) {
    return { phase: "waiting", worker: waiting.scriptURL };
  }
  // controller 才能说明当前页面实际由哪个 worker 控制
  if (active && controller && controller.scriptURL === active.scriptURL) {
    return { phase: "controlling", worker: controller.scriptURL };
  }
  return { phase: active ? "active-not-confirmed" : "no-active-worker" };
}

如果产品允许无感切换，可以在确认资源兼容后由 worker 自己处理等待激活；如果页面存在未保存编辑、长连接或旧缓存协议，保守地提示用户刷新往往更安全。skipWaiting() 解决的是激活时机，不是下载判断本身。

缓存和控制范围里的四个常见误判

• 脚本 URL 没变就认为脚本没更新。浏览器比较的是脚本响应的字节内容，构建产物或服务端响应策略变化也可能触发更新；反过来，内容没有变化时反复调用 update() 不会凭空产生新 worker。
• 看到 updatefound 就提示“更新完成”。它只代表进入 installing，必须等 statechange 到达目标状态。
• 看到 waiting 就认为所有页面都换成新版本。waiting 说明新 worker 等待激活，旧客户端仍可能被旧 worker 控制。
• 用一次 reload 当成通用修复。先确认 scope、HTTPS 或 localhost、脚本响应和当前 controller；盲目刷新可能只掩盖缓存或注册范围配置问题。

最终检查清单可以压缩为四个问题：本次有没有新的 installing？它是否到达 installed 或 activated？registration.waiting 是否仍有值？刷新后 controller 是否指向预期脚本？四个答案齐全，更新链路才算真正可解释。

常见问题

update() resolve 后没有 installing，是不是浏览器没有请求脚本？

不一定。它可能已经完成检查但发现脚本内容没有变化。要排查请求是否发生，再查看浏览器网络面板和服务器响应；代码中的状态判断只负责区分注册结果。

installed 和 waiting 是同一个阶段吗？

它们有关联但不是同一个观察点。installed 是 worker 的状态，waiting 是 registration 上的槽位；新 worker 安装完成后通常会出现在 waiting，具体激活时机还受旧客户端影响。

为什么 active 有值但 controller 还是旧的？

active 描述注册对象当前的激活 worker，controller 描述当前页面正在使用的控制者。页面可能还没有重新导航，或者新 worker 尚未对这个客户端取得控制权。

总结

判断 Service Worker 新脚本是否已经下载，不要只看 registration.update() 的 Promise。用 updatefound 找到新 worker，再用 statechange 等到 installed 或 activated；随后用 waiting、active 和页面 controller 判断它是否只是准备好，还是已经真正服务当前页面。