v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:04:00.000Z▲ 0 upvotes

Next.js Docker イメージと出力: 'standalone': マルチステージ ビルドおよび非 root

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

なぜスタンドアロンなのか

通常の Next.js イメージは、node_modules 全体を devDependency、ソース、ビルド キャッシュとともにコピーします。 output: 'standalone' Next.js を使用すると、ビルド時にサーバーが実際に必要とするファイルを追跡し、それらを最小限の server.js とともに .next/standalone に配置します。これ、静的、および public のみが最終イメージに含まれます。

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};
export default nextConfig;

モノリポジトリでは、リポジトリ ルートへのパスを含む outputFileTracingRoot を追加します。そうしないと、トレースで隣接フォルダーからパッケージが検索されません。

Dockerfile

# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS base
ENV NEXT_TELEMETRY_DISABLED=1
WORKDIR /app

# 1. Только зависимости — слой кэшируется, пока не меняется lock-файл
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

# 2. Сборка
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
RUN npm run build

# 3. Рантайм
FROM base AS runner
ENV NODE_ENV=production \
    PORT=3000 \
    HOSTNAME=0.0.0.0

COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static

USER node
EXPOSE 3000
CMD ["node", "server.js"]

ソリューションの分析:

  • 3 段階。 コンパイラー、devDependency、およびソースは中間段階に残り、最終イメージにはなりません。
  • `--mount=type=cache` は、同じマシン上のビルド間で npm キャッシュを保持します。これは BuildKit 関数であるため、先頭に # syntax 行があります。
  • `HOSTNAME=0.0.0.0`. server.js は、この変数からのアドレスをリッスンします。これがないと、サーバーはコンテナ名にバインドでき、転送されたポートは接続失敗で応答します。
  • 静的コピーは個別にコピーされます。 .next/standalone には .next/static と public は含まれません。これは、最初のビルド後の CSS および JS での 404 の一般的な原因です。
  • `USER node`. 公式ノード イメージにはすでに非特権ユーザー node (uid 1000) が含まれています。独自のファイルを作成する必要はありませんが、ファイルは --chown からコピーする必要があります。そうしないと、プロセスは ISR とイメージの最適化のために .next/cache に書き込むことができなくなります。

環境変数: ビルドとランタイム

NEXT_PUBLIC_* 変数は next build 中にクライアント JavaScript に置き換えられます。 docker run で転送するには遅すぎます。バンドルにはすでにアセンブリからの値が含まれているか、空です。したがって、ビルダー段階で ARG を通過します。

逆に、サーバーのシークレット (DATABASE_URL、API キー) はイメージに含めるべきではありません。これらを ARG として渡したり、.env をコピーしたりしないでください。起動時に設定します。

docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0

そして、必ず .dockerignore を実行してください。そうしないと、COPY . . によって、シークレットを含む不要なものがアセンブリ コンテキストにドラッグされます。

node_modules
.next
.git
.env*
*.log
coverage

PID 1 とコンテナの停止

PID 1 として実行されているノード プロセスは、信号に対する標準のカーネル動作を受け取りません。アプリケーションに SIGTERM ハンドラーがない場合、docker stop はタイムアウト (デフォルトでは 10 秒) を待機し、SIGKILL によってプロセスを強制終了し、アクティブなリクエストを終了します。簡単な解決策は、init プロセスです。

# compose.yml
services:
  web:
    image: myapp:1.4.0
    init: true
    env_file: /etc/myapp/prod.env
    ports:
      - "127.0.0.1:3000:3000"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3

スリム イメージには curl がないため、ヘルスチェックはノード自体に書き込まれます。グローバル fetch はノード 18 以降で使用できます。

画像とシャープ

Next.js 15 では、sharp はスタンドアロン モードで next start に自動的に接続されます。手動でインストールする必要はありません。それでもシャープがないことに関する警告が表示される場合は、ビルドとランタイムが同じプラットフォーム上にあることを確認してください。glibc 用にコンパイルされたバイナリは Alpine (musl) では機能しません。また、その逆も同様です。したがって、この例では、すべてのステージが 1 つの基本イメージから作成されます。

結果の確認方法

docker build -t myapp:test --build-arg NEXT_PUBLIC_SITE_URL=https://example.com .
docker image ls myapp:test                  # размер образа
docker run --rm myapp:test id               # uid=1000(node), не root
docker run --rm myapp:test ls -la .next     # владелец node

レイヤー内のスペースを占有しているものを分析するには、dive ツールが便利です。最終画像が予想外に大きい場合は、通常 node_modules 全体が含まれています。ランナーに COPY . . が含まれていないことを確認してください。

よくある間違い

  • .next/cache に書き込むときに Error: EACCES - ファイルは --chown なしでコピーされました。
  • サイトは機能しますが、スタイルがありません - .next/static をコピーするのを忘れていました。
  • NEXT_PUBLIC_* はブラウザ内で空です - アセンブリ時ではなく、実行時に転送されます。
  • Apple Silicon を搭載した Mac 上でビルドし、amd64 サーバー上で実行します。docker buildx build --platform linux/amd64 が必要です。そうでない場合、ネイティブ モジュールのアーキテクチャが間違っています。

スタンドアロンが必要ない場合

展開が Vercel または独自のアセンブリを持つ別のプラットフォームに行われる場合、この設定は何も与えません。静的エクスポート (output: 'export') の場合、サーバーはまったく必要ありません。静的な nginx で十分です。

Обсуждение (0)

Ещё на vbcd4u.com