プロトコル

stale-while-revalidateとは?Cache-Controlの意味とReact(SWR)の再検証を解説

stale-while-revalidateとは?Cache-Controlの意味とReact(SWR)の再検証を解説

stale-while-revalidateは、期限切れのキャッシュをそのまま返しつつ、裏側で新しい応答を取り直すためのキャッシュ制御です。HTTPのCache-Controlディレクティブとしての顔と、Reactのデータ取得ライブラリSWRが実装する再検証の顔があり、同じ名前でも設定場所も効き方も異なります。この記事では両方を一次情報で切り分け、Node.js・nginx・Service Workerでの設定例、CDNごとに割れるs-maxage併用の判断、nginx 1.31.8で測ったキャッシュ状態の変化、ReactのSWRとTanStack Queryで古い値を返す条件の違い、採用してはいけない応答の条件まで整理します。

まとめ:stale-while-revalidateの設定場所と配信基盤ごとの判断の要点

  • stale-while-revalidateはRFC 5861(2010年5月・Informational)が定めるCache-Control拡張で、「応答がstaleになった後も、指定秒数まではキャッシュがその応答を提供してよい」という指示です。鮮度の期間は持たないため、max-ageと組み合わせて使います。
  • ブラウザはChrome 75・Firefox 68・Safari 14から解釈します。stale-if-errorはブラウザの対応を前提にできないので、エラー時の保険はCDNかnginxの層に置きます。
  • 迷いやすいのはs-maxageとの併用です。Cloudflareは「併用するな」、Vercelは「Functionsではs-maxageを付けろ」と正反対の指示を出しています。配信先のドキュメントを正として書き分けます。
  • 効いているかはヘッダーで確かめます。CloudflareならCF-Cache-Status: UPDATING、Vercelならx-vercel-cache: STALEが、古い応答を返しながら裏で更新している状態です。nginx 1.31.8で測ると、proxy_cache_background_updateを書かない設定では期限切れ後の最初の要求がオリジンを待ち(EXPIRED)、onにすると最初の要求がSTALE、更新中の後続がUPDATINGで即座に返りました。
  • nginxはオリジンが返すstale-if-errorヘッダーだけでは、オリジンが503を返したときに古い応答へ切り替えません(接続拒否では切り替える)。5xxの応答で耐えるならproxy_cache_use_staleにhttp_503などを書きます。
  • ReactのSWR(2.5.1・2026年11月時点)は同じ考え方をメモリ上で実装したもので、鮮度の期間を持たず、マウントやフォーカスのたびに再検証します。一定時間は取り直さない設計にしたいなら、max-ageに当たるstaleTimeを持つTanStack Queryが合います。SWRのerrorRetryCountには既定値がないため明示します。
  • 数秒〜数分の古さを許せる一覧・記事・画像には付け、在庫数・残高・ログイン状態で中身が変わる応答には付けません。

stale-while-revalidateの意味とRFC 5861の再検証猶予

RFC 5861の2指示における再検証中とエラー時の古い応答の扱い

RFC 5861「HTTP Cache-Control Extensions for Stale Content」は、Mark Nottingham氏が2010年5月にIndependent Submissionとして発行したInformational RFCです。ここで定義されているのは3節のstale-while-revalidateと4節のstale-if-errorの2つで、前者は「応答がstaleになった後も、指定された秒数まではキャッシュがその応答を提供してよい」、後者は「エラーが発生したとき、他の鮮度情報にかかわらずキャッシュ済みのstale応答を要求への応答に使用してよい」と規定します。どちらも値はdelta-seconds(秒数)です。

revalidateは「再検証」、staleは「期限切れ」を指します。つまりstale-while-revalidateは、期限切れの応答を返すことでオリジンへの再検証完了を待たずに応答し、裏側で再検証を試みるための指示です。再検証が完了するまでは、許容期間内の後続アクセスにも古い応答が返る場合があります。再検証が成功すると、以後は更新済み、または内容が変わっていないと確認された応答が返ります。

max-ageと組み合わせたときのfresh・stale・期限切れの3つの時間帯

このディレクティブ自体は鮮度の期間を持ちません。鮮度はExpiresやヒューリスティックでも決まりますが、実務ではmax-age(またはs-maxage)と組み合わせ、鮮度の期間と、期限切れ後に古い応答を許す期間を分けて明示します。

Cache-Control: max-age=3600, stale-while-revalidate=600, stale-if-error=86400

