ISR のページはビルド時や再生成時に作られるためリクエストのクエリが届かないことを示した図

【Next.js】ISR にクエリを渡す回避策の正体とは?【解説】

今回は Next.js の ISR でリクエストのパラメータが読めなかった話を、クエリを例に書きます。プレビューモードを挟めば値は渡せますが、その正体は静的生成のバイパスでした。App Router での扱いまで解説します!

ISR のページはビルド時や再生成時に作られるためリクエストのクエリが届かないことを示した図

こんにちは。ダタク @iQeeeda です。

3 年続けた Laravel 案件を終えて、 Next.js のフロントエンド案件に移った 1 年目 (2025 年のはじめ頃) のことです。
ISR (Incremental Static Regeneration。ビルド時に作ったページを、公開後もリクエストをきっかけに作り直せる仕組み) のページで、HTTP リクエストのパラメータを使いたい場面がありました。

いざ調べると、そもそも受け取れない。
ビルド時や再生成時に動く仕組みなので、個別のリクエストのパラメータは届かないと分かりました。正直、詰んだかと思いました。

結論: ISR にクエリを渡す回避策は静的生成を一時的にやめる仕組み

先に結論です。

  • 静的生成用の関数 getStaticProps の context にクエリは入ってこない
  • 静的生成のままサーバ側で読める入力は URL パスの params 等だけ
  • プレビューモードを挟めば値は渡せるが、正体は静的生成のバイパス
  • プレビューモードの後継 Draft Mode には値を渡せない

※ Next.js 16 系の App Router (app/ 構成) でサーバ側からクエリを読むなら、ページの引数 searchParams を使い動的レンダリングにするのが正攻法です。

今回は「ISR のページにリクエストのパラメータを渡す」という話を、クエリパラメータを例に書きます。
Pages Router (pages/ ディレクトリを使う従来の書き方) の話ですが、Next.js 16 系の App Router でどうなったかまで触れます。それでは解説していきます。

getStaticProps がクエリパラメータを読めない理由

getStaticProps はページをビルド時にプリレンダリングするための関数です。
ISR を有効にすると再生成のときにも走りますが、引数として渡される context にリクエストの中身は入りません。
公式ドキュメントに載っている context のキーは全部で 8 つで、まとめると次の 5 系統だけです。

  • params — 動的ルーティングのパラメータ
  • preview / previewData — 下書きプレビュー用 (非推奨)
  • draftMode — Draft Mode (プレビューモードの後継機能) が有効かどうか
  • locale / locales / defaultLocale — 多言語まわり
  • revalidateReason — getStaticProps が呼ばれた理由

クエリ (query) もリクエスト情報 (req) もありません。

getStaticProps の context には params はあるがクエリパラメータを受け取る項目が無いことを示した図

つまり ISR のページが静的生成のままサーバ側 (getStaticProps) で受け取れる入力は URL のパスに載った `params` など事前に決まる値だけです。
たとえば /items/123 のように動的ルートを用意してあれば params で読めますが、?id=123 のようなクエリパラメータは届きません。

プレビューモードを経由してクエリの値を渡す

当時たどり着いたのは プレビューモード を経由する方法でした。

  1. まずクエリを付けて API ルート (pages/api/ に置くサーバ側の処理) にアクセスする
  2. API ルートで res.setPreviewData() に値をセットする
  3. 目的のページにリダイレクトする

previewData を使った受け渡しのコード例

クエリパラメータを受け取る最小限のコードにすると、API ルート側はこんな形になります。

export default function handler(req, res) {
  // 実際には secret の検証が要る (公式のサンプルを参照)
  // 渡したい値を previewData にセットする
  res.setPreviewData({ id: req.query.id })
  // 目的のページへリダイレクトする
  res.redirect('/target')
}

セットしたオブジェクトは getStaticProps の context.previewData にそのまま入ってきます。

export async function getStaticProps(context) {
  // setPreviewData に渡したオブジェクトがそのまま読める
  const id = context.previewData?.id
}

公式ドキュメントにも、必要ならプレビュー用の API ルートから getStaticProps へセッション情報を渡す用途に使えると書かれています。

API ルートで値をセットしてリダイレクトすると getStaticProps で読めることを示した流れ図

