Docker Multi-Stage Builds للمبتدئين: نزّل صورة Node.js من 1.2GB لـ 95MB

# المرحلة الأولى: البناء
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# المرحلة الثانية: الإنتاج
FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/index.js"]

الحجم الناتج: حوالي 95MB. التحسّن الفعلي: 92% أقل. السطور اللي اتغيرت فعليًا: خمسة. الكود نفسه ما اتلمسش.

إيه اللي حصل بالظبط

1. المرحلة builder اشتغلت بـ node:20 الكامل علشان تقدر تبني الكود. التطبيق محتاج TypeScript و devDependencies في المرحلة دي بس.
2. المرحلة runtime بدأت من node:20-alpine. الـ Alpine base image حجمه ~50MB مقابل ~370MB لـ node:20 الكامل.
3. npm ci --omit=dev ثبّت dependencies الإنتاج فقط. لا TypeScript، لا jest، لا eslint.
4. COPY --from=builder /app/dist ./dist نقل الكود المبني فقط. مفيش source أصلي، مفيش .git، مفيش node_modules بتاعة البناء.
5. USER node منع التشغيل بصلاحيات root، وده default سيء في كثير من الـ images.

قياس الفرق

القياس الحقيقي اللي يهم: لو بتعمل deploy 30 مرة في اليوم على 5 سيرفرات، الفرق بيوفّر تقريبًا 150 دقيقة pull يوميًا، وبيقلّل تكلفة egress من الـ registry بنسبة مماثلة. هذا الشرح مبني على فرضية إنك بتشغّل تطبيق Node.js قياسي بـ TypeScript. لو بتستخدم Bun أو Deno الأرقام بتختلف.

trade-offs لازم تعرفها

الـ Multi-Stage مش مجاني تمامًا.

• زمن البناء أطول قليلاً أول مرة (15–20 ثانية إضافية تقريبًا، لأن فيه مرحلتين بدل واحدة). لكن BuildKit cache بيخلّي البناءات اللي بعد كده أسرع، وأحيانًا أسرع من الـ Dockerfile الأصلي بسبب layer caching أنظف.
• Debugging أصعب على alpine. مفيش curl ولا vim ولا bash داخل الصورة النهائية. لو محتاج تدخل عليها، شغّل docker run --rm -it <image> sh أو ضيف RUN apk add --no-cache curl في مرحلة debug منفصلة.
• مكتبات native (مثل bcrypt أو sharp) ممكن تحتاج build-base و python3 في مرحلة البناء على alpine، وأحيانًا تحتاج تنقل الـ .node binaries يدويًا للـ runtime.
• الـ Alpine بيستخدم musl libc بدل glibc. ده بيكسر بعض المكتبات النادرة. لو حصل، استخدم node:20-slim بدل node:20-alpine — أكبر شوية (~80MB) لكن أقل مفاجآت.

متى لا تستخدم Multi-Stage

لو التطبيق فيه interpreter بدون build step (Python بدون Cython، Ruby بدون extensions، PHP خام)، الفائدة محدودة جدًا. ساعتها استخدم base image صغير مباشرة زي python:3.12-slim وخلاص. كذلك لو بتبني صورة CI runner أو dev container تستخدمها أنت بنفسك للتطوير، احتفظ بكل الأدوات داخلها — مفيش معنى توفّر 1GB في صورة هتعيش على لابتوبك.

كمان لو فريقك ما عندوش خبرة بـ Docker layers، ابدأ بحل أبسط: غيّر الـ base image لـ node:20-slim فقط. هتاخد 60% من الفائدة بسطر واحد، ومن غير تعقيد المرحلتين.

الخطوة التالية

افتح Dockerfile في أقرب مشروع Node.js عندك، وقسّمه لمرحلتين بالنمط فوق. شغّل docker build -t app:before . على النسخة القديمة، و docker build -t app:after . على الجديدة. قارن بـ docker images | grep app. لو الفرق أقل من 50%، غالبًا فيه node_modules بيتنقل بالغلط، أو الـ .dockerignore ناقصة. ضيف فيها node_modules و .git و dist قبل ما تعيد البناء.

المصادر

• التوثيق الرسمي لـ Docker Multi-Stage Builds: docs.docker.com/build/building/multi-stage
• Node.js Docker Best Practices (Node.js Foundation): github.com/nodejs/docker-node — BestPractices.md
• Snyk: 10 best practices to containerize Node.js applications: snyk.io/blog
• Alpine Linux base image — node official: hub.docker.com/_/node
• Trivy container vulnerability scanner: aquasecurity.github.io/trivy