Next.js のデプロイ｜next build とセルフホスト構成

開発が終わったら本番環境に出します。Next.js は Node.js が動く環境なら基本的にどこでも動きますが、キャッシュや環境変数の扱いに独特の前提があり、そこを知らないと「ローカルでは動くのに本番でおかしい」という状態になります。この記事では自前サーバーで運用する場合を中心に扱います。

1デプロイ方式の選択

静的書き出し（output: "export"）は HTML と静的ファイルだけを出力する方式で、任意の Web サーバーに置けます。ただしサーバーを必要とする機能は使えません。proxy.ts のようにリクエストを見る仕組みは動かず、画像最適化も専用のローダーを別途用意する必要があります。

2Node.js サーバーとして動かす

npm run build
npm run start

これだけで全機能が使えます。ただし、Next.js のサーバーを直接インターネットに晒すのは推奨されていません。Nginx などのリバースプロキシを前段に置き、不正なリクエストの遮断、接続数の制限、ペイロードサイズの上限といった役割を任せます。Next.js 側は描画に専念させる、という考え方です。

3Docker 向けの standalone 出力

コンテナに入れる場合、node_modules を丸ごと持ち込むとイメージが肥大します。output: "standalone" を指定すると、実行に必要なファイルだけがまとめて出力されます。

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'standalone',
}

export default nextConfig

複数のコンテナを立てる場合、同じビルド成果物を使い回すのが原則です。ステージごとにビルドし直すと、後述するビルド ID が食い違って問題が起きます。どうしてもビルドを分ける必要があるなら、generateBuildId で git のコミットハッシュなどを固定値として与えます。

// next.config.js
module.exports = {
  generateBuildId: async () => {
    return process.env.GIT_HASH
  },
}

4環境変数はいつ読まれるか

ここが最も誤解されやすい部分です。環境変数には、ビルド時に固定されるものと、実行時に読まれるものがあります。

実行時に確実に読みたい場合は、connection() を先に await します。これによりその処理がリクエスト時の実行に切り替わり、ビルド時の値が固定されるのを防げます。

import { connection } from 'next/server'

export default async function Page() {
  await connection()
  const value = process.env.RUNTIME_CONFIG   // 実行時に評価される
  return <p>{value}</p>
}

なお、バージョン 16 で serverRuntimeConfig と publicRuntimeConfig は削除されました。環境変数に置き換えてください。

5キャッシュの置き場所

生成済みページやキャッシュは、既定でインスタンスごとのメモリとローカルディスクに保存されます。1 台で動かし、ディスクが永続化されているなら、これで問題ありません。

問題になるのは複数台構成です。コンテナごとに別々のキャッシュを持つため、あるインスタンスで再検証しても他には伝わらず、古い内容が出続けます。この場合は共有ストアを使うカスタムのキャッシュハンドラを設定します。

// next.config.js
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0,   // 既定のメモリキャッシュを無効化
}

ハンドラ側では get / set / revalidateTag を実装し、Redis などの外部ストアに保存します。加えて、タグの無効化を全インスタンスへ伝えるための refreshTags も実装しておくと、再検証の取りこぼしを防げます。

6複数インスタンスで必要な 3 点

暗号鍵はビルドごとに自動生成されるため、インスタンス間で食い違うと Server Function の復号に失敗します。base64 で 16・24・32 バイトのいずれかの鍵を用意し、ビルド時に環境変数で与えます。

デプロイ ID を設定すると、静的資産の URL にデプロイ識別子が付き、クライアントの持つ ID と食い違ったときは通常のページ遷移ではなく完全な再読み込みに切り替わります。新旧のバージョンが混在する時間帯を安全に乗り切るための仕組みです。

7ストリーミングを止めない

ストリーミングは、レスポンスを分割して送り続けることで成立します。前段のプロキシがバッファリングしていると、分割の意味が失われて最後にまとめて届きます。

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*{/}?',
        headers: [{ key: 'X-Accel-Buffering', value: 'no' }],
      },
    ]
  },
}

ロードバランサーやその手前の機器も、分割転送に対応している必要があります。1 か所でもためこむ設定があると、経路全体でストリーミングが無効になります。

8停止と再起動

after() で登録した後処理は、レスポンスを返した後に実行されます。プロセスを止めるときは SIGINT か SIGTERM を送り、処理中のリクエストと保留中の後処理が終わるのを待ちます。停止までの猶予は 10〜30 秒程度を確保しておくのが目安です。いきなり強制終了すると、書き込み途中の処理が失われる可能性があります。

9つまずきやすいところ

• 環境変数を変えたのに反映されない：NEXT_PUBLIC_ 付きはビルド時に埋め込まれます。再ビルドが必要です。
• CDN を挟んだら個人情報が他人に見えた：リクエスト依存の描画では Cache-Control: private が付きますが、CDN 側がこれを尊重する設定になっているか確認してください。
• 画像最適化でメモリを食う：glibc 系の Linux では、メモリアロケータの設定が必要になる場合があります。
• ビルドが Webpack 設定で失敗する：バージョン 16 では Turbopack が既定です。設定を移行するか --webpack を指定します。
• デプロイ直後だけ遅い：キャッシュキーにビルド ID が含まれるため、新しいデプロイでは作り直しから始まります。仕様どおりの挙動です。

これでひととおりの流れが揃いました。最後に、既存プロジェクトをバージョン 16 へ持っていく際の注意点をまとめます。