これで値の受け渡しはできました。ただし入れられる量には上限があります。
previewData はクッキーに保存されるので、2KB までです。

プレビューモードの正体は静的生成のバイパス

回避策そのものより、こちらのほうが大事です。

プレビューモードは CMS の下書き確認用

プレビューモードは CMS で書いた記事を公開前に確認するための機能です。
書きかけの記事を見たいのに静的生成のままだと公開済みの内容しか出てきません。
下書きを確認するケースだけ (プレビュー用のクッキーが付いている間だけ) 静的生成をバイパスするのが本来の用途です。

公式ドキュメントによると、このプレビュー用クッキーが付いたリクエストでは getStaticProps がビルド時ではなくリクエスト時に呼ばれます。

通常の ISR はビルド時と再生成時に生成されプレビュー時はリクエストごとに生成されることを示した対比図

つまりクッキーが付いた時点で、そのページはもう静的ではありません。
クッキーが残っている限り、アクセスのたびに getStaticProps が走ります。

サーバ側でクエリを読むなら静的生成をやめるしかない

僕は「値を渡す方法」を探していたつもりでした。
実際に選んでいたのは「そのページの静的生成をやめる方法」だった。

ビルド時にプリレンダリングされる関数に、リクエストごとの値は入りません。
リクエストごとの値をサーバ側 (getStaticProps) で使いたいなら、道は結局この 2 つです。

  • 値を URL のパスに載せて params で受け取る
  • そのページの静的生成をやめる

プレビューモードを挟む回避策は 2 つ目の「静的生成をやめる」を遠回りに実現していたことになります。
クッキーが効いている間だけ静的生成を外すのか、リクエストごとにサーバで描画する関数 (getServerSideProps) に書き換えて毎回動かすのか。
2KB の上限や API ルート経由のリダイレクトといった違いはありますが、静的生成を手放してリクエスト時に動かす構造自体は同じです。

なお、ページを静的生成のまま置きたいなら、クエリはクライアント側で読むという手もあります。
ただし静的生成のページだと、 `useRouter` の query はサーバ側のプリレンダリング中は空のオブジェクトです。
初回の描画では値を使えず、ブラウザ側で描き直すことになります。

Draft Mode では値を渡せないが App Router なら searchParams で読める

値を previewData に載せるこの書き方は 2026 年 11 月時点の公式ドキュメント (Next.js 16.4 系) で非推奨とされています。
プレビューモードの公式ページには legacy API と明記されていて、後継は Draft Mode だと案内されています。getStaticProps の context 一覧でも、preview と previewData には「Deprecated for draftMode」が付いています。

ただし Draft Mode には値を渡す引数がありません。
Pages Router で指定できるのは res.setDraftMode({ enable: true }) のように有効か無効かだけ。受け取る側も context.draftMode に真偽値が入るのみです。

App Router の `draftMode()` も同じで、持っているのは次の 3 つです。

  • isEnabled — 有効かどうかの真偽値
  • enable() — 有効にする
  • disable() — 無効にする
previewData は任意のデータを渡せるが draftMode は 3 つの操作しか持たないことを示した対比図

setPreviewData に相当するものがありません。当時の回避策は Draft Mode へそのまま移せません。

App Router でサーバ側から読むなら searchParams を使う

新規で App Router を使う構成なら、サーバ側からクエリを読むのにプレビューモードのような回り道は要りません。
ページの引数として渡される `searchParams` (クエリの中身) をそのまま読むだけです。

ただし公式ドキュメントには、searchParams を使うとそのページはリクエスト時の動的レンダリングになると明記されています。
一部だけ静的な枠を残せる Cache Components を使う場合でも、searchParams を読む部分自体はリクエスト時に動きます。

つまり Pages Router で getServerSideProps に切り替えるのと同じで、サーバ側でクエリを読むならページ全体の静的生成を手放すことになります。
静的なまま保ちたい場合は、動的ルートのパスに載せるかクライアント側で読む設計を選びます。

Pages Router でも App Router でも、静的生成とリクエスト時の値のトレードオフ自体は変わりません。
サーバ側でクエリを読みたくなった時点で、そのページ全体を静的生成のままにはしておけない。これだけははっきり覚えました。

よかったら参考にしてみてください。

関連記事

まだコメントはありません