image کار می‌کند؛ پس چرا هنوز سنگین است؟The image works—so why is it still heavy?

فصل قبل بالاخره image خودت را ساختی و با curl هم دیدی که برنامه جواب می‌دهد. خیلی طبیعی است همین‌جا بگویی: «خب، تمام شد دیگر!» اما بیایید قبل از تمام‌کردن کار، درِ image را باز کنیم. برنامهٔ ما برای اجرا فقط یک فایل JavaScript و خود Node را لازم دارد؛ پس TypeScript، فایل‌های منبع و وابستگی‌های توسعه آن تو چه کار می‌کنند؟

In Chapter 4 you put a small application into an image and ran a container. If curl returns the expected response, it is tempting to call the job finished. Ask one more question: does the program really need TypeScript, the compiler, source files, and development dependencies while it is running?

قرار نیست مستقیم سراغ راه‌حل برویم. اول یک image تک‌مرحله‌ای می‌سازیم که کاملاً کار می‌کند، ولی عمداً وسایل کارگاه را هم با محصول نهایی داخل یک جعبه می‌گذارد. بعد اندازه‌اش می‌گیریم و می‌بینیم دقیقاً چه چیزهایی بی‌دلیل همراه برنامه مانده‌اند. وقتی مشکل را با چشم دیدیم، multi-stage build دیگر یک دستور حفظی نیست؛ جواب یک سؤال واقعی است.

To answer, we will first build a single-stage image. It intentionally keeps everything: source files, node_modules, TypeScript, and the build output. That is not wrong as a starting point. The problem begins when we assume the build environment and the runtime environment must be identical.

آزمایش اول: image سالم را اندازه بگیرExperiment one: measure the working image

برای اینکه بحث گم نشود، یک پروژهٔ خیلی کوچک به نام demo-ts داریم. برنامه فقط یک پاسخ HTTP ساده می‌دهد. TypeScript را هم نه برای آموزش TypeScript، بلکه فقط برای این آورده‌ایم که یک مرحلهٔ واقعیِ «ساختن» داشته باشیم: چیزی وارد build شود و در پایان فایل دیگری از آن بیرون بیاید.

Consider a small project named demo-ts. The program uses only Node’s built-in HTTP API; TypeScript is here only to make the difference between source and artifact visible, not to turn this into a TypeScript course.

demo-ts/
├── src/server.ts
├── package.json
├── package-lock.json
├── tsconfig.json
└── .dockerignore

در package.json، scriptِ build، TypeScript را اجرا می‌کند و خروجی را در dist/server.js می‌گذارد. package-lock.json هم باید کنار manifest باشد تا npm ci همان وابستگی tree قفل‌شده را نصب کند.

In package.json, the build script runs TypeScript and writes dist/server.js. package-lock.json must sit beside the manifest so npm ci installs the locked dependency tree.

$ docker image ls demo-ts
REPOSITORY   TAG      IMAGE ID       CREATED          SIZE
demo-ts      single   91ab...        seconds ago     182MB

$ docker image history demo-ts:single
IMAGE       CREATED        CREATED BY                         SIZE
91ab...     seconds ago   CMD ["node","dist/server.js"]       0B
<missing>   seconds ago   RUN npm run build                   4.8MB
<missing>   seconds ago   COPY . .                            12.4MB
<missing>   seconds ago   RUN npm ci                           66MB
<missing>   seconds ago   FROM node:22-bookworm-slim            99MB

به عددها نچسب. این اندازه‌ها نمونه‌اند و روی سیستم تو با توجه به tag، معماری و image پایه فرق می‌کنند. چیزی که باید ببینی خودِ الگوست: image نهایی فقط dist/server.js را اجرا می‌کند، ولی هنوز فایل‌های منبع، TypeScript و وابستگی‌های توسعه را هم با خودش حمل می‌کند.

This is not a measurement from one particular machine. The numbers are representative; tags, architecture, the base image, and build time change the size. The important clue is that source files and development dependencies live in the same image that is supposed to run only dist/server.js.

چند FROM یعنی چند محیط جداMultiple FROM instructions mean separate environments