Amazon CloudFrontの公式ドキュメントはこの指定を例示し、最初の1時間は通常のキャッシュヒット、経過後の10分間は古い応答を即返しながら裏でオリジンへ再検証、その再検証でオリジンがエラーを返した場合は24時間まで古い応答を返し続ける、と説明しています。注意点として、CloudFrontが古い応答を返せるのはstale-while-revalidateの値とCloudFrontの最大TTLのうち小さい方までで、最大TTLを過ぎたオブジェクトはエッジキャッシュから削除される仕様です。Amazon CloudFrontとは?仕組み・料金プランとエッジ機能・採用判断を実装者目線で解説でTTL設定の全体像を確認しておくと、この上限の意味がつかみやすくなります。

3つの時間帯を整理すると次のとおりです。

経過時間 状態 キャッシュの振る舞い
0〜3,600秒 fresh オリジンに問い合わせず即応答
3,600〜4,200秒 stale(再検証猶予内) 古い応答を即返し、裏で再検証
4,200秒以降 猶予切れ オリジンの応答を待ってから返す

3つ目の帯に入ると通常のキャッシュミスと同じ待ち時間になります。アクセスの少ないページほどこの帯に落ちやすいため、猶予の秒数はアクセス間隔より長めに取ると効果が出ます。

Googleのweb.devの解説記事はmax-age=1, stale-while-revalidate=59の例で同じ3つの帯を示し、非対応のブラウザはこの値を無視してmax-ageだけで動くと書いています。非対応ブラウザでは無視されますが、対応ブラウザでは古い応答が表示されるため、その古さを許容できる応答に限定して追加します。ブラウザ側のキャッシュ指示全般はMDNのCache-Controlリファレンスで一覧できます。

Node.js・nginx・Workboxでのキャッシュ再検証の設定例

ここでは、Cache-Controlにstale-while-revalidateを指定するNode.jsの例、nginxで裏側の更新を有効にする例、WorkboxのStaleWhileRevalidateで応答する例を扱います。設定対象は、オリジンの応答ヘッダー、リバースプロキシ、Service Workerの各層です。

Node.jsの標準httpモジュールでヘッダーを返す最小のサーバー例

まずはオリジン側でヘッダーを返す形を手元で動かします。外部パッケージを使わず、Node.jsのnode:httpだけで記述できる構成です。応答に現在時刻を含めておくと、後述のcurlで古い応答が返ったかどうかを目で判別できます。

// server.mjs  「node server.mjs」で起動し、http://localhost:3000/ を確認する
import { createServer } from 'node:http'

createServer((req, res) => {
  // 60秒はfresh、その後300秒は古い応答を返しつつ裏で再検証、障害時は1日まで古い応答で耐える
  res.setHeader('Cache-Control', 'public, max-age=60, stale-while-revalidate=300, stale-if-error=86400')
  res.setHeader('Content-Type', 'application/json; charset=utf-8')
  res.end(JSON.stringify({ generatedAt: new Date().toISOString() }))
}).listen(3000)

設定値として指定できるのは整数だけです。CloudflareのOrigin Cache Controlのドキュメントは、max-age・s-maxage・stale-while-revalidateの値はRFC 9111に従って整数でなければならず、max-age=2.5のような小数は無効として扱われ、キャッシュそのものを素通りする可能性があると明記しています。設定値を計算で組み立てる実装では、Math.floorなどで整数に丸めてから出力します。

nginxで期限切れのキャッシュを返すためのバックグラウンド更新設定

CDNを使わず、nginxをリバースプロキシキャッシュとして前段に置く構成でも同じ挙動を作れます。nginxのngx_http_proxy_moduleのドキュメントによると、proxy_cache_background_updateは1.11.10で追加され、既定はoffです。期限切れの項目を返しながらバックグラウンドのサブリクエストで更新する指示で、更新中の古い応答の利用は、proxy_cache_use_stale updating、または有効なstale-while-revalidate応答ヘッダーで許可します。

proxy_cache_path /var/cache/nginx keys_zone=app:10m;

server {
    listen 8080;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_cache app;
        proxy_cache_valid 200 1m;
        # 更新中とオリジン障害時に古い応答を返す
        proxy_cache_use_stale updating error timeout http_500 http_502 http_503 http_504;
        # 期限切れの項目を裏側のサブリクエストで更新する
        proxy_cache_background_update on;
        # 同じキーの取得を1本にまとめ、オリジンへの同時アクセスを抑える
        proxy_cache_lock on;
        # キャッシュ状態(HIT・STALE・UPDATINGなど)を応答ヘッダーで確認する
        add_header X-Cache-Status $upstream_cache_status;
    }
}

同じドキュメントは、1.11.10以降は応答ヘッダーのstale-while-revalidateとstale-if-errorでも古い応答の利用を有効にでき、ただしディレクティブのパラメータより優先度が低いと書いています。上の設定のようにproxy_cache_use_staleを明示すると、オリジンのヘッダーよりnginx.confの指定が優先され、指定した条件ではヘッダーの猶予秒数を過ぎても古い応答を返し得ます。古さに上限がある用途では、この設定例をそのまま使わず、失効・パージの設計も必要です。ヘッダーだけに任せた場合にどこまで効くかは、後半のcurlの章に実測結果を載せています。

