Next.js 16 への移行｜破壊的変更と詰まりどころ

バージョン 15 から 16 への移行は、変更点の数が多いわりに一つ一つは機械的です。ただし「動かない理由が分からない」タイプの詰まり方をしやすく、原因の切り分けに時間を取られがちです。この記事では、実際に遭遇する順に並べて対処法を示します。新規に学んでいる人にとっても、古い記事のコードが動かない理由の索引として使えます。

1まずコードモッドを流す

npx @next/codemod@canary upgrade latest

このコマンドが自動でやってくれるのは次のとおりです。

• next.config の Turbopack 設定を新しい位置へ移す
• next lint から ESLint CLI への移行
• middleware から proxy への改名
• 安定化した API から unstable_ 接頭辞を外す
• ルートセグメント設定の experimental_ppr を削除する

ただし、これですべてが終わるわけではありません。同期的な params アクセスが残っている場合は、別のコードモッドを追加で実行します。

npx @next/codemod@canary next-async-request-api .

2前提バージョンを上げる

手動で上げる場合は本体と React をまとめて更新します。TypeScript を使っているなら型定義も忘れずに。

npm install next@latest react@latest react-dom@latest

3同期アクセスの廃止

バージョン 15 で非同期化され、互換のために同期アクセスも残されていた API が、16 で完全に非同期のみになりました。対象は次のとおりです。

• cookies()、headers()、draftMode()
• layout / page / route / default の params
• page の searchParams
• opengraph-image / twitter-image / icon / apple-icon の params

// 15 まで（もう動かない）
export default function Page({ params }) {
  const slug = params.slug
}

// 16
export default async function Page({ params }) {
  const { slug } = await params
}

画像生成関数では id も Promise になりました。generateImageMetadata 側の params は同期のままという非対称があるので、両方を書いている場合は注意してください。sitemap の id も同様に Promise です。

4Turbopack が既定になったことによる影響

--turbopack は不要になりました。逆に、独自の Webpack 設定を持つプロジェクトで next build を実行すると、設定の不整合を避けるためビルドが失敗します。

Sass の ~ 接頭辞（@import '~bootstrap/...'）は Turbopack では使えません。接頭辞を外すか、turbopack.resolveAlias で吸収します。

5middleware から proxy へ

mv middleware.ts proxy.ts

関数名も proxy に変えます。設定フラグも skipMiddlewareUrlNormalize → skipProxyUrlNormalize のように改名されました。

ここで一点だけ注意が要ります。proxy の実行環境は Node.js に固定されており、Edge ランタイムは使えません。Edge を前提にした処理がある場合は、当面 middleware のまま運用する判断もあり得ます。

6キャッシュ関連の変更

API 側の変更も押さえておきます。

7削除されたもの

8気づきにくい挙動の変化

• 並行ルートに default.tsx が必須：無いとビルドが失敗します。notFound() を呼ぶか null を返すファイルを置きます。
• スムーススクロールの上書きをやめた：html に scroll-behavior: smooth を設定していると、遷移時もスムーズにスクロールするようになりました。以前の挙動に戻すには data-scroll-behavior="smooth" を html に付けます。
• next dev と next build が同時に実行できる：出力先が分かれました。開発サーバーの出力は .next/dev です。同じプロジェクトでの二重起動はロックで防がれます。
• ビルド出力から size と First Load JS が消えた：サーバーコンポーネント構成では正確でなかったためです。実測にはブラウザの計測ツールを使います。
• next dev 時に process.argv に 'dev' が含まれない：設定ファイルの読み込み回数が減ったためです。判定は NODE_ENV で行います。
• ESLint がフラット設定を既定にした：.eslintrc 形式を使っている場合は移行を検討します。

9エラーから原因を逆引きする

10移行の進め方

実務では、次の順で進めると切り分けが楽になります。

1. Node.js と TypeScript を先に上げ、現行バージョンのまま動作を確認する
2. 本体を更新し、コードモッドを流す
3. ビルドを通す（Turbopack・非同期 API・並行ルートの 3 点が主な壁）
4. 削除された機能の使用箇所を潰す
5. ここまでを本番に出して安定させる
6. 別作業として cacheComponents の採用を検討する

とくに 6 を 3 と同時にやらないことが重要です。キャッシュモデルの移行は設計変更を伴うため、バージョン更新と混ぜると原因の特定が困難になります。

ここまでで、シリーズはひととおり完結です。個々のトピックは 目次 から辿れます。