اولین فکری که ممکن است به ذهن برسد این است: «آخر build فایل‌های اضافه را پاک می‌کنم.» می‌شود، اما راه تمیزتری داریم. در Dockerfile چند FROM می‌نویسیم و برای هر مرحله یک محیط جدا می‌سازیم. محیط اول کار ساخت را انجام می‌دهد؛ محیط آخر از یک image پایهٔ تازه شروع می‌شود و فقط چیزهایی را می‌گیرد که صریحاً به آن منتقل کنیم.

The solution is not manually deleting files from the same stage. We use multiple FROM instructions. Each FROM starts a new stage with its own base and filesystem; only what you explicitly bring to the final stage gets there.

مرحلهٔ اول را builder صدا می‌زنیم؛ چون کارش ساختن است. مرحلهٔ آخر جایی است که برنامه واقعاً اجرا می‌شود. اسم‌گذاری کمک می‌کند وقتی می‌نویسی COPY --from=builder دقیقاً معلوم باشد از کدام محیط چیزی برمی‌داری؛ لازم نیست شمارهٔ مرحله‌ها را حفظ کنی.

In our example, we name the first stage builder. The last stage is the runtime. Naming matters because COPY --from=builder refers to a stage’s role rather than a fragile number. If you later add a test stage, the name remains readable.

مثال کوچک: TypeScript فقط نقش build tool داردA small example: TypeScript is only the build tool

برنامهٔ ما عمداً ساده است: یک HTTP server که روی پورت ۳۰۰۰ جواب می‌دهد. اگر این برنامه را با Node معمولی بنویسی، runtime فقط فایل JavaScript خروجی را می‌خواهد. پس می‌توانیم وابستگی‌های build را در جایی نگه داریم که خروجی build را می‌سازد.

Our application is intentionally small: an HTTP server that answers on port 3000. If you wrote it directly in Node, the runtime would need only the generated JavaScript file. That lets us keep build dependencies where they produce the artifact.

// src/server.ts
import { createServer } from "node:http";

const port = Number(process.env.PORT ?? 3000);
const server = createServer((_request, response) => {
  response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
  response.end("hello from a multi-stage image\n");
});

server.listen(port, "0.0.0.0", () => {
  console.log("listening on " + port);
});

در یک پروژهٔ واقعی، قبل از build باید npm install --package-lock-only یا نصب معمولی، lockfile را ایجاد کند. اینجا نسخهٔ lockfile را کنار پروژه فرض می‌کنیم؛ چون بدون آن npm ci عمداً متوقف می‌شود.

In a real project, npm install --package-lock-only or a normal install must create the lockfile before the build. We assume the lockfile is committed beside the project; without it, npm ci intentionally stops.