Service WorkerとWorkboxによるAPIや画像の再検証例

ブラウザ内で同じ戦略を明示的に組む方法もあります。Service Workerのキャッシュ戦略ライブラリWorkbox(workbox-strategiesは7.4.1系・2026年10月時点)は、公式ドキュメントでStaleWhileRevalidateを「キャッシュがあれば即応答し、ネットワークの応答でキャッシュを更新する」戦略として提供しています。

// sw.js(バンドラーでビルドしてService Workerとして登録する)
import { registerRoute } from 'workbox-routing'
import { StaleWhileRevalidate } from 'workbox-strategies'

// アバター画像は古くても困らないので、即応答して裏で更新する
registerRoute(
  ({ url }) => url.pathname.startsWith('/images/avatars/'),
  new StaleWhileRevalidate()
)

HTTPヘッダーのstale-while-revalidateとの違いは、猶予の秒数がない点です。Workboxのこの戦略はキャッシュの古さにかかわらず毎回再検証のリクエストを出すと公式ドキュメントが書いています。通信量を抑えたい場面ではHTTPヘッダー側で猶予を決め、オフライン対応が要る場面でService Workerを使う、という役割分担です。Service Workerの登録手順やマニフェストはPWAとは?Service Workerとマニフェストの実装手順・ネイティブアプリとの使い分けと採用判断を解説で扱っています。

ブラウザとCDN4社のstale-while-revalidate対応状況と挙動の違い

ブラウザの再検証対応版とstale-if-errorの実装上の制約

MDNのブラウザ互換データによると、応答ディレクティブとしてのstale-while-revalidateはChrome 75、Firefox 68、Safari 14から対応しています。いずれも2019年から2020年にかけてのリリースで、現行のブラウザであれば解釈されると考えて差し支えありません。一方stale-if-errorには同じ互換データの項目がなく、ブラウザ側の実装を前提にした設計は避けるべきです。エラー時のフォールバックはCDNかnginx、Service Workerの層で持たせます。

Cloudflare・CloudFront・Vercel・Fastlyの対応比較

CDNの層では4社とも両ディレクティブに対応していますが、効く条件が違います。CDNそのものの仕組みと選び方はCDNとは?仕組み・キャッシュ制御からサービスの選び方まで実装目線で解説にまとめています。

配信基盤 stale-while-revalidate stale-if-error 注意点
Amazon CloudFront 対応 対応(500〜600の応答) 最大TTLとの小さい方で頭打ち
Cloudflare 対応(完全非同期) 対応 Always Online有効時は両方無視
Vercel 対応(s-maxageと併記) 対応 proxy-revalidateは未対応
Fastly 対応 対応 Surrogate-Control内のs-maxageは非対応

同じヘッダーを返しても、どこまで古い応答を配るかは基盤側の設定に左右されます。CloudflareではAlways Onlineを有効にしているとstale-while-revalidateとstale-if-errorの指定が無視されます。Workersのcache.matchやcache.putを経由する場合もこのディレクティブは効きません。stale-while-revalidateは完全に非同期で、期限切れ後の最初のリクエストから古い応答がUPDATINGで即座に返り、オリジンの応答が届いた後はHITに戻ります。

VercelはCDN Cacheのドキュメント(2026年9月14日更新)で「Vercel’s CDN supports stale-if-error」と明記し、Cache-Control headersのページは500エラー・ネットワーク障害・DNSエラーの際に古い応答を返すと説明しています。未対応なのはproxy-revalidateです。

Fastlyのドキュメントでは、stale-while-revalidateとstale-if-errorを同時に書いた場合、どちらの期間もmax-ageが切れた同じ瞬間から数え始めます。段階的にずれていくわけではないため、公式が示す組み合わせは「stale-while-revalidateは短く、stale-if-errorは長く」です。オリジンが生きているときに極端に古い内容を配らず、落ちているときだけ長く耐える形になります。ブラウザには短い鮮度を、CDNには長いstale許容を与えたい場合はSurrogate-Controlを使いますが、Fastlyのこのヘッダーはs-maxageを解釈しない点に注意してください。

s-maxageとの併用条件がCloudflareとVercelで正反対になる理由と対処

Cloudflareが併用を禁じVercelが必須とするs-maxageの扱いの違い

