Next.js 13 静的エクスポートと Vercel デプロイ完全ガイド

静的エクスポートの基本概念

Next.js 13 では output: 'export' を next.config.js に記述するだけで、ビルド時にページがすべて静的 HTML として出力されます。

• ビルドフロー
• next build がプロジェクト全体の依存関係解決・最適化を実行。

• 同じプロセス内で自動的に next export が走り、生成物はデフォルトで .output（または out）ディレクトリに書き出されます。

• 得られる成果物

• 完全な HTML ファイル（ページごとに 1 つ）
• CSS/JS のバンドルは _next/static/* 以下に配置
• 画像やフォントなどのアセットも同梱可能

この形態は CDN や静的ホスティングサービス（Vercel、Netlify、GitHub Pages 等）で高速配信が可能です。

注: output: 'export' を設定しない場合は従来通りサーバーレス関数が生成され、静的エクスポートは行われません。

next.config.js の推奨設定とローカルでの確認方法

1. 基本的な静的エクスポート設定

2. ローカルで生成物をプレビューする手順

1. ビルド & エクスポート
   bash
npm run build # 出力先はデフォルトで out ディレクトリ
2. 簡易サーバー起動（serve パッケージを使用）
   bash
npx serve out -l 5000 # http://localhost:5000 で確認
npm i -g serve が不要な場合は上記のように一時的に実行できます。

ポイント：ローカルサーバーは「ファイルベース」の静的配信を再現するため、リダイレクトやクリーン URL の挙動も同様に確認できます。

Vercel へのプロジェクト作成・GitHub 連携手順

1. プロジェクトの新規作成

2. Framework Preset と Output Directory の設定

1. Settings → General

2. Framework Preset: Next.js を選択（Vercel が自動で next build を実行）

3. Build & Output Settings

4. Output Directory: out （静的エクスポートの出力先を明示）
5. Build Command: 省略可。デフォルトは npm run build && npm run export が実行されますが、output: 'export' が設定済みなら npm run build のみで十分です。

注意：Vercel が自動的に next export を走らせるかどうかは、output: 'export' が 正しく認識されていること が前提です。公式ドキュメントでも「静的エクスポートを使用する場合は output オプションで明示してください」と記載されています。

3. GitHub Actions の位置付け

Vercel の自動ビルドだけでデプロイは完結しますが、以下のようなケースでは GitHub Actions が有用です。

• ビルド前にコード整形・テストを走らせたい
• カスタムスクリプト（例：画像圧縮や外部 API からのデータ取得）をビルドプロセスに組み込みたい

したがって「GitHub Actions が不要になる」という表現は過剰です。必要に応じて併用してください。

vercel.json による高度な URL 制御と環境変数の管理

1. 静的サイト向けのリライトルール例

2. 環境変数とシークレットの安全な扱い方

1. Vercel ダッシュボード → Settings → Environment Variables
2. Name（例：NEXT_PUBLIC_API_URL）
3. Value（実際のエンドポイント）

4. Environment（Production / Preview / Development）を選択

5. コード側での参照
   js
// 例: pages/api/client.js
const API_URL = process.env.NEXT_PUBLIC_API_URL;
export async function getStaticProps() {
const res = await fetch(${API_URL}/posts);
const posts = await res.json();
return { props: { posts } };
}

6. シークレット変数（NEXT_ で始まらないもの）はクライアント側に露出しません。ビルド時のみ利用され、ランタイムでも Vercel Functions に渡すことが可能です。

ベストプラクティス：公開 API キーは NEXT_PUBLIC_ プレフィックスで明示的に公開する。一方、認証トークンや DB パスワードはシークレット変数として登録し、コード内では process.env.<NAME> のみ使用してください。

ビルド失敗時の典型的な原因と対策

Hybrid（静的＋サーバーレス）構成の例

この方式なら、静的ページは高速 CDN 配信しつつ、動的処理は Vercel Functions が担う形になるため、柔軟性が向上します。

実運用で役立つ Tips とベストプラクティス

1. CI/CD の分離
2. 静的エクスポートだけなら Vercel の自動ビルドで完結。

3. それでもコード品質（ESLint、Jest）を保証したい場合は GitHub Actions にテストジョブのみ配置し、ビルドは Vercel 任せにするとシンプルです。

4. キャッシュ制御

5. vercel.json の headers 設定で HTML は Cache-Control: no-cache, max-age=0、静的資産は長期キャッシュ（例：max-age=31536000, immutable）を付与すると、ブラウザ側の再取得が減少します。

json
{
"headers": [
{
"source": "/(.*).html",
"headers": [{ "key": "Cache-Control", "value": "no-cache" }]
},
{
"source": "/_next/static/(.*)",
"headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
}
]
}

1. プレビュー環境の活用

2. Vercel の Preview Deploy はブランチごとに自動生成され、VERCEL_ENV=preview がセットされます。環境変数で API エンドポイントを切り替えるだけで、本番と同等の挙動をローカルに近い形で確認できます。

3. 画像・フォントの最適化

4. next/font と組み合わせてサブセット化したフォントをビルド時に埋め込む。

5. 静的エクスポートでも next/image が外部画像を自動圧縮するので、remotePatterns に対象ホストだけ追加すれば OK。

6. デプロイ後のモニタリング

7. Vercel の Analytics（有料）または Google Analytics を組み込み、ページロード時間やエラーレートを定期的にチェック。
8. エラーが頻出したら vercel logs コマンドでサーバーログ（Functions が残っている場合）を取得し、原因を特定します。

まとめ

• 静的エクスポートの核は output: 'export' と next build の組み合わせ。これだけで完全な HTML・CSS·JS が out/ に出力されます。
• 推奨する next.config.js 設定は trailingSlash, basePath, images.remotePatterns を加えることで、サブパスや外部画像の取り扱いが楽になります。
• Vercel では「Framework Preset = Next.js」「Output Directory = out」を設定すれば自動ビルドが走りますが、GitHub Actions が不要になるわけではなく、テストやカスタム処理が必要な場合は併用が推奨です。
• vercel.json による rewrites / redirects / cache ヘッダー の設定と、環境変数・シークレットの安全管理で、静的サイトでも柔軟かつセキュアに運用できます。
• ビルド失敗は主に「動的ページが未定義」「API Routes が残っている」ことが原因です。getStaticPaths の正しい実装や Hybrid 構成への切り替えで対処しましょう。

これらの手順とベストプラクティスを踏めば、Next.js 13 で作った静的サイトを Vercel にシームレスにデプロイし、パフォーマンス・保守性ともに高い Web プロダクトを実現できます。