{
  "private": true,
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  },
  "devDependencies": {
    "@types/node": "22.10.0",
    "typescript": "5.7.2"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

این فایل فقط قرارداد خروجی را روشن می‌کند: هر فایل TypeScript از src به JavaScript در dist می‌رود. اگر این قرارداد عوض شود، مسیر COPY --from هم باید دوباره بررسی شود.

This file makes the output contract explicit: TypeScript files under src become JavaScript under dist. If that contract changes, re-check the COPY --from path too.

این وابستگی‌ها برای کامپایل لازم‌اند، نه برای اجرای dist/server.js. چون برنامه فقط از API داخلی Node استفاده می‌کند، runtime به بستهٔ محیط واقعی جداگانه‌ای نیاز ندارد. این انتخاب، تفاوت دو stage را واضح و قابل‌اندازه‌گیری می‌کند.

These dependencies are needed to compile, not to execute dist/server.js. Because the app uses only Node’s built-in APIs, the runtime needs no separate production package. That makes the difference between the two stages clear and measurable.

نسخهٔ A: اول image کارا بسازVersion A: first build a working image

نسخهٔ A را عمداً ساده و تک‌مرحله‌ای نگه می‌داریم. هنوز دنبال image کوچک نیستیم؛ اول یک نسخهٔ سالم می‌خواهیم که بتوانیم بعداً منصفانه با نسخهٔ چندمرحله‌ای مقایسه‌اش کنیم. اگر نقطهٔ شروع سالم نباشد، هر مقایسه‌ای بعدش بی‌معنی می‌شود.

Version A is intentionally single-stage. We are not optimizing yet; we first need a runnable baseline so the later comparison means something.

FROM node:22-bookworm-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/server.js"]

دستورها را یک بار آرام از بالا به پایین بخوان. فایل‌های وابستگی زودتر می‌آیند تا cache با هر تغییر کوچک کد از بین نرود؛ بعد کد منبع وارد می‌شود و TypeScript آن را می‌سازد. مشکل اینجاست که همان محیطی که ابزار ساخت را لازم داشته، قرار است image نهایی هم باشد؛ بنابراین همهٔ وسایل کارگاه همان‌جا می‌مانند.

Read the instructions slowly: the manifest and lockfile come first so dependency caching is separated from source changes; then source is copied and compiled. The result still keeps node_modules, source, and compiler tools beside the artifact.

$ docker build -f Dockerfile.single -t demo-ts:single .
[+] Building 8.6s (10/10) FINISHED
 => [internal] load build definition from Dockerfile.single
 => [5/6] RUN npm run build
 => exporting to image
 => naming to docker.io/library/demo-ts:single

$ docker run --rm -d --name demo-single -p 8080:3000 demo-ts:single
7d91...
$ curl -sS localhost:8080
hello from a multi-stage image

این خروجی دو چیز را ثابت می‌کند: build خروجی build ساخته شده و runtime پاسخ می‌دهد. هنوز دربارهٔ اندازه یا امنیت نتیجه‌ای نگرفته‌ایم؛ برای آن باید image را جداگانه بررسی کنیم.

This output proves two things: the build produced an artifact and the runtime answers. It says nothing yet about size or security; those require separate image inspection.

نسخهٔ B: builder و runtime را جدا کنVersion B: separate builder and runtime

حالا همان پروژه را دو اتاق می‌کنیم. اتاق اول، builder، همهٔ ابزارهای ساخت را دارد و فایل نهایی را تولید می‌کند. اتاق دوم از یک image پایهٔ تمیز شروع می‌شود. از اتاق اول فقط dist را برمی‌داریم و می‌آوریم اینجا. همین جدایی، تمام ایدهٔ multi-stage build است.

Now we have two FROM instructions. The first stage compiles the source. The second starts from a fresh base and takes only the output file from the builder. That separation is the heart of a multi-stage build.

FROM node:22-bookworm-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build

FROM node:22-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/server.js"]

FROM ... AS builder stage را نام‌گذاری می‌کند. COPY --from=builder /app/dist ./dist می‌گوید کد منبع این COPY فایل‌سیستم stage builder است، نه build context میزبان. مقصد ./dist هم نسبت به WORKDIR /app در runtime محاسبه می‌شود.

FROM ... AS builder names the stage. COPY --from=builder /app/dist ./dist says that the source filesystem is the builder stage, not the host build context. The destination ./dist is resolved relative to WORKDIR /app in the runtime stage.

COPY --from را مثل یک آدرس دقیق بخوانRead COPY --from as a path contract

این دستور را مثل یک آدرس سه‌قسمتی بخوان: builder می‌گوید از کدام مرحله بخوان؛ /app/dist می‌گوید فایل در آن مرحله کجاست؛ و ./dist می‌گوید در مرحلهٔ فعلی کجا قرارش بده. اگر یکی از این سه را اشتباه بگیری، build همان‌جا می‌ایستد و هنوز اصلاً به اجرای container نرسیده‌ای.

The three names in this instruction have different roles: builder is a stage name; /app/dist is an absolute path inside the builder filesystem; ./dist is a destination in the runtime filesystem. If you confuse any of them with a laptop path, the build fails before runtime begins.

اگر شک کردی فایل واقعاً در builder ساخته شده یا نه، همان مرحله را جدا بساز: docker build --target builder .... این مثل این است که قبل از بسته‌بندی محصول، وارد خود کارگاه شوی و قفسهٔ خروجی را نگاه کنی. فقط حواست باشد image حاصل از --target builder همان image نهایی برنامه نیست.

For practice, build docker build --target builder -t demo-ts:builder . and inspect the stage separately. Targeting a stage helps debugging; do not confuse that tag with the final image.

آزمایش دوم: قبل و بعد را با همان سؤال مقایسه کنExperiment two: compare before and after with the same questions

حالا وقت مقایسه است، ولی فقط یک چیز را تغییر بده: ساختار تک‌مرحله‌ای در برابر چندمرحله‌ای. برنامه، خانوادهٔ image پایه و دستور اجرا را ثابت نگه دار. اگر هم‌زمان همه‌چیز را عوض کنی، وقتی اندازه تغییر کرد دیگر نمی‌فهمی علتش multi-stage بوده یا تغییر دیگری.

Run both images with the same base family, application, and command. If you also change the base, architecture, and application, you will not know whether the difference came from multi-stage or from those other changes.

$ docker build -f Dockerfile.multi -t demo-ts:multi .
[+] Building 5.1s (11/11) FINISHED
 => [builder 5/5] RUN npm run build
 => [runtime 1/2] COPY --from=builder /app/dist ./dist
 => naming to docker.io/library/demo-ts:multi

$ docker image ls demo-ts --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
REPOSITORY   TAG      SIZE
demo-ts      single   182MB
demo-ts      multi    118MB

$ docker image history demo-ts:multi
IMAGE       CREATED        CREATED BY                         SIZE
a82c...     seconds ago   CMD ["node","dist/server.js"]       0B
<missing>   seconds ago   COPY /app/dist                    4.8MB
<missing>   seconds ago   FROM node:22-bookworm-slim       99MB

در این نمونه image کوچک‌تر شده چون فایل‌های منبع، TypeScript و وابستگی‌های توسعه اصلاً وارد مرحلهٔ نهایی نشده‌اند. خبری از فشرده‌سازی جادویی نیست؛ فقط چیزهای غیرلازم را از همان ابتدا داخل جعبهٔ نهایی نگذاشته‌ایم.

In this representative sample, the image is smaller because dev dependencies, the compiler, and source files never entered the final image—not because of magical compression. The runtime base still contributes substantially, and shared layers may not be stored twice locally.

cache بین stageها: سریع‌تر شدن با حذف فایل‌ها یکی نیستCache across stages: speed is not the same as final contents

اینجا دو موضوع خیلی راحت با هم قاطی می‌شوند. یکی این است که «چه چیزی داخل image نهایی می‌رود؟» و دیگری اینکه «در build بعدی کدام مرحله دوباره اجرا می‌شود؟» اولی دربارهٔ محتوای image نهایی است؛ دومی دربارهٔ cache و سرعت build. ممکن است مرحلهٔ builder کاملاً از cache استفاده شود، ولی هیچ‌کدام از فایل‌های اضافی آن وارد image نهایی نشوند.

Multi-stage has two separate questions: what enters the final image, and which steps rerun on the next build? The cache may speed up the builder even though builder files never enter the final image.

# 1 · fresh builder
docker build -f Dockerfile.multi -t demo-ts:multi .

# 2 · no file changed
docker build -f Dockerfile.multi -t demo-ts:multi .

# 3 · edit src/server.ts only
docker build -f Dockerfile.multi -t demo-ts:multi .

# 4 · edit package-lock.json
docker build -f Dockerfile.multi -t demo-ts:multi .

نکتهٔ مهم: cache می‌تواند لایه‌های builder را روی ماشین نگه دارد، اما این به معنی کپی‌شدن آن‌ها در image نهایی نیست. برای دیدن رفتار دقیق، --progress=plain بزن و به اولین stepی نگاه کن که دیگر CACHED نیست.

Important: the cache may keep builder layers on the machine, but that does not copy them into the final image. Use --progress=plain and find the first step that is no longer CACHED.

کوچک‌تر همیشه یعنی Alpine نیستSmaller does not automatically mean Alpine

عمداً سراغ imageهای خیلی عجیب و کوچک نرفتیم. اگر هم‌زمان multi-stage را یاد بگیری و image پایه را هم عوض کنی، دوباره معلوم نیست نتیجه از کجا آمده. انتخاب image پایه باید با نیاز برنامه، کتابخانه‌های native، ابزارهای عیب‌یابی و قواعد تیم جور باشد؛ نه اینکه فقط کوچک‌ترین عدد جدول را انتخاب کنیم.

We used node:22-bookworm-slim so the main question stays isolated. You can choose another runtime, but the choice should follow application needs, native-library compatibility, debugging tools, and team policy—not only the smallest number on the screen.

کم‌شدن ابزارها و packageهای اضافی می‌تواند سطح حمله را کمتر کند، اما این یک میان‌بُر برای امنیت نیست. image کوچک هنوز ممکن است وابستگی آسیب‌پذیر، تنظیمات بد یا کاربر root داشته باشد. پس «کوچک‌تر» را با «امن» مساوی نگذار.

Multi-stage often makes an image cleaner and can reduce attack surface because fewer tools and packages remain at runtime. But “smaller equals secure” is not a valid claim: you still need separate checks for non-root execution, patches, dependencies, configuration, and application behavior.

وقتی COPY --from خراب می‌شود، هنوز به runtime نرسیده‌ایWhen COPY --from fails, runtime has not started yet

حالا عمداً یک اشتباه ساده بساز: نام مرحله را در COPY --from غلط بنویس. ممکن است متن خطا کمی عجیب باشد و حتی شبیه تلاش برای پیدا کردن image دیگری دیده شود. قبل از دست‌کاری ده خط Dockerfile، فقط یک سؤال بپرس: «اسمی که اینجا نوشته‌ام دقیقاً با FROM ... AS ... یکی است؟»

Create this failure deliberately: write COPY --from=build /app/dist ./dist while the stage is actually named builder. The error may mention pulling or not finding an image named build; wording varies by builder.

[runtime 1/2] COPY --from=build /app/dist ./dist
------
> [runtime 1/2] COPY --from=build /app/dist ./dist:
------
failed to solve: pull access denied for build,
repository does not exist or may require authorization

این خطا هیچ ربطی به خراب‌بودن container نهایی ندارد؛ container هنوز ساخته نشده. اگر نام مرحله درست بود، قدم بعدی مسیر فایل است. COPY --from فایل را از داخل همان مرحله می‌خواند، نه از پوشه‌ای روی سیستم تو. همین تفکیک جلوی خیلی از تغییرهای تصادفی را می‌گیرد.

Docker is not saying that the final container is broken; no container has been created yet. First compare the name with FROM ... AS .... If the name is correct, check the path next: COPY --from reads from the root of the builder filesystem, not from the host’s current directory.

دو خطا دیگر هم آموزشی‌اند: اگر RUN npm run build را حذف کنی، /app/dist تولید نمی‌شود؛ اگر به‌جای /app/dist مسیر خیالی مثل /app/build بدهی، builder خروجی build را پیدا نمی‌کند. هر دو قبل از runtime رخ می‌دهند.

Two more failures are useful: if you remove RUN npm run build, /app/dist is never produced; if you use a fictional path such as /app/build instead of /app/dist, the builder cannot find the artifact. Both happen before runtime.

۱۸ تمرین: اول پیش‌بینی، بعد اجرا18 exercises: predict first, then run

این ۱۸ تمرین قرار نیست هجده بار یک قالب تکراری را پر کنی. بعضی‌جا فقط پیش‌بینی می‌کنی، بعضی‌جا خروجی build را می‌خوانی و بعضی‌جا باید قبل از تغییر Dockerfile بگویی مشکل احتمالاً کجاست. جواب را زود باز نکن؛ اول یک دلیل برای حدست بنویس.

The exercises are intentionally varied. Some ask you to measure size and history, some test stage and cache reasoning, and some ask you to name the broken boundary before touching the Dockerfile.

آزمایشگاه کامل: از image سنگین تا runtime تمیزFull lab: from a heavy image to a clean runtime

مدل نهایی را با خودت ببرCarry the final model with you

اگر بخواهیم کل فصل را در یک تصویر نگه داریم: builder کارگاه است، فایل خروجی محصول است و مرحلهٔ آخر جعبهٔ تحویل. multi-stage چیزی را جادویی پنهان نمی‌کند؛ فقط مجبورمان می‌کند آگاهانه بگوییم چه چیزی از کارگاه وارد جعبه شود. همین انتخاب صریح است که image نهایی را تمیزتر و قابل‌فهم‌تر می‌کند.

Multi-stage is not a magic box that hides files. You create a build environment, produce an artifact with a path contract, start a fresh runtime, and explicitly transfer only what is needed. Then you measure size, history, command, and real behavior separately.

مرجع سریعQuick reference