配信基盤を移行するときは、s-maxageとstale-while-revalidateの併用条件を確認してください。Cloudflareのドキュメントは「s-maxageをstale-while-revalidateと併用しないでください」と注意し、理由としてRFC 9111でs-maxageがproxy-revalidateの意味を含むため、共有キャッシュがオリジンに再検証せずstaleな応答を配ることができなくなる点を挙げています。Cloudflare配下ではmax-age=600, stale-while-revalidate=30のようにmax-ageと組み合わせるのが公式の例です。

ところがVercelは逆です。VercelのCDNでFunctionsの応答をキャッシュさせるにはs-maxage=Nを含める必要があり、公式に提示されている組み合わせはs-maxage=N, stale-while-revalidate=Zおよびs-maxage=N, stale-while-revalidate=Z, stale-if-error=Zです。proxy-revalidateは現時点で未対応と明記されており、Cloudflareが警戒している意味論をそもそも実装していません。

// Vercel公式が示すRoute Handlerの例(app/api/cache-control-example/route.ts)
export async function GET() {
  return new Response('Cache Control example', {
    status: 200,
    headers: { 'Cache-Control': 's-maxage=1, stale-while-revalidate=59' }
  })
}

つまり「s-maxageとstale-while-revalidateを併用すべきか」に一般解はありません。RFCの意味論を厳密に適用する基盤では併用が無効化され、Vercelのようにs-maxageをキャッシュ判定の入口にしている基盤では併用が前提になります。判断基準は配信先のドキュメントです。他社の設定例をそのまま持ち込むと、保存自体は行われても期限切れ後のstale配信が無効になり、再検証待ちが発生する場合があります。

Next.jsのISRが出力するキャッシュ指示とCDNごとの配信挙動

この食い違いは、フレームワーク側が出力するキャッシュ指示にも関わる問題です。Next.jsのISRガイドは、revalidateの秒数とexpireTimeからCache-Controlを組み立てる仕様を説明しており、expireTimeを1時間、対象パスのrevalidateを15分にした場合に生成される値をs-maxage=900, stale-while-revalidate=2700と明記しています。Vercel上では想定どおり動く一方、同じ成果物をCloudflare配下に置くとs-maxageが併記されているためstale配信が無効になり得ます。この場合に直接変わるのはCloudflareでのstale配信であり、Next.jsサーバー内のISR再生成が無効になるわけではありません。

Cloudflare配下でNext.jsを配信する場合は、CDN向けの指示をCDN-Cache-Controlなどの別ヘッダーへ分けるか、Cloudflare側のキャッシュルールで上書きするかを先に決めます。ページ側のキャッシュ制御はNext.jsのキャッシュ|16.4のuse cache・revalidateTagの使い分けとCDNで効かない原因と合わせて設計すると、重複した指定を避けられます。

VercelでCDN-Cache-Controlを付けずに返すとブラウザへ届かない指示

もう1つVercel固有の落とし穴があります。CDN-Cache-Controlを設定せずにCache-Controlだけを返すと、VercelのCDNはブラウザへ送る前にs-maxageとstale-while-revalidateを取り除きます。ブラウザキャッシュにも同じ挙動をさせたい場合に必要なのは、CDN向けとブラウザ向けのヘッダーを分けた指定です。Vercelの公式例では、Cache-Control: public, s-maxage=1・CDN-Cache-Control: public, s-maxage=60・Vercel-CDN-Cache-Control: public, s-maxage=3600の3つを並べ、届け先ごとに秒数を変えています。

curlで応答ヘッダーとキャッシュ状態を確かめる検証手順と見るべき値

curlのGET要求3回でキャッシュ状態ヘッダーと生成時刻の変化を読む手順

ヘッダーを書いただけでは効いているか分かりません。期限切れの前後で3回GETリクエストを送り、キャッシュ状態ヘッダーと本文の生成時刻の変化を見ます。-I(HEAD要求)では本文が返らず生成時刻を比べられないため、-iでヘッダーと本文を両方表示します。前章のNode.jsサーバーとnginxを起動した状態なら、次のコマンドでそのまま確認することが可能です。CDN配下で確かめるときは、URLを自社の公開URLに置き換えます。

# 1回目:キャッシュが空なのでMISS。本文のgeneratedAtを控えておく
curl -sS -i http://localhost:8080/

# freshの期間(この例では60秒)を過ぎてから2回目を送る
sleep 65
curl -sS -i http://localhost:8080/

# 直後の3回目:裏側の更新が終わっていればHITに戻り、generatedAtが新しくなる
curl -sS -i http://localhost:8080/

2回目でキャッシュ状態が「期限切れだがキャッシュから返した」値になり、本文のgeneratedAtが1回目と同じ時刻なら、古い応答を即返して裏で更新している証拠です。3回目で時刻が新しくなっていれば、バックグラウンドの再検証が完了しています。3回目がUPDATINGのときは更新がまだ終わっていないので、少し待ってからもう一度送ります。2回目がMISSやEXPIREDのままなら、猶予の秒数が短すぎるか、基盤側の設定(CloudflareのAlways Online、s-maxageの併記、nginxのproxy_cache_background_updateの書き忘れなど)で無効化されています。

