
AI Assisted
この記事は筆者の実装経験をもとに実装コードをベースで執筆し、AIによる校閲・推敲を経て公開しています。
Next.js 16 へのメジャーアップグレードでは、paramsやcookiesの非同期化、middleware.tsの廃止など、既存のアプリケーションに大きな影響を与える変更が含まれています。 何も知らずにアップグレードすると、大量のエラーに直面することになります。
この記事では、Next.js 16 における Breaking Changes(破壊的変更)の全貌と、具体的な対応方法をコード付きで解説します。
後方互換性のない変更のことです。アップグレードすると、今まで動いていたコードが動かなくなる可能性がある変更を指します。
Next.js はメジャーバージョンアップ時に、設計の改善、セキュリティ修正、パフォーマンス向上などを目的として Breaking Changes を導入します。今回は特に大規模な変更が含まれているため、事前の把握が必須です。
まず、足回りの環境を確認しましょう。
Node.js 18 はサポート対象外になりました。
# バージョン確認
node -v
# nvm 使用時
nvm install 20
nvm use 20
CI/CD、Docker、本番環境すべてで確認とアップデートが必要です。
TypeScript を使用している場合は、package.json のバージョンを確認してください。
ここが今回のアップグレードで最も影響が大きい部分です。多くのコンポーネントで修正が必要になります。
Page や Layout コンポーネントの props である params と searchParams が Promise になりました。アクセスするには await が必要です。
// [NG] Next.js 15まで
export default function Page({ params }: { params: { id: string } }) {
// 同期的にアクセスできていた
const { id } = params
return <div>{id}</div>
}
// [OK] Next.js 16から
export default async function Page({
params,
}: {
// 型も Promise になる
params: Promise<{ id: string }>
}) {
// await が必須
const { id } = await params
return <div>{id}</div>
}
クエリパラメータを取得する searchParams も同様です。
// [OK] Next.js 16
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
const { q } = await searchParams
return <div>検索: {q}</div>
}
サーバーサイドでリクエスト情報を取得する関数群も非同期になりました。
// [NG] Next.js 15まで
import { cookies, headers, draftMode } from 'next/headers'
export default function Page() {
const cookieStore = cookies() // 同期
const headerList = headers() // 同期
const { isEnabled } = draftMode() // 同期
}
// [OK] Next.js 16から
import { cookies, headers, draftMode } from 'next/headers'
// コンポーネントを async にする
export default async function Page() {
const cookieStore = await cookies() // 非同期
const headerList = await headers() // 非同期
const { isEnabled } = await draftMode() // 非同期
}
従来の Middleware は廃止され、より強力な proxy.ts に置き換わりました。ファイル名と関数名の変更が必要です。
詳細は別記事「Next.js 16 proxy.ts 移行ガイド」を参照してください。
// [NG] Next.js 15: middleware.ts
export function middleware(request: NextRequest) { ... }
// [OK] Next.js 16: proxy.ts
export function proxy(request: NextRequest) { ... }
並列ルート(@folder)を使用している場合、すべてのスロットに対してフォールバック用の default.tsx(または default.js)が必須になりました。
app/
├── @sidebar/
│ ├── page.tsx
│ └── default.tsx <- これがないとエラーになる
├── layout.tsx
└── page.tsx
とりあえず何も表示しない場合は null を返します。
// app/@sidebar/default.tsx
export default function Default() {
return null
}
next/image のデフォルト設定がいくつか変更されています。意図しない表示崩れやキャッシュ挙動の変化に注意してください。
| 設定 | Next.js 15 | Next.js 16 |
|---|---|---|
minimumCacheTTL | 60 秒 | 14400 秒(4時間) |
imageSizes | 16 を含む | 16 を削除 |
qualities | 1〜100 すべて | 75 のみ |
maximumRedirects | 無制限 | 3 |
従来の動作を維持したい場合は、next.config.js で明示的に設定する必要があります。
// next.config.js
const nextConfig = {
images: {
// Next.js 15 と同じ挙動にする設定例
minimumCacheTTL: 60,
imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
qualities: [50, 75, 100],
maximumRedirects: 5,
},
}
セキュリティ強化のため、ローカル IP への画像最適化リクエストがデフォルトでブロックされるようになりました。開発環境などで許可したい場合は設定が必要です。
// next.config.js
const nextConfig = {
images: {
dangerouslyAllowLocalIP: true,
},
}
クエリ文字列(?v=1 など)を含むローカル画像を最適化する場合、localPatterns.search の設定が必須になりました。
// next.config.js
const nextConfig = {
images: {
localPatterns: [
{
pathname: '/assets/**',
search: '?v=1', // クエリを許可
},
],
},
}
待望の Turbopack が、next dev と next build のデフォルトバンドラーになりました。高速な開発体験が標準になります。
# Turbopack で起動(デフォルト)
next dev
next build
# 従来の webpack に戻す場合
next dev --webpack
next build --webpack
next.config.js 内での Turbopack の設定場所が、experimental からトップレベルに移動しました。
// [NG] Next.js 15
const nextConfig = {
experimental: {
turbopack: { /* options */ },
},
}
// [OK] Next.js 16
const nextConfig = {
turbopack: { /* options */ },
}
next dev と next build の出力先が分離されました。
| コマンド | 出力先 |
|---|---|
next dev | .next/dev |
next build | .next |
これにより、開発サーバーを起動したまま裏でビルドを実行する、といった並行作業が可能になります。
以下の機能は完全に削除されました。使用している場合は代替手段への移行が必要です。
AMP 関連のすべての API が削除されました。
// [NG] 削除されたAPI
import { useAmp } from 'next/amp'
export const config = { amp: true }
Next.js 組み込みのリンターコマンドが削除されました。今後は標準的な ESLint CLI や他のツールを使用します。
# [NG] 削除
next lint
# [OK] 代替案
npx eslint .
# または
npx biome check .
serverRuntimeConfig と publicRuntimeConfig は削除されました。
// [NG] 削除
module.exports = {
serverRuntimeConfig: { ... },
publicRuntimeConfig: { ... },
}
今後は標準的な環境変数(.env)を使用してください。
# .env.local
DATABASE_URL=xxx # サーバー側のみで参照可能
NEXT_PUBLIC_API_URL=xxx # クライアント側でも参照可能(NEXT_PUBLIC_ 接頭辞)
devIndicators オプション(ビルドインジケーターの表示設定)experimental.dynamicIO(代わりに cacheComponents: true を使用)まだ動作はしますが、将来的に削除されるため移行が推奨される機能です。
// [注意] 非推奨
import Image from 'next/legacy/image'
// [OK] 推奨:新しい next/image を使う
import Image from 'next/image'
画像最適化のドメイン指定は、よりセキュアな remotePatterns が推奨されます。
// [注意] 非推奨
const nextConfig = {
images: {
domains: ['example.com'],
},
}
// [OK] 推奨
const nextConfig = {
images: {
remotePatterns: [
{
protocol: 'https', // プロトコル指定が必須
hostname: 'example.com',
},
],
},
}
キャッシュ関連のAPIが安定化しました。
// [NG] 非推奨
import {
unstable_cacheLife as cacheLife,
unstable_cacheTag as cacheTag,
} from 'next/cache'
// [OK] 推奨
import { cacheLife, cacheTag } from 'next/cache'
細かいですが、挙動が変わる点です。
Next.js はナビゲーション中に CSS の scroll-behavior: smooth をオーバーライドしなくなりました。
もしスムーズスクロールが効かなくなった場合は、自身の CSS または html タグで明示的に設定してください。
<html lang="ja" style={{ scrollBehavior: 'smooth' }}>
開発時の設定ファイルロードが 2 回から 1 回に削減され、起動が高速化しました。
これに伴い、process.argv.includes('dev') は意図した動作をしなくなります。環境の判定には NODE_ENV を使用してください。
// [NG] 動作しない
if (process.argv.includes('dev')) { ... }
// [OK] 推奨
if (process.env.NODE_ENV === 'development') { ... }
next build 実行時に表示されていた size(バンドルサイズ)と First Load JS のメトリクス表示が削除されました。
正確なパフォーマンス測定には、Chrome Lighthouse や Vercel Analytics などの専用ツールを使用してください。
手動での修正範囲が広いため、Next.js 公式が提供する codemod(自動修正ツール)の活用を強く推奨します。
以下のコマンドで、主要な破壊的変更を自動的に適用できます。
npx @next/codemod@canary upgrade latest
このコマンドは以下のような変更を自動で行ってくれます:
async-request-api: params/searchParams/cookies 等の非同期化middleware-to-proxy: proxy.ts への移行next-lint-to-eslint-cli: ESLint CLI への移行設定まず、Next.js と React 関連のパッケージを最新版に更新します。
npm install next@latest react@latest react-dom@latest
自動修正ツールを実行し、機械的に直せる部分を一気に修正します。
npx @next/codemod@canary upgrade latest
codemod で対応しきれない部分(画像設定の変更や、複雑なコンポーネントの非同期化など)を手動で修正します。TypeScript のエラーを頼りに修正していくと良いでしょう。
# まずビルドが通るか確認
npm run build
# 開発サーバーで実際の動作を確認
npm run dev
Next.js 16 は、パフォーマンスと開発体験を大きく向上させるメジャーアップデートですが、その分、移行のハードルも高くなっています。
特に非同期化の対応は、アプリケーション全体に影響が及びます。codemod を活用しつつ、計画的にアップグレードを進めてください。
スポーツ×ITの会社でバックエンドエンジニア兼マネージャーとして勤務。インテル関連の情報を中心に発信しています。
最終更新: 2026年1月25日
© 2025 nero15.dev. All rights reserved.