テーマ: {theme}
} ``` next@16.4.0でビルドすると、このルートは`◐ /blog 1h 1d`（Partial Prerender、Revalidate 1時間、Expire 1日）と表示されました。Cookieを読んでもルート全体が動的レンダリングに倒れることはなく、見出しと記事一覧は静的シェルに入ります。`cookies()`や`headers()`を`use cache`の内側で読むことはできないので、外で値を取り出して引数で渡します。 ### cacheLifeのプリセット値と短命キャッシュの扱い `cacheLife`は`stale`（クライアントが確認なしで使える時間）、`revalidate`（サーバーが背後で作り直すまでの時間）、`expire`（アクセスが無いまま経過したら同期再生成に切り替わる時間）の3つを持ちます。next@16.4.0の実装（`dist/server/config-shared.js`）の値は次のとおりで、[cacheLifeのリファレンス](https://nextjs.org/docs/app/api-reference/functions/cacheLife)の表とも一致します。 | プロファイル | stale | revalidate | expire | | ------- | ----- | ---------- | ------ | | default | 5分 | 15分 | 期限なし | | seconds | 30秒 | 1秒 | 1分 | | minutes | 5分 | 1分 | 1時間 | | hours | 5分 | 1時間 | 1日 | | days | 5分 | 1日 | 1週間 | | weeks | 5分 | 1週間 | 30日 | | max | 5分 | 30日 | 1年 | 寿命が短すぎるキャッシュはプリレンダーから外れます。`revalidate`が0か`expire`が5分未満なら、リクエスト時に解決される「動的な穴」になり、プリセットでは`seconds`だけが該当します。`stale`が30秒以上5分未満なら、プリレンダーには入りますが、プリフェッチで配るApp Shellからは外れます。入れ子にも注意が要ります。`cacheLife`を書いていない外側の`use cache`が短命キャッシュを含むと、外側まで短命化するのを防ぐためにビルドがエラーで止まります。外側に`cacheLife`を明示すれば解決します。 ### use cache・private・remoteの選び分け | ディレクティブ | サーバー保存 | cookies等 | 向く用途 | | ------------------ | ---------- | -------- | ----------- | | use cache | インスタンスのメモリ | 不可 | 全員共通のデータ | | use cache: remote | 共有ハンドラ | 不可 | ヒット率が高い重い処理 | | use cache: private | しない | 可 | ユーザー固有の表示 | remoteは毎回ネットワーク往復が入るので、ヒット率が高いときしか元が取れません。privateの結果はブラウザのメモリにだけ残り、再読み込みで消えます。まずはCookieの値を外で読んで`use cache`の引数に渡す形を試し、書けないときだけprivateを使います。 ### ensureStaticによる静的レンダリングの保証 16.4で追加された`export const ensureStatic = 'navigation'`をページやレイアウトに書くと、そのルートに動的な部分が紛れ込んだ時点でビルドが失敗します。上の`/blog`に付けて試すと、Cookieを読む`Theme`のせいで`Next.js encountered uncached or runtime data on a route that must be fully static.`というエラーで止まりました。値は`'shell'`・`'prefetch'`・`'navigation'`の順に厳しくなります。 ## 再検証APIの使い分け 16では再検証APIの役割が整理されました。`fetch`の`next.tags`で付けたタグにも`cacheTag`で付けたタグにも同じように効き、`cacheComponents`の有無を問わず使えます。 | API | 呼べる場所 | 次の読み取り | 使う場面 | | --------------------------------- | --------------------------- | ------------ | ----------- | | revalidateTag(tag, ‘max’) | Server Action・Route Handler | 旧データを返し背後で更新 | Webhook・一覧 | | revalidateTag(tag, { expire: 0 }) | Server Action・Route Handler | 新データを待つ | 外部からの即時削除 | | updateTag(tag) | Server Actionのみ | 新データを待つ | フォーム送信・設定変更 | | revalidatePath(path) | Server Action・Route Handler | パス単位で無効化 | タグ設計の無いルート | | refresh() | Server Actionのみ | 未キャッシュ部分だけ更新 | 通知件数 | ``` 'use server' import { revalidateTag, updateTag, refresh } from 'next/cache' import { db } from '@/lib/db' type Profile = { name: string } export async function publishPost(id: string) { await db.posts.publish(id) revalidateTag('posts', 'max') } export async function saveProfile(id: string, data: Profile) { // 認証・更新権限・入力値の検証はここか db 層で行う前提 await db.users.update(id, data) updateTag(`user-${id}`) } export async function markAsRead(id: string) { await db.notifications.markAsRead(id) refresh() } ``` 判断の基準は「更新した本人にすぐ見せる必要があるか」です。フォーム送信のように本人が結果を確認する導線では、読み取り直しを保証する`updateTag`を選びます。記事一覧のように多少の遅れが許されるものは`revalidateTag`に`'max'`を渡し、閲覧者には旧データを即座に返しながら背後で作り直させます。仕組みは[stale-while-revalidateとは？Cache-ControlとSWRの再検証を解説](/tech/details/7774/)を参照してください。 第2引数は省略できません。`revalidateTag('posts')`と書いてビルドすると、16.4では`error TS2554: Expected 2 arguments, but got 1.`で型チェックが通りませんでした。型エラーを抑えれば動きますが、挙動は`{ expire: 0 }`と同じになります（[revalidateTagのリファレンス](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)）。 ## CDNのキャッシュ可否とHTML・RSCのパージ対象 サーバーキャッシュを正しく書いても、手前のCDNが別の判断をすれば古い画面は出続けます。next@16.4.0を`next start`で起動して確かめたヘッダーが次の表です。 | ルート | Cache-Control | | ------------------------ | ------------------------------------------------------- | | use cacheだけの静的ページ（hours） | s-maxage=3600, stale-while-revalidate=82800 | | Suspenseで動的部分を含むページ | private, no-cache, no-store, max-age=0, must-revalidate | | /\_next/static配下のJS | public, max-age=31536000, immutable | 静的ページの`stale-while-revalidate`は、`expire`（1日）から`revalidate`（1時間）を引いた値です。一方、動的な部分を1つでも含むPPRのページは、静的シェルがプリレンダー済みでもHTMLのレスポンスに`private, no-store`が付き、一般的なCDNはこれをキャッシュしません。公式は静的シェルをCDNから直接配信できると説明していますが、それはPPRに対応したデプロイ先やアダプターでシェルを分けて配る場合の話です。`next start`の前にCDNを置くだけの構成でページをCDNに載せたいなら、そのルートを完全に静的にします。 逆に、CDNがキャッシュしている静的ページでは`revalidateTag`や`revalidatePath`がCDNまで届きません。公式の[CDN Cachingガイド](https://nextjs.org/docs/app/guides/cdn-caching)も、CDNは`s-maxage`が切れるまで手元の複製を返し続けるので、再検証と同時にCDNのパージAPIを呼ぶよう案内しています。パージ対象にはHTMLとRSCの両方が要ります。RSCのリクエストはクエリ`_rsc`で区別され、実測では`rsc: 1`ヘッダーだけのリクエストに`?_rsc`付きURLへの`307`が返りました。クエリをキャッシュキーから外すCDNでは画面遷移が壊れます。CDN側の設定の考え方は[CDNとは？仕組み・キャッシュ制御からサービスの選び方まで実装目線で解説](/tech/details/13095/)を参照してください。 ### Cache-Controlの全パス一括指定による長期キャッシュの危険 `headers()`で全パスに長いキャッシュ期間を付ける例を見かけますが、採用すべきではありません。 ``` // 採用しないこと module.exports = { async headers() { return [{ source: '/(.*)', headers: [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }], }] }, } ``` この値は本来、ファイル名にハッシュを含む不変アセットにNext.jsが自動で付けるもので、公式はそのアセットについては上書きできないと書いています（[headersのリファレンス](https://nextjs.org/docs/app/api-reference/config/next-config-js/headers)）。問題は残りのパスです。15以降のNext.jsはカスタムの`Cache-Control`を既定値で上書きしなくなったため、HTMLページにも書いた値がそのまま出ます。`immutable`付きなので再検証も行われず、一度アクセスした人には何度デプロイしても最大1年間古いページが表示されます。手を入れるなら`/images/:path*`のように自分で管理する静的パスに限ります。 ## cacheComponentsを使わない構成での書き方 既存アプリを16へ上げただけの場合、キャッシュは従来どおり個別に指定します。この構成でも`fetch`は既定でキャッシュされません（[Caching (Previous Model)](https://nextjs.org/docs/app/guides/caching-without-cache-components)）。 ``` import { unstable_cache } from 'next/cache' import { db } from '@/lib/db' // fetch を明示的にキャッシュする export async function getPosts() { const res = await fetch('https://api.example.com/posts', { cache: 'force-cache', next: { revalidate: 3600, tags: ['posts'] }, }) return res.json() } // fetch を使わない DB クエリをキャッシュする export const getCachedUser = unstable_cache( async (id: string) => db.users.findUnique({ where: { id } }), ['user'], { tags: ['user'], revalidate: 3600 } ) ``` ルート単位なら、ページやレイアウトから`export const revalidate = 600`のように出します。ルート内で最も小さい`revalidate`がルート全体の間隔になります。レンダリング方式の選び方は[Next.jsのレンダリング方式｜SSG・ISR・SSR・CSRの違いとApp Routerでの選び方](/tech/details/3791/)で整理しています。 `unstable_cache`は公式に「16で`use cache`に置き換えられた」と明記されています。それでもこの構成を残す理由は1つで、`unstable_cache`と`fetch`のキャッシュは、保存先を維持する構成ならデプロイをまたいで再利用できるからです。セルフホストでコンテナを入れ替えるなら、永続ボリュームか外部ストアで保存先を残す必要があります。デプロイのたびに温め直すと外部APIの料金や負荷が問題になるデータだけ、この方式に残す判断はありえます。旧方式と新方式が混在する既存アプリの移行計画から相談したい場合は、[業務用・Webアプリ開発](https://www.issoh.co.jp/service/apps/business/)の支援も行っています。 ## キャッシュが効かない・消えないときの切り分け 症状から原因の層を絞り込む手順です。上から順に確かめます。 - 開発サーバーで本番とキャッシュの挙動が違う → `next dev`ではページは常にオンデマンドで描画されますが、データ側のキャッシュは開発時にも働きます。ページのキャッシュは`next build`と`next start`で確かめます。 - デプロイ後も古い内容が出る → `use cache`はキーに使うID（ビルドIDか`deploymentId`）が変われば旧エントリを使いません。IDが変わったか、旧版のインスタンスに振り分けられていないか、デプロイをまたぐ`fetch`・`unstable_cache`のキャッシュ、CDNとブラウザのHTTPキャッシュを順に確かめます。 - revalidateTagを呼んだのに古い → まず第2引数を見ます。`'max'`なら、次のアクセスで作り直しが始まり、終わるまでのリクエストに旧データが返るのは正常な動作です。作り直しが終わっても古いなら、タグ名の一致、CDNが持っている複製、別インスタンスへの振り分けを確かめます。CDNはパージ、別インスタンスはキャッシュハンドラに共有ストアへの無効化の伝達を実装して直します。 - 本番でだけ`use cache`がエラーになる → キャッシュの内側（呼び出し先の関数を含む）で`cookies`や`headers`を読んでいます。動的なルートでは`next build`を通過し`next start`で落ちます。 - ビルドが50秒で止まる → `params`や`searchParams`、未キャッシュのデータを`use cache`の内側で待っています。値を先に取り出して引数で渡します。 - 戻る操作で古い画面が出る → クライアントキャッシュです。クライアントコンポーネントから`router.refresh()`を呼びます。ただしサーバー側のキャッシュは無効化されないので、そこが古ければタグやパスの再検証も要ります。`next/cache`の`refresh()`はServer Action専用の別APIです。 挙動を追うときは`NEXT_PRIVATE_DEBUG_CACHE=1`を付けて起動すると詳細ログが出ます。開発時はキャッシュされた関数のコンソール出力に`Cache`の接頭辞が付きます。ただしこれはキャッシュ済みの関数のログを再生した印で、接頭辞だけではヒットか新規実行かを判別できません。 ## よくある質問 ### Next.jsのキャッシュをクリアするにはどうすればよいですか？ 層ごとに手段が違います。`use cache`の旧エントリは、キーに使うビルドID（設定時は`deploymentId`）が変われば使われなくなります。同じIDのまま再配備しただけでは消える保証はありません。特定のデータだけなら、Server Action内は`updateTag`、Route Handlerからは`revalidateTag`、ルート単位は`revalidatePath`です。CDNが持っている分はCDNのパージが別に要ります。 ### Data Cacheはどこに保存されますか？ 13〜14でData Cacheと呼ばれた`fetch`と`unstable_cache`の保存先は、セルフホストでは各インスタンスのディスクとメモリ（上限50MB）です。`use cache`のキャッシュはこれとは別の仕組みで、既定では各インスタンスのメモリだけに置かれます。複数のコンテナで共有するなら、従来方式は`cacheHandler`、`use cache`は`use cache: remote`か`cacheHandlers`でRedisなどの外部ストアに載せます。 ### Lighthouseの「効率的なキャッシュ保存期間を使用する」はどう直しますか？ HTTPキャッシュの指摘です。ビルド出力のJavaScriptとCSSにはNext.jsが1年の`immutable`を自動で付けるので、指摘されるのは`public/`配下に自分で置いた画像やフォント、外部ドメインの配信物です。自サイトが配信するパスなら`headers()`か管理下のCDNでキャッシュ期間を付けます。外部ドメインの配信物は配信元で直すしかありません。同じURLのまま画像を差し替える運用なら、差し替えの頻度に合わせて期間を短めに決めます。 ### SSRのページもキャッシュできますか？ できます。Cache Componentsでは、リクエスト時のデータを読む部分だけを`