キャッシュ状態ヘッダーのUPDATINGとSTALEが示す更新状況

キャッシュ状態を示すヘッダー名と値は基盤ごとに異なります。古い応答を返しながら裏で更新している状態は、次の値で表れます。

基盤 見るヘッダー 裏で更新中の値 同期の再検証
Cloudflare CF-Cache-Status UPDATING REVALIDATED
Vercel x-vercel-cache STALE REVALIDATED
nginx X-Cache-Status(自分で付与) STALE・UPDATING EXPIRED

Cloudflareのキャッシュ応答の説明は、REVALIDATEDはリクエストがオリジンの応答を待つ同期の経路で、stale-while-revalidateが設定されていないときやmust-revalidate・no-cacheで古い応答が禁じられているときに出ると書いています。CloudflareではSTALEは「オリジンに接続できず期限切れの応答を返した」状態を指し、VercelのSTALEとは意味が違う点も読み違えやすいところです。Vercelの値の定義はVercelのレスポンスヘッダーの説明にあります。nginxのREVALIDATEDはproxy_cache_revalidate onで条件付きリクエストを送り、オリジンが304を返したときの値で、期限切れの応答をオリジンから取り直して待った場合はEXPIREDになります。

ブラウザの開発者ツールで確かめるときは「キャッシュを無効化」のチェックに注意します。Vercelのドキュメントは、多くの開発者ツールが既定でpragma: no-cacheを送り、そのときは同期の再検証になってx-vercel-cacheがREVALIDATEDになると説明しています。開発者ツールで毎回待たされるのに本番ユーザーでは速い、という食い違いはこれが原因です。

nginx 1.31.8で実測したSTALE・UPDATING・EXPIREDの出方とbackground_updateの差

nginxについては、設定の違いで状態がどう変わるかを手元で測りました(2026年11月6日、macOS上のnginx 1.31.8・Node.js v26.5.0・curl 8.7.1)。オリジンは応答に1秒の遅延を入れ、Cache-Control: max-age=2, stale-while-revalidate=6, stale-if-error=30を返します。nginx側はproxy_cacheだけを書いた設定(A)と、それにproxy_cache_background_update onを足した設定(B)の2つで、どちらもproxy_cache_use_staleは書いていません。

要求のタイミング A:ヘッダーのみ B:background_update on
初回 MISS・1.03秒 MISS・1.04秒
max-age切れ直後の1本目 EXPIRED・1.02秒(新しい応答) STALE・0.018秒(古い応答)
その0.2秒後の2本目 UPDATING・0.001秒(古い応答) UPDATING・0.001秒(古い応答)
swr窓の経過後・オリジンが503 503がそのまま返る 503がそのまま返る
swr窓の経過後・オリジン停止 STALE・古い応答で200 STALE・古い応答で200
30秒のsie窓も経過・オリジン停止 502 502

ヘッダーのstale-while-revalidateだけでは、期限切れ後の最初の要求はオリジンの応答を待ちます。古い応答が返るのは、その取得が終わる前に届いた後続の要求(UPDATING)だけです。アクセスがまばらなページでは後続の要求がほとんど来ないため、待ち時間はほぼ減りません。最初の要求から待たせないにはproxy_cache_background_update onが必要です。

nginxのSTALEとUPDATINGは役割が分かれています。Bでは更新のきっかけになった要求がSTALE、更新中に届いた要求がUPDATINGでした。Cloudflareのドキュメントは期限切れ後の最初の要求からUPDATINGを返すと書いているので、同じ「裏で更新中」でも基盤によって値が揃いません。アクセスログでUPDATINGだけを数えると、nginxではバックグラウンド更新を起こした要求を数え落とします。

ヘッダーのstale-if-errorは、接続拒否には効き、オリジンが返した503には効きませんでした。nginxのソースngx_http_upstream.cでは、ヘッダー由来のフラグ(stale_error)は接続エラーやタイムアウトで次の処理へ移る経路でだけ参照され、ステータスコードで古い応答に切り替える経路はproxy_cache_use_staleの指定しか見ていません。RFC 5861の4節は500・502・503・504になる状況をすべて「エラー」に含めているので、nginxの解釈はそれより狭いことになります。アプリが落ちて503を返す障害やメンテナンス中の503で古い応答を返したいなら、前掲の設定例のようにproxy_cache_use_staleへhttp_500 http_502 http_503 http_504を明示します。max-age切れ直後の挙動は、間隔を変えた2回の測定で同じ結果でした。

Reactでstale-while-revalidateを使うSWRの既定値と再検証の状態管理

