الـ image من القسم الأول تشحن إلى الإنتاج TypeScript، وتعريفات الأنواع، ومشغّل الاختبارات، ومجلد src/، وكل اعتمادية تطوير أخرى. لا شيء من هذا يعمل في الإنتاج. وكله سطح هجوم إضافي، ووقت سحب إضافي، وضجيج في تقارير الفحص. الحل أن تبني في مكان وتشحن من مكان آخر.
كل FROM تبدأ مرحلة (stage) جديدة بنظام ملفات جديد. سمِّ المراحل بـ AS، وانسخ الملفات بينها بـ COPY --from. والمرحلة الأخيرة وحدها هي التي تصبح الـ image التي تضع عليها الـ tag.
# syntax=docker/dockerfile:1\n\n# 1. Compile TypeScript (needs dev dependencies)\nFROM node:24-slim AS build\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN --mount=type=cache,target=/root/.npm npm ci\nCOPY tsconfig.json ./\nCOPY src ./src\nRUN npm run build\n\n# 2. Production dependencies only\nFROM node:24-slim AS deps\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN --mount=type=cache,target=/root/.npm npm ci --omit=dev\n\n# 3. What actually ships\nFROM node:24-slim AS runtime\nENV NODE_ENV=production\nWORKDIR /app\nCOPY package.json ./\nCOPY --from=deps /app/node_modules ./node_modules\nCOPY --from=build /app/dist ./dist\nEXPOSE 3000\nCMD [\"node\", \"dist/server.js\"]مرحلة runtime تحصل على ثلاثة أشياء بالضبط: package.json، وnode_modules الخاص بالإنتاج، وdist/ المترجَم. أما TypeScript وsrc/ وذاكرة تنزيلات npm فتبقى في مراحل لا يشحنها أحد.
يحسب BuildKit مخطّط الاعتماديات بين المراحل بنفسه. لا تعتمد build وdeps إحداهما على الأخرى، فتعملان بالتوازي، وأي مرحلة لا يحتاج إليها الهدف تُتخطّى كليًا.
في notes-api قلّص هذا حجم الـ image بنحو الثلث، وفحص الثغرات الذي ستشغّله لاحقًا في هذا القسم انتقل من عشرات النتائج في أدوات التطوير إلى بضع نتائج فقط في بيئة التشغيل. الدرس التالي يقلّص الـ base image نفسها.
\nلماذا ننسخ package.json إلى مرحلة التشغيل أصلًا؟ لأن package.json في notes-api يحتوي على "type": "module"، الذي يطلب من Node أن يعامل ملفات .js على أنها ES modules. إن حذفته، فسيفشل الـ container عند البدء برسالة SyntaxError: Cannot use import statement outside a module، وهي تبدو خللًا في البناء لكنها في الحقيقة ملف مفقود. إذا كان مشروعك يستخدم CommonJS فيمكنك تخطّيه، لكنه لا يكلّف شيئًا ويُبقي البيانات الوصفية لـ npm متاحة.
قد ترى نمطًا مختلفًا: مرحلة واحدة تشغّل npm ci، ثم تبني، ثم تشغّل npm prune --omit=dev قبل نسخ node_modules إلى الخارج. هذا يعمل، ويوفّر عملية تثبيت واحدة. أنا أفضّل مرحلة deps المنفصلة لأنها تُخزَّن في الـ cache مستقلةً: ترقية أداة خاصة بالتطوير مثل الـ linter لا تُبطل layer اعتماديات الإنتاج، فيُعاد استخدام تلك الـ layer عبر عمليات بناء كثيرة، وتتغيّر image التشغيل بوتيرة أقل.
المراحل أهداف مفيدة أيضًا. شغّل مجموعة الاختبارات في البيئة التي تحتوي على اعتماديات التطوير، دون لمس الـ image المشحونة:
\ndocker build --target build -t notes-api:test .\ndocker run --rm notes-api:test npm testالخيار --target build يتوقّف عند مرحلة build. يستطيع الـ CI تشغيل هذا قبل بناء image التشغيل، ويتشارك البناءان الـ cache نفسه.
حين تشغّل docker build .، يُرسل المجلد كاملًا إلى أداة البناء بوصفه الـ context، مطروحًا منه كل ما يطابق .dockerignore. من دونه، ينتقل إلى أداة البناء node_modules المحلي لديك (مئات الميغابايتات، وربما فيه وحدات أصلية (native modules) مترجَمة لـ macOS)، ومجلد .git، وأي ملف .env فيه بيانات اعتماد حقيقية. وأي COPY . . يضعها كلها في layer.
node_modules\ndist\ncoverage\n.git\n.env\n.env.*\n*.log\nDockerfile\ncompose*.yamlثلاثة مكاسب دفعة واحدة: يهبط الـ context من مئات الميغابايتات إلى بضع مئات من الكيلوبايتات، ولا تعود تعديلات الملفات المتجاهَلة تُبطل الـ cache، ولا يمكن نسخ الأسرار الموجودة في مجلد عملك إلى image بالخطأ.
\n\nالصيغة تشبه .gitignore: نمط واحد في كل سطر، والرمزان * و** للمطابقة، و! لإعادة تضمين شيء ما. أبقِه في جذر الـ build context. وإن احتجت رغم ذلك إلى ملف واحد من الملفات المتجاهَلة، فأعِد تضمينه تحت القاعدة العامة، مثلًا .env.* يليه !.env.example، حتى يمكن نسخ ملف القالب بينما لا يمكن نسخ الملفات الحقيقية.
عند الشك، افحص ما استلمته أداة البناء فعلًا: الأمر docker build --progress=plain . يطبع حجم الـ context المنقول في أسطره الأولى. إذا كان هذا الرقم بالميغابايتات لـ API صغير، فهناك شيء ناقص في .dockerignore.
في الدرس التالي ستستبدل الـ base image بأخرى أصغر، وتكفّ عن تشغيل التطبيق بالمستخدم root.
\n","toc":[{"id":"sec-1","text":"Dockerfile واحد، ومراحل عدّة","level":2},{"id":"sec-2","text":"استخدام المراحل الوسيطة عن قصد","level":2},{"id":"sec-3","text":"ملف .dockerignore: تحكّم فيما تراه أداة البناء","level":2}],"takeaways":["الـ multi-stage build يستخدم عدّة مراحلFROM؛ ولا يتحوّل إلى image إلا المرحلة الأخيرة (أو المرحلة التي تحدّدها بـ --target).","التعليمة COPY --from=<stage> تسحب ملفات محدّدة من مرحلة سابقة، فلا تصل المترجِمات واعتماديات التطوير إلى الإنتاج أبدًا.","ثبّت اعتماديات الإنتاج بـ npm ci --omit=dev في مرحلة خاصة بها، وانسخ node_modules وdist فقط إلى مرحلة التشغيل.","ملف .dockerignore يُبقي node_modules و.git وملفات .env ومخرجات البناء خارج الـ context، فيصير البناء أسرع وأكثر أمانًا."],"further":[{"title":"Multi-stage builds","url":"https://docs.docker.com/build/building/multi-stage/"},{"title":"Build context and .dockerignore","url":"https://docs.docker.com/build/concepts/context/"},{"title":"Dockerfile reference: COPY --from","url":"https://docs.docker.com/reference/dockerfile/#copy---from"}],"quiz":[{"q":"في Dockerfile مراحله build وdeps وruntime (بهذا الترتيب)، ماذا ينتج الأمر docker build -t notes-api:1.0.0 .؟
notes-api:1.0.0.","why":"البناء الواحد ينتج image واحدة. المراحل السابقة وسيطة ولا توجد إلا في الـ build cache."},{"text":"image مبنية من المرحلة الأخيرة runtime، ولا تحتوي إلا على ما نسخته تلك المرحلة إليها.","why":"صحيح. المرحلة الأخيرة هي الهدف الافتراضي. وكل ما لم يُنسخ إليها يبقى خلفها."},{"text":"image مبنية من المرحلة الأولى، لأن البناء يحدث فيها.","why":"المرحلة الأولى هي الافتراضية فقط حين تكون الوحيدة. مع عدّة مراحل تفوز الأخيرة ما لم تمرّر --target."},{"text":"image واحدة تحتوي على layers المراحل الثلاث مكدّسة معًا.","why":"المراحل لا تتكدّس. كل FROM تبدأ نظام ملفات جديدًا؛ ولا ينقل الملفات بينها إلا COPY --from صريحة."}],"answer":1},{"q":"لماذا نثبّت اعتماديات الإنتاج في مرحلة deps منفصلة بدلًا من تقليمها في مرحلة build؟
npm ci --omit=dev لا يعمل إلا في مرحلة اسمها deps.","why":"أسماء المراحل مجرد تسميات اعتباطية. الخيار يعمل في أي مرحلة."},{"text":"لأن المراحل المنفصلة دائمًا أصغر من مرحلة واحدة.","why":"عدد المراحل وحده لا يغيّر الحجم. المهمّ هو ما تنسخه إلى المرحلة الأخيرة."},{"text":"لأن مراحل البناء لا تستطيع تشغيل npm scripts.","why":"أي مرحلة تستطيع تشغيل أي أمر؛ ومرحلة البناء نفسها تشغّل npm run build."},{"text":"لأن مرحلة البناء تحتاج إلى اعتماديات التطوير مثل TypeScript، بينما لا يحتاج التشغيل إلا إلى اعتماديات الإنتاج؛ والتثبيت النظيف بـ --omit=dev يعطي هذه المجموعة بالضبط.","why":"صحيح. كما أن هذه المرحلة تُخزَّن في الـ cache مستقلةً، فتغيير اعتمادية خاصة بالتطوير لا يُبطل تثبيت الإنتاج."}],"answer":3},{"q":"حجم الـ build context لديك 1.2 غيغابايت، وكل بناء يبدأ بعبارة “transferring context” لمدة 40 ثانية. ما الحل الأرجح؟
","options":[{"text":"أضف ملف.dockerignore يستبعد node_modules و.git ومخرجات البناء.","why":"صحيح. هذه المجلدات تشكّل عادةً معظم الـ context، ولا ينبغي إرسال أي منها إلى أداة البناء."},{"text":"استخدم COPY src ./src بدلًا من COPY . ..","why":"النسخ الأضيق يفيد الـ cache ومحتوى الـ image، لكن الـ context كاملًا ما زال يُرسل ما لم تتجاهل الملفات."},{"text":"انقل الـ Dockerfile إلى مجلد فرعي.","why":"الـ context هو المجلد الذي تمرّره أيًّا كان، بغضّ النظر عن مكان الـ Dockerfile."},{"text":"أضف --no-cache لتخطّي نقل الـ context.","why":"الخيار --no-cache يعطّل إعادة استخدام الـ layers. والـ context ما زال يُنقل."}],"answer":0},{"q":"كيف تشغّل اختبارات الوحدات لـ notes-api داخل بيئة بناء الـ image دون أن تشحن أدوات الاختبار؟
","options":[{"text":"أضفRUN npm test إلى مرحلة التشغيل.","why":"مرحلة التشغيل لا تحتوي على اعتماديات التطوير، فلن يكون مشغّل الاختبارات موجودًا؛ وأنت تريد إبقاء الاختبارات خارج الـ image المشحونة على أي حال."},{"text":"انسخ ملفات الاختبار إلى مرحلة التشغيل وشغّلها بـ docker exec.","why":"هذا يشحن الاختبارات وأدواتها إلى الإنتاج، وهو بالضبط ما تتجنّبه الـ multi-stage builds."},{"text":"ابنِ مرحلة build وحدها بـ --target build وشغّل الاختبارات في container منها.","why":"صحيح. --target يتوقّف عند المرحلة المسمّاة، التي تحتوي على اعتماديات التطوير والكود المصدري، ولا يتسرّب منها شيء إلى image التشغيل."},{"text":"استخدم Dockerfile ثانيًا ينسخ image التشغيل.","why":"image التشغيل تفتقر عمدًا إلى اعتماديات التطوير، فلا يمكن تشغيل الاختبارات فيها."}],"answer":2}],"exercise":{"kind":"spot-bug","language":"dockerfile","code":"# syntax=docker/dockerfile:1\nFROM node:24-slim AS build\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN npm ci\nCOPY . .\nRUN npm run build\n\nFROM node:24-slim AS runtime\nENV NODE_ENV=production\nWORKDIR /app\nCOPY --from=build /app ./\nEXPOSE 3000\nCMD [\"node\", \"dist/server.js\"]","bugLines":[12],"title":"الـ multi-stage build الذي يشحن كل شيء","prompt":"كان الهدف من هذا الـ Dockerfile ذي المرحلتين إبقاء TypeScript واعتماديات التطوير خارج الإنتاج. لكن الـ image بالكاد أصغر من قبل، وما زال الماسح يُبلغ عن ثغرات CVE في أدوات الاختبار. اختر السطر الذي يُفسد الغرض من المرحلة الثانية.
\n","hints":["انظر إلى ما تنسخه مرحلة التشغيل من مرحلة البناء.","المجلد/app في مرحلة البناء يحتوي على src/ وdist/ وnode_modules فيه كل اعتماديات التطوير."],"explanation":"السطر 12 ينسخ /app الكامل من مرحلة البناء إلى image التشغيل، فيُشحن src/ واعتماديات التطوير وكل ما كان في الـ context. أضف مرحلة لاعتماديات الإنتاج فقط وانسخ مسارات مسمّاة:
FROM node:24-slim AS deps\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN npm ci --omit=dev\n\nFROM node:24-slim AS runtime\nENV NODE_ENV=production\nWORKDIR /app\nCOPY package.json ./\nCOPY --from=deps /app/node_modules ./node_modules\nCOPY --from=build /app/dist ./dist