PWA デプロイ即反映（Service Worker 自動 reload）— 完全再現指示書

Next.js / Vite / Vanilla の PWA で、コードを更新して server が新版を配信していても、 スマホ側は Service Worker と Chrome HTTP キャッシュで 古い bundle を掴んだまま になる問題を、 「デプロイ即・全 tab 自動 reload」に変える完全レシピ。

何が起きる問題か

• server は新版を返している (HTML bundle 差し替え済み)
• SW が古い bundle を cache から返している / Chrome の HTTP キャッシュが古い .js を返す
• クライアントは 1 週間前の UI が表示されたまま
• ユーザーに「PWA を削除して入れ直して」と言うのは苦しい

3 点セット（これで解決）

1. Service Worker に VERSION 定数 + activate で全 tab に postMessage

public/sw.js:

const VERSION = 'vN-YYYY-MM-DD'; // deploy ごとに bump

self.addEventListener('install', (e) => {
  self.skipWaiting();
});

self.addEventListener('activate', (e) => {
  e.waitUntil((async () => {
    await self.clients.claim();
    const tabs = await self.clients.matchAll({ type: 'window' });
    for (const t of tabs) {
      try { t.postMessage({ type: 'sw-updated', version: VERSION }); } catch {}
    }
  })());
});

// network-first passthrough — server が生きてる時は常に fresh を fetch
self.addEventListener('fetch', (event) => {
  event.respondWith(fetch(event.request).catch(() => new Response('offline', { status: 503 })));
});

2. クライアント側: SW register 時に updateViaCache='none' + message listener で自動 reload

React 例 (Vite / Next.js どちらでも同じ):

useEffect(() => {
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js', {
      scope: '/',
      updateViaCache: 'none', // SW 自体のキャッシュを回避
    }).then((reg) => {
      reg.update().catch(() => {});
      navigator.serviceWorker.addEventListener('message', (e) => {
        if (e.data?.type === 'sw-updated') {
          window.location.reload();
        }
      });
    }).catch(() => {});
  }
}, []);

3. UI に版番号タグを表示（人間が新旧を目視判別）

タイトルバー / ヘッダに版番号を出す:

<h1>アプリ名 <span className="text-[9px] text-zinc-600 ml-1">v3-08-04</span></h1>

デプロイフロー

大きな UI 変更をした時:

1. sw.js の VERSION 定数を bump ('v3-08-04' → 'v4-08-05')
2. UI 側のタグも合わせて更新
3. デプロイ
4. 開いてる全 PWA が SW update → activate → 全 tab に postMessage → 自動 reload

検証

デプロイ後、実機の PWA を開いて:

• 版番号タグが新しくなっているか目視確認
• なっていなければキャッシュクリア (最初の 1 回だけ、以後は自動)

Why これで解決するのか

• updateViaCache: 'none' は SW 本体の fetch を必ずネットワークにする → 新 VERSION 検知が早い
• skipWaiting() + clients.claim() で「次の tab close まで待たずに」新 SW が activate
• postMessage → location.reload() で開いてる tab を強制更新
• ネットワークファースト fetch で JS/HTML bundle も新版を掴む

やらないこと

• caches.open() で pre-cache しない (キャッシュ管理コスト >>> 帯域節約)
• Chrome の HTTP キャッシュヘッダ (Cache-Control) だけに頼らない (SW を挟む以上 SW 側の制御が必要)
• サービス側で「更新あります」バナーを出す UX は 1 tap 追加になり離脱するので、自動 reload の方が良い

適用範囲

• Next.js App Router / Pages Router いずれも
• Vite + React / Vue
• Vanilla HTML PWA
• Cordova / Capacitor 系にも Web View 部分は同じ