再検証のトリガーとdefaultConfigの既定値(SWR 2.5.1系時点)

Vercelが公開しているReact向けデータ取得ライブラリSWRは、この戦略の名前をそのまま冠しています。npm registryで確認した最新版は2026年11月6日時点でも2.5.1(2026年8月12日公開・MITライセンス・peerDependenciesはreact ^16.11/^17/^18/^19)です。HTTPヘッダーがCDNやブラウザのキャッシュに効くのに対し、SWRが制御するのはJavaScriptのメモリ上のキャッシュで、設定場所も効く範囲も別物です。

再検証がいつ走るかは、SWR 2.5.1のソースsrc/_internal/utils/config.tsにあるdefaultConfigの既定値で決まります。各オプションの公式説明はSWRのAPIドキュメントにあります。

オプション 既定値 役割
revalidateIfStale true キャッシュがある状態でマウントしても再検証
revalidateOnFocus true タブがフォーカスされたら再検証
revalidateOnReconnect true ネットワーク復帰で再検証
dedupingInterval 2000ms 同一キーの重複リクエストを束ねる
focusThrottleInterval 5000ms フォーカス再検証の間隔
errorRetryInterval 5000ms エラー時の再試行の基準間隔
loadingTimeout 3000ms onLoadingSlowが発火するまで
shouldRetryOnError true エラー時に再試行するか

この表で見落とされやすいのがrevalidateIfStaleです。通常の構成では、既定のtrueによりキャッシュがあってもマウント時の再検証が有効になります。ただし、明示したrevalidateOnMountが優先され、リクエストの重複排除なども適用される仕組みです。falseにするとキャッシュがある間は再取得せず、mutateやフォーカスなど別のトリガーがない限り古い値を返し続けます。更新頻度に加え、再マウント時の再取得が必要か、mutateなど別の更新経路を設けているかで判断します。

なおerrorRetryIntervalとloadingTimeoutは回線速度で切り替わります。navigator.connection.effectiveTypeがslow-2gか2g、またはsaveDataが真のとき、それぞれ10,000msと5,000msになります。開発機では再現しにくい挙動なので、低速回線の検証時は数値が変わる前提で読んでください。

isLoadingとisValidatingの使い分けとスケルトン表示の分岐例

ローディング表示でつまずくのはこの2つの違いです。isLoadingは現在のキーについて取得済みデータがなく、リクエストが進行中のときにtrueになります。キー変更後の取得や初回取得失敗後の再試行でもtrueになり得て、fallbackDataやkeepPreviousDataによる表示値は取得済みデータに含みません。isValidatingは初回ロードやfetcherによる再検証中にtrueになります。Promiseを渡したmutateの更新処理を待っている間は、それだけではtrueになりません。

import useSWR from 'swr'

const fetcher = async (url) => {
  const res = await fetch(url)
  if (!res.ok) {
    const error = new Error(`HTTP ${res.status}`)
    error.status = res.status
    throw error
  }
  return res.json()
}

export function Profile() {
  const { data, error, isLoading, isValidating } = useSWR('/api/user', fetcher)
  if (error && !data) return <p>読み込みに失敗しました</p>
  if (isLoading) return <p>読み込み中</p>
  // dataは表示したまま、再検証中だけ控えめな印を出す
  return (
    <div>
      {data.name}
      {isValidating && <span>更新中</span>}
    </div>
  )
}

スケルトン表示の分岐はisLoadingで行い、isValidatingは既に表示している内容の上に小さな更新中表示を重ねる用途に向きます。isValidatingでスケルトンに切り替えると、フォーカスのたびに画面が消えることになります。

mutateによる手動再検証とキー共有で重複リクエストを束ねる仕組み

ユーザーの操作直後など、トリガーを待たずに更新したい場面で使うのがmutateです。同じキャッシュプロバイダー内の同一キーを持つフックはキャッシュを共有し、再検証結果が各フックに反映されます。以下のimportしたmutateは既定のキャッシュが対象で、独自プロバイダー内ではuseSWRConfigからmutateを取得します。

import useSWR, { mutate } from 'swr'

// 同じキーのuseSWRがマウントされていれば、別コンポーネントからも再検証できる
await mutate('/api/user')

// 楽観的更新:先に新しい値を描画し、裏で再検証する
await mutate('/api/user', updateUser(newName), {
  optimisticData: { name: newName },
  revalidate: true
})

再検証中も表示は直前の値のまま維持され、取得完了後に差し替わります。これがライブラリ側で再現されたstale-while-revalidateの動きです。useSWRそのものの構文やオプション設定はuseSWRとは?使い方とfetcher・mutate・オプション既定値を解説【SWR 2.5対応】で扱っています。

