Next.js डॉकर छवि आउटपुट के साथ: 'स्टैंडअलोन': मल्टी-स्टेज बिल्ड और नॉन-रूट
स्टैंडअलोन क्यों
एक नियमित Next.js छवि संपूर्ण node_modules को निर्भरता, स्रोतों और बिल्ड कैश के साथ कॉपी करती है। 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 जोड़ें, अन्यथा ट्रेस पड़ोसी फ़ोल्डरों से पैकेज नहीं ढूंढ पाएगा।
डॉकरफ़ाइल
# 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"]समाधान का विश्लेषण:
- तीन चरण। संकलक, निर्भरता और स्रोत मध्यवर्ती चरणों में रहते हैं और अंतिम छवि में समाप्त नहीं होते हैं।
- `--mount=type=cache` एक ही मशीन पर बिल्ड के बीच एनपीएम कैश को सुरक्षित रखता है। यह एक BuildKit फ़ंक्शन है, इसलिए शुरुआत में
# syntaxलाइन है। - `HOSTNAME=0.0.0.0`.
server.jsइस वेरिएबल से पता सुनता है। इसके बिना, सर्वर कंटेनर नाम से जुड़ सकता है, और अग्रेषित पोर्ट कनेक्शन विफलता के साथ प्रतिक्रिया देगा। - स्टेटिक्स को अलग से कॉपी किया जाता है।
.next/standaloneमें.next/staticऔरpublicशामिल नहीं है - यह पहली बिल्ड के बाद CSS और JS पर 404 का एक सामान्य कारण है। - `USER node`. आधिकारिक नोड छवियों में पहले से ही एक विशेषाधिकार प्राप्त उपयोगकर्ता नहीं है
node(यूआईडी 1000)। अपना खुद का बनाना आवश्यक नहीं है, लेकिन फ़ाइलों को--chownसे कॉपी किया जाना चाहिए, अन्यथा प्रक्रिया ISR और छवि अनुकूलन के लिए.next/cacheपर लिखने में सक्षम नहीं होगी।
पर्यावरण चर: निर्माण और रनटाइम
NEXT_PUBLIC_* वेरिएबल्स को next build के दौरान क्लाइंट जावास्क्रिप्ट में प्रतिस्थापित किया जाता है। docker run के साथ उन्हें स्थानांतरित करने में बहुत देर हो चुकी है - बंडल में पहले से ही असेंबली से एक मान शामिल है या खाली है। इसलिए वे बिल्डर चरण में ARG से गुजरते हैं।
इसके विपरीत, सर्वर रहस्य (DATABASE_URL, एपीआई कुंजियाँ) को छवि में शामिल नहीं किया जाना चाहिए। उन्हें 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
पीआईडी 1 और कंटेनर को रोकना
पीआईडी 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 और स्टैंडअलोन मोड में कनेक्ट होता है; इसे मैन्युअल रूप से इंस्टॉल करने की कोई आवश्यकता नहीं है. यदि आपको अभी भी शार्प की अनुपस्थिति के बारे में चेतावनी दिखाई देती है, तो जांच लें कि बिल्ड और रनटाइम एक ही प्लेटफ़ॉर्म पर हैं: ग्लिबैक के लिए संकलित बायनेरिज़ अल्पाइन (मसल) पर काम नहीं करते हैं, और इसके विपरीत। इसलिए, उदाहरण में, सभी चरण एक मूल छवि से हैं।
रिजल्ट कैसे चेक करें
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 . . तो नहीं है।
सामान्य गलतियां
Error: EACCES.next/cacheपर लिखते समय - फ़ाइलें--chownके बिना कॉपी की गईं।- साइट काम करती है, लेकिन शैलियों के बिना - वे
.next/staticकी प्रतिलिपि बनाना भूल गए। NEXT_PUBLIC_*ब्राउज़र में खाली - रनटाइम पर स्थानांतरित किया गया, असेंबली के दौरान नहीं।- Apple सिलिकॉन के साथ Mac पर बनाएं, amd64 सर्वर पर चलाएं - आपको
docker buildx build --platform linux/amd64की आवश्यकता है, अन्यथा मूल मॉड्यूल गलत आर्किटेक्चर के हैं।
जब स्टैंडअलोन की जरूरत न हो
यदि परिनियोजन वर्सेल या किसी अन्य प्लेटफ़ॉर्म पर अपनी असेंबली के साथ जाता है, तो यह सेटिंग कुछ नहीं देती है। स्थैतिक निर्यात (output: 'export') के लिए, सर्वर की बिल्कुल भी आवश्यकता नहीं है - स्थैतिक के साथ nginx पर्याप्त है।