nextjs-deployment

Next.js のデプロイ

Docker、CI/CD パイプライン、包括的なモニタリングを使用して、Next.js アプリケーションを本番環境にデプロイします。

概要

このスキルでは、Next.js アプリケーションを本番環境にデプロイするためのパターンとコード例を紹介します。Docker によるコンテナ化、GitHub Actions による CI/CD の自動化、環境設定、ヘルスチェック、本番環境のモニタリングを扱います。コンテナを使ったデプロイではスタンドアロン出力モードを使用し、最適化されたイメージを作成するにはマルチステージ Docker ビルドを使用します。また、可観測性には OpenTelemetry を使用します。

使用するタイミング

次のようなリクエストがあった場合に有効にします。

• 「Next.js をデプロイ」「Next.js を Docker 化」「コンテナ化」
• 「GitHub Actions」「CI/CD パイプライン」「自動デプロイ」
• 「環境変数」「ランタイム設定」「NEXT_PUBLIC」
• 「プレビュー環境へのデプロイ」「ステージング環境」
• 「モニタリング」「OpenTelemetry」「トレース」「ロギング」
• 「ヘルスチェック」「レディネス」「ライブネス」
• 「本番ビルド」「スタンドアロン出力」
• 「Server Actions の暗号化キー」「NEXT_SERVER_ACTIONS_ENCRYPTION_KEY」

クイックリファレンス

出力モード

モード	用途	コマンド
standalone	Docker／コンテナでのデプロイ	output: 'standalone'
export	静的サイト（サーバーなし）	output: 'export'
（デフォルト）	Node.js サーバーへのデプロイ	next start

環境変数の種類

プレフィックス	利用可能な場所	用途
NEXT_PUBLIC_	ビルド時およびブラウザー	公開 API キー、機能フラグ
（プレフィックスなし）	サーバーのみ	データベース URL、シークレット
ランタイム	サーバーのみ	環境ごとに異なる値

主要ファイル

ファイル	目的
Dockerfile	マルチステージのコンテナビルド
.github/workflows/deploy.yml	CI/CD パイプライン
next.config.ts	ビルド設定
instrumentation.ts	OpenTelemetry のセットアップ
src/app/api/health/route.ts	ヘルスチェックのエンドポイント

手順

1. スタンドアロン出力を設定する

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

const nextConfig: NextConfig = {
  output: 'standalone',
  poweredByHeader: false,
  generateBuildId: async () => process.env.GIT_HASH || 'build',
}

export default nextConfig

2. Dockerfile を作成する

マルチステージビルド、マルチアーキテクチャ対応、最適化の詳細については、references/docker-patterns.md を参照してください。

# syntax=docker/dockerfile:1
FROM node:20-alpine AS base

FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1 NODE_ENV=production
ARG GIT_HASH NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
ENV GIT_HASH=${GIT_HASH} NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=${NEXT_SERVER_ACTIONS_ENCRYPTION_KEY}
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 PORT=3000 HOSTNAME="0.0.0.0"
RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
USER nextjs
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => r.statusCode === 200 ? process.exit(0) : process.exit(1))"
CMD ["node", "server.js"]

3. GitHub Actions をセットアップする

テスト、セキュリティスキャン、デプロイ戦略を含むワークフローの詳細については、references/github-actions.md を参照してください。

# .github/workflows/deploy.yml
name: Build and Deploy
on:
  push:
    branches: [main, develop]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      - id: generate-key
        run: echo "key=$(openssl rand -base64 32)" >> $GITHUB_OUTPUT
      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          build-args: |
            GIT_HASH=${{ github.sha }}
            NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=${{ steps.generate-key.outputs.key }}

4. 環境変数を設定する

// src/lib/env.ts
export function getEnv() {
  return {
    databaseUrl: process.env.DATABASE_URL!,
    apiKey: process.env.API_KEY!,
    publicApiUrl: process.env.NEXT_PUBLIC_API_URL!,
  }
}

export function validateEnv() {
  const required = ['DATABASE_URL', 'API_KEY', 'NEXT_PUBLIC_API_URL']
  const missing = required.filter((key) => !process.env[key])
  if (missing.length > 0) {
    throw new Error(`Missing required environment variables: ${missing.join(', ')}`)
  }
}

5. ヘルスチェックを実装する

// src/app/api/health/route.ts
import { NextResponse } from 'next/server'

export const dynamic = 'force-dynamic'

export async function GET() {
  const checks = {
    status: 'healthy',
    timestamp: new Date().toISOString(),
    version: process.env.npm_package_version || 'unknown',
    uptime: process.uptime(),
  }
  return NextResponse.json(checks)
}

6. モニタリングをセットアップする

OpenTelemetry の設定、ロギング、アラート、ダッシュボードの詳細については、references/monitoring.md を参照してください。

// instrumentation.ts
import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel({
    serviceName: process.env.OTEL_SERVICE_NAME || 'next-app',
  })
}

7. Server Actions の暗号化を設定する

重要：複数サーバーへのデプロイでは、一貫した暗号化キーを生成して設定してください。

# Generate key
openssl rand -base64 32

# Set in GitHub Actions Secrets as NEXT_SERVER_ACTIONS_ENCRYPTION_KEY

このキーがないと、複数サーバーへのデプロイで Server Actions が「Failed to find Server Action」エラーを返して失敗します。

ベストプラクティス

• Docker：マルチステージビルドを使用し、スタンドアロン出力を有効にして、非 root ユーザーを設定し、ヘルスチェックを追加します
• セキュリティ：.env.local をコミットせず、公開値にのみ NEXT_PUBLIC_ を使用し、NEXT_SERVER_ACTIONS_ENCRYPTION_KEY を設定します
• パフォーマンス：output: 'standalone' を使用し、静的アセットに CDN を有効にして、next/image を使用します
• 環境：すべての環境で同じ Docker イメージを使用し、環境変数を介してランタイム設定を注入します

例

// next.config.ts
const nextConfig = {
  output: 'standalone',
  poweredByHeader: false,
  compress: true,
  generateBuildId: async () => process.env.GIT_HASH || 'build',
}
export default nextConfig

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://db:5432/myapp
      - NEXT_PUBLIC_API_URL=http://localhost:3000/api

制約と警告

制約

• スタンドアロン出力には Node.js 18 以降が必要です
• Server Actions の暗号化キーは、すべてのインスタンスで同じである必要があります
• ランタイム環境変数が機能するのは、output: 'standalone' の場合のみです
• OpenTelemetry を使用するには、プロジェクトのルートに instrumentation.ts が必要です

警告

• 機密情報に NEXT_PUBLIC_ プレフィックスを絶対に使用しないでください
• 複数サーバーへのデプロイでは、必ず NEXT_SERVER_ACTIONS_ENCRYPTION_KEY を設定してください
• ヘルスチェックがないと、オーケストレーターが正常でないインスタンスにトラフィックを送る可能性があります
• ランタイム環境変数は静的エクスポート（output: 'export'）では機能しません

参考資料

• references/docker-patterns.md - 高度な Docker 設定、マルチアーキテクチャビルド、最適化
• references/github-actions.md - CI/CD ワークフロー、テスト、セキュリティスキャンの完全ガイド
• references/monitoring.md - OpenTelemetry、ロギング、アラート、ダッシュボード
• references/deployment-platforms.md - プラットフォーム別ガイド（Vercel、AWS、GCP、Azure）