SWRとTanStack Queryで古いデータを返す期間の決め方の違い

Reactで同じ戦略を取るもう1つの定番がTanStack Query(@tanstack/react-query)です。どちらもキャッシュ済みの値を先に描画して裏で取り直しますが、「いつまでを新しいとみなすか」の持ち方が違います。既定値はSWR 2.5.1と@tanstack/query-core 5.106.1のソースで確かめました。

項目 SWR 2.5.1 TanStack Query 5.106.1
新しいとみなす期間 設定項目なし staleTime(既定0)
マウント時の再取得 revalidateIfStale: true refetchOnMount: true(古いときだけ)
フォーカス時の再取得 revalidateOnFocus: true refetchOnWindowFocus: true(古いときだけ)
同時要求のまとめ方 取得中+完了後2秒 取得中の要求を共有
エラー時の再試行 上限なし(errorRetryCount未設定) 3回(サーバー側は0回)

HTTPに置き換えると、TanStack QueryのstaleTimeがmax-ageに当たります。既定の0では取得した瞬間から古い扱いになり、マウントやフォーカスのたびに取り直します。staleTime: 60_000にすれば、60秒間はマウントしても通信は発生しません。refetchOnMountなどを'always'にすると、新しい間も取り直します。また、手動のrefetch、invalidateQueriesによる無効化、refetchIntervalによるポーリングは、staleTimeを設定しても実行されます。

SWRにはmax-ageに当たる設定がありません。キャッシュは常に古い扱いで、マウント・フォーカス・再接続のたびに再検証します。通信を間引くのは、取得中と取得完了から2秒間の要求を1本にまとめるdedupingIntervalと、フォーカス再検証の間隔を5秒空けるfocusThrottleIntervalだけです(src/index/use-swr.tsは取得完了後にsetTimeout(cleanupState, config.dedupingInterval)で共有を解除します)。一定時間は取り直したくない画面では、SWRならrevalidateIfStaleとrevalidateOnFocusを切り、時間で管理したいならTanStack QueryのstaleTimeで設計するほうが意図をそのまま書けます。v5の使い方全般はTanStack Queryとは?React Queryとの違い・v5の使い方と既定値の落とし穴で扱っています。

SWRのエラー再試行と打ち切り条件

指数バックオフの待ち時間とerrorRetryCountによる再試行回数の制限

クライアント側のSWRでは、fetcherの失敗に対して再試行を設定します。shouldRetryOnErrorが既定でtrueのため、fetcherが失敗すると指数バックオフで再試行します。待ち時間はMath.floor((Math.random() + 0.5) * 2 ** Math.min(リトライ回数, 8)) * errorRetryIntervalミリ秒で、指数部分はリトライ8回で頭打ちになります。注意すべきはerrorRetryCountに数値の既定値がない点で、APIドキュメントでも既定値なしの「max error retry count」としか書かれていません。指定しない限り再試行の上限がないため、障害中のAPIに対して叩き続けないよう、認証エラーなど回復しないステータスではshouldRetryOnErrorを落とすかerrorRetryCountを明示してください。

import { SWRConfig } from 'swr'

export function AppProviders({ children }) {
  return (
    <SWRConfig value={{
      errorRetryCount: 3,
      // 401・403・404は再試行しても回復しないので打ち切る
      onErrorRetry: (error, key, config, revalidate, { retryCount }) => {
        if ([401, 403, 404].includes(error.status)) return
        if (retryCount > config.errorRetryCount) return
        setTimeout(() => revalidate({ retryCount }), 5000)
      }
    }}>
      {children}
    </SWRConfig>
  )
}

onErrorRetryを自分で書くと既定の指数バックオフは使われず、ここで決めた5秒間隔になります。前節のfetcherでerror.statusを持たせておくと、この分岐でステータスごとに扱いを変えられます。

stale-while-revalidateを採用する条件と付けてはいけない応答の判断基準

採用する条件:数秒から数分の古さを許せる一覧・記事・画像の配信

付けるべきかどうかを決める判断基準は、「利用者が古い値を見て困るか」です。記事本文、商品一覧、検索結果、ランキング、アバター画像のように、数十秒から数分古くても判断を誤らない応答には付けます。この種の応答では、古いキャッシュを返すことで再検証待ちを隠せます。同時要求がまとまる範囲はキャッシュキーや配信拠点、実装に依存し、オリジンへのアクセスが全体で1本になる保証はありません。

猶予の秒数は、更新頻度ではなくアクセス間隔から逆算します。1時間に数回しか読まれないページにstale-while-revalidate=30を付けても、ほぼ毎回猶予切れの帯に入って効果が出ません。ただし、通常時に利用者が目にする古さの上限はmax-ageと猶予の秒数の合計です。アクセスの少ないページで猶予を長く取るなら、その分max-ageを短くして、合計が許容できる古さに収まるように設計します。

