Next.js の再検証｜revalidateTag と updateTag

キャッシュを置いた瞬間から「いつ捨てるか」という問題が生まれます。長すぎれば古い情報が出続け、短すぎればキャッシュの意味がありません。Next.js はこれを「時間で切る」と「出来事で切る」の 2 系統で扱います。この記事では両者の使い分けと、バージョン 16 で追加・変更された API を整理します。

1時間で切る — cacheLife の 3 つの値

cacheLife は 'use cache' のスコープ内で呼び、そのキャッシュの寿命を決めます。指定するのは 3 つの時間です。

この 3 つを毎回考えるのは大変なので、名前付きのプリセットが用意されています。

// app/blog/[slug]/page.tsx
import { cacheLife } from 'next/cache'

export default async function BlogPost() {
  'use cache'
  cacheLife('days')          // ブログ記事は日次更新

  const post = await fetchBlogPost()
  return <article>{post.content}</article>
}

プリセットが合わない場合は、next.config.ts で独自の名前を定義するか、その場でオブジェクトを渡します。省略したプロパティは default から引き継がれます。

// next.config.ts
const nextConfig = {
  cacheComponents: true,
  cacheLife: {
    editorial: {
      stale: 600,        // 10 分
      revalidate: 3600,  // 1 時間
      expire: 86400,     // 1 日
    },
  },
}
export default nextConfig

cacheLife は毎回書くことが推奨されています。省略しても動きますが、入れ子になったキャッシュがあると、外側の寿命が内側に引っぱられて短くなることがあり、追いにくくなるためです。

2出来事で切る — cacheTag

「記事を編集したら、その記事のキャッシュだけを捨てたい」という要求は時間では表現できません。この場合はキャッシュにタグを付けます。

import { cacheLife, cacheTag } from 'next/cache'

async function getPost(slug: string) {
  'use cache'
  cacheLife('days')
  cacheTag(`post-${slug}`)     // このエントリの目印

  return await fetchPost(slug)
}

あとは更新処理の中で、そのタグを指定して無効化します。タグは複数付けられるので、「この記事」と「記事一覧」の両方を同時に狙うこともできます。

3revalidateTag と updateTag の違い

ここがバージョン 16 で最も間違えやすい部分です。似た名前の 2 つは、目的がはっきり分かれています。

revalidateTag はバージョン 16 で第 2 引数が必須になりました。ここには cacheLife のプロファイル名を渡します。

// 旧: revalidateTag('posts')
revalidateTag('posts', 'max')

updateTag は Server Actions の中でのみ使える API で、キャッシュを失効させたうえで同じリクエストの中で作り直します。ユーザーが自分の変更をすぐ確認できる、いわゆる read-your-writes の挙動になります。

// app/actions.ts
'use server'

import { updateTag } from 'next/cache'

export async function updateUserProfile(userId: string, profile: Profile) {
  await db.users.update(userId, profile)
  updateTag(`user-${userId}`)   // 即座に反映される
}

4revalidatePath と refresh

タグを付けていない場合や、URL 単位でまとめて捨てたい場合は revalidatePath が使えます。これは内部的にはタグ機構の上に乗った便利関数で、そのパス用の特別なタグを無効化しています。

'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  // データを更新する処理
  revalidatePath('/posts')
}

もう一つ、refresh という API があります。これはクライアント側のルーターを更新するだけで、タグ付きキャッシュの再取得は行いません。ヘッダーの通知件数を更新したい、といった軽い用途向けです。

5寿命の短さが描画に与える影響

寿命の指定は「いつ作り直すか」だけでなく、「事前生成に含められるかどうか」にも影響します。

• revalidate が 0、または expire が 5 分未満 → 事前生成から外れ、リクエスト時に解決される
• stale が 30 秒未満 → 先読みしても届く前に期限切れになるため、事前生成から外れる

プリセットの中では seconds だけがこの条件に当たります。リアルタイム性の高い部分を seconds にする場合は、Suspense で包んでフォールバックを用意しておくのが自然な構成になります。

6つまずきやすいところ

• revalidateTag('posts') が型エラーになる：バージョン 16 では第 2 引数が必須です。
• 更新したのに画面が変わらない：revalidateTag は古い内容を見せたまま裏で更新します。即時反映が必要なら updateTag です。
• 複数インスタンスで反映されない：既定ではタグの無効化は呼ばれたインスタンスにしか効きません。複数台構成では共有ストアとタグ同期の仕組みが要ります（本番ビルドとセルフホスト）。
• 入れ子のキャッシュで寿命が縮む：外側に cacheLife を明示していないと、内側の短い寿命に引っぱられます。外側にも必ず書きます。

読み取り側の設計はここまでです。次は書き込み、つまりフォーム送信とデータ更新に進みます。