Next.js Docker イメージと出力: 'standalone': マルチステージ ビルドおよび非 root
なぜスタンドアロンなのか
通常の 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 で十分です。