見送る場面:在庫数・残高・ログイン状態で変わる応答とprivateの扱い

在庫数、口座残高、予約枠、決済状態のように、古い値を見せると利用者が誤った操作をする応答には付けません。ここで古い応答を返すと、「在庫ありと表示されたのに注文で失敗する」という問い合わせに直結します。更新直後に必ず反映させたいコンテンツも同様で、CDNのパージとアプリ側の無効化を設計します。Next.jsのrevalidateTagは'max'指定では古い値を返すため、即時失効が必要ならServer ActionsではupdateTag、Route HandlersではrevalidateTag(tag, { expire: 0 })を使い分けます。

ログイン状態で中身が変わる応答は、そもそも共有キャッシュに載せません。Cache-Control: privateは共有キャッシュへの保存を禁止します。ただし、CloudFrontでは最小TTLが0より大きいとprivateがあっても保存されるため、個別応答を扱う配信経路ではCDN側のキャッシュ設定も確認します。ブラウザにも保存させない場合はno-storeを指定します。Vercelのドキュメントは、Vary: Cookieのようにほぼ利用者ごとに値が変わるヘッダーを指定した応答はCDNに保存しないとも書いています。stale-while-revalidateは、ブラウザの私有キャッシュにも共有キャッシュにも適用できます。共有キャッシュでは応答を共有できる範囲を確認し、どちらの場合も指定期間の古さを許容できる応答に限って使います。

CDN・Next.js・クライアントの3層にまたがるキャッシュ設計を含め、業務Webアプリの構築や改修を外部に相談したい場合は、一創の業務用・Webアプリ開発で要件整理から対応しています。

stale-while-revalidateとReact SWRに関するよくある質問

stale-while-revalidateの意味、SWRの設定、CDNでの扱いについて、検索の多い質問に答えます。

stale-while-revalidateとはどういう意味ですか?

「期限切れ(stale)の応答を返しながら、その裏で再検証(revalidate)する」という意味です。RFC 5861が定めるCache-Control拡張で、指定した秒数のあいだは期限切れのキャッシュを即座に返すことが許されます。待ち時間を削る代わりに、一時的に古いデータが表示されることを受け入れる設定です。

revalidateIfStaleをfalseにすると何が変わりますか?

キャッシュに値があるときのマウント時の再検証が止まり、フォーカスやネットワーク復帰、mutateなど別のトリガーが来るまで古い値のままになります。revalidateOnMountを明示している場合はそちらが優先されます。更新頻度が低いデータで、マウントのたびの通信を減らしたいときに使います。

SWRのrefreshIntervalとstale-while-revalidateはどう違いますか?

refreshIntervalは指定した間隔で定期的にポーリングする設定で、既定では無効です。stale-while-revalidateは時間で定期実行するのではなく、アクセスやマウントといったイベントを契機に「古い値を返しつつ取り直す」挙動を指します。一定間隔で更新したい画面ではrefreshIntervalを併用できます。ただしポーリング間隔中の変更は即時には反映されず、常時最新を保証する設定ではありません。

stale-if-errorはブラウザでも効きますか?

前提にできません。MDNのブラウザ互換データにstale-if-errorの項目がないためです。CloudFront・Cloudflare・Fastly・VercelはCDNでの対応を明記しているので、オリジン障害時のフォールバックはCDNかnginxの層で設定し、本番の応答ヘッダーで効いていることを確かめます。

Next.jsのISRとstale-while-revalidateは同じものですか?

考え方は同じですが、動く場所が違います。ISRは生成済みページをサーバー側で再生成する仕組みで、Cache-Controlディレクティブとしてのstale-while-revalidateはCDNやブラウザのキャッシュに対する指示です。ただし両者は無関係ではなく、ISRはs-maxageとstale-while-revalidateを含むCache-Controlを出力してCDNに古い応答を配らせます。詳しくはNext.jsのレンダリング方式|SSG・ISR・SSR・CSRの決まり方と16.4のCache Componentsを参照してください。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2025.12.19 コラム アンダーマイニング効果とは?具体例と報酬でやる気が下がる条件、エンハンシング効果との違い
  2. 2026.11.20 テックブログ MAI Code 2とは?Flashとの違い・料金・GitHub Copilotでの使い方【2026年11月】
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.20 テックブログ 六花亭の不正アクセス:決済画面の改ざんでカード情報約8,000件、対象期間と改ざん検知の手順【11月20日時点】
  5. 2026.11.20 テックブログ 福岡銀行の不正アクセス:FFGインダストリーズ1,221先の漏えい可能性と、分析ツールに認証情報を渡さない実装

RELATED POSTS 関連記事

目次