キャッシュの話：maxAge と stale をやさしく理解する

サイトが microCMS の「コピー」をどれくらいの間使うか（maxAge）と、期限切れ後に古いデータを返すか（stale/SWR）の違い。記事一覧がいつ見えるか、ベストプラクティスもまとめました。

5歳向けに言うと

maxAge = 「同じコピーをどれくらい使うか」

  • サイトは誰かがページを開くたびに microCMS に聞いていない。
  • 一覧のコピーを取っておいて、しばらくそのコピーを使う。
  • maxAge: 1時間 = 「このコピーを1時間使う」という意味。

だからその一覧では、毎秒 microCMS を見ているのではなく、保存したコピーを見ている。

新しい記事は1時間後にしか出ない？

どのページかによる。

  1. 「list-no-stale」を使うページ（例: /news-no-stale）
    • その一覧は1時間キャッシュされる。
    • なのではい：microCMS で新しく作った記事は、キャッシュが切れるまで最大1時間出ないことがある。
  2. それ以外のページ（メインの News / Articles）
    • CDN のキャッシュは1分（60秒）にしている。
    • 新しい記事はおおむね1分以内、またはユーザーがリロード／遷移して refetch すれば表示される。

まとめ：1時間なのは list-no-stale のエンドポイント（とそれを使うページ）だけ。約1分なのはメインの news/articles 一覧。

maxAge と stale（swr）の違い

maxAge（例: 60×60 = 1時間）

  • キャッシュが「新鮮」とみなされる時間（秒）。
  • その間：ハンドラはキャッシュを返し、microCMS は呼ばない。
  • 過ぎたら：キャッシュは期限切れ。

stale（swr で制御）

  • 期限切れ後にどうするか。
    • swr: true（デフォルト）：古い（stale）レスポンスを一度返しつつ、裏で再取得してキャッシュを更新。ユーザーは1回古い内容を見る可能性あり。
    • swr: false（list-no-stale で使用）：古いキャッシュは返さない。次のリクエストは microCMS の新規取得を待ってから返す。

list-no-stale では：maxAge = 1時間はキャッシュを使う。stale = 1時間過ぎたら古いキャッシュは使わず、必ず新しいデータを取る（swr: false）。

記事・ニュースでのよくあるベストプラクティス（Nuxt 4 / NuxtHub / microCMS）

  • 一覧・詳細 API：キャッシュして microCMS を毎回叩かない。ニュースっぽくしたいなら maxAge を短く（1〜5分）か SWR オンで「速い＋徐々に最新」にする。
  • SWR：記事・ニュースでは swr: true（Nitro のデフォルト）＋ maxAge 60〜300秒がよくある。古いキャッシュを返しつつ裏で再検証。
  • Webhook：microCMS で公開・更新したら、webhook でキャッシュを無効化すると、maxAge を長くしても新記事を早く出せる。
  • フロント（Nuxt 4）：useFetch で安定した key を使い、一覧・詳細ページに遷移したときに refresh() すると、リロードなしで更新が見える。
  • CDN：API に Cache-Control（例: s-maxage）を付け、必要なら CDN でも stale-while-revalidate にする。

実務では：一覧・詳細は短い maxAge ＋ SWR オン。「no stale」の比較用だけ maxAge ＋ swr: false。 公開後の更新を早くしたければ microCMS の webhook でキャッシュ削除。

← ニュース一覧に戻る