映像檔太肥怎麼辦?Docker 多階段建置與 .dockerignore

映像檔太肥怎麼辦:換小的基底映像檔,用多階段建置把編譯工具留在前一階段,再用 .dockerignore 擋掉多餘檔案。

同一個不到 20 行的 Flask 網頁程式,用 python:3.14 打包是 1.64GB,換個寫法只要 204MB,差了 8 倍。更糟的是,沒注意的話,你放在資料夾裡的 .env 密碼會被一起打包進映像檔,任何拿到映像檔的人都讀得到。

這篇在 Cloud Shell 實際比一次:完整版、slim、多階段建置三種寫法各多大;遇到需要編譯的套件(連 PostgreSQL 用的 psycopg2)時,slim 為什麼裝不起來、多階段怎麼解;最後示範沒有 .dockerignore 時,200MB 的垃圾和密碼怎麼被打包進去。

這是「容器系列」的第 8 篇,也是 Docker 段落的最後一篇。全部在免費的 Cloud Shell 實際跑過,輸出都是真實結果(2026 年 11 月實測,Docker 29.9.3、Python 3.14.10)。程式沿用第 4 篇:Dockerfile 怎麼寫?的 Flask 範例。

多階段建置的比喻:第一階段是廚房,有鍋具和瓦斯爐(gcc、完整工具);第二階段是便當,只放做好的菜,COPY --from=builder 把菜裝進便當

為什麼你需要知道

  • 映像檔越大,每一步都越慢:推上倉庫、部署到雲端、新機器第一次下載,都要搬這麼多資料;1.64GB 和 204MB 下載時間差很多
  • 雲端放映像檔要錢:Google 的 Artifact Registry 依儲存量計費,同一個服務每次更新都存一版,肥的映像檔會一直累積
  • 裝了用不到的東西=多了被攻擊的地方:編譯器、除錯工具留在正式環境的映像檔裡,萬一被入侵,等於送攻擊者一整箱工具
  • 密碼外洩很常發生:COPY . . 會把資料夾裡所有東西打包,包括 .env、.git;映像檔一推上公開倉庫,密碼就公開了

映像檔為什麼會肥?

第 3 篇講過,映像檔是一層一層疊起來的。最底下是你在 FROM 寫的基底映像檔(Base Image),上面再疊你自己的套件和程式。所以映像檔會肥,通常是這三個原因:

原因例子解法
基底映像檔太大python:3.14 裡有編譯器、各種開發套件改用 -slim
建置時才需要的工具留在最後為了編譯套件裝了 gcc,跑程式其實用不到多階段建置
打包了不該打包的檔案COPY . . 把資料、.env、.git 全搬進去.dockerignore

Python 官方映像檔的三種版本

標籤白話適合
python:3.14完整版:Debian 系統+很多常用的開發套件(含 gcc、各種 -dev 檔)需要編譯東西的建置階段
python:3.14-slim精簡版:只有跑 Python 需要的最少東西大部分正式環境
python:3.14-alpine用 Alpine Linux 做的極小版本想要最小,但要小心相容性

Docker Hub 的 Python 官方映像檔說明(2026 年 11 月查)寫得很清楚:slim 版沒有編譯工具,需要從原始碼編譯的套件,pip install 可能會失敗;alpine 版用的是 musl 而不是一般 Linux 常見的 glibc,軟體常常會遇到問題。所以 Python 專案通常先選 slim,不輕易用 alpine。

版本補充:這篇跟第 4 篇一樣用 Python 3.14(實測裝的是 3.14.10)。2026 年 11 月 Docker Hub 上的最新版已經是 3.15,換版本時把標籤改掉就好,寫法不變。


多階段建置是什麼?

白話是什麼

多階段建置(multi-stage build)是在同一個 Dockerfile 裡寫好幾個 FROM,每個 FROM 開始一個新階段。前面的階段負責「準備」(下載、編譯、安裝),最後一個階段只用 COPY --from= 把需要的成品拿過來,其他工具和暫存檔全部丟在前面的階段。只有最後一個階段會變成你的映像檔。

比喻:廚房和便當

做便當要用到鍋子、瓦斯爐、砧板(第一階段:廚房),但客人拿到的只有便當盒裡的菜(第二階段)。你不會把瓦斯爐一起裝進便當送出去。多階段建置就是把「廚房」和「便當」分開寫。

來龍去脈

在多階段建置出現以前(Docker 17.05,2017 年),想要小映像檔,得寫兩個 Dockerfile、用腳本把第一個建出來的檔案複製到外面,再餵給第二個。官方文件(2026 年 11 月查)說明現在一個檔案就能做到:「可以有選擇地把一個階段的東西複製到另一個階段,把不需要的全部留在後面」。官方的建置最佳實務也建議用兩種基底映像檔:一個負責建置和測試,另一個(通常更精簡的)負責正式執行。

為什麼要學

Go、Java、Node.js 這類需要「先編譯或打包,再執行」的語言,多階段建置幾乎是標準寫法。Python 則是在套件需要編譯時特別有用,等一下會實際遇到。


.dockerignore 是什麼?

白話是什麼

.dockerignore 是一份「不要送進建置的檔案清單」,放在 Dockerfile 旁邊,寫法跟 Git 的 .gitignore 很像,一行一個規則。

來龍去脈:建置內容(build context)

docker build -t 名字 . 最後那個 .,意思是「把目前這個資料夾當作建置內容(build context)」。Docker 會先把整個資料夾打包送給建置程式,Dockerfile 裡的 COPY 才拿得到檔案。官方文件說明,符合 .dockerignore 規則的檔案,在送出之前就會被排除,所以 COPY 也拿不到它們。

比喻:搬家前先列一張「不要搬」的清單,搬家公司根本不會把那些東西裝上車,新家當然也不會出現。

為什麼要學

沒有 .dockerignore,COPY . . 會把資料夾裡所有東西搬進映像檔:測試資料、本機的虛擬環境、.git 版本紀錄、.env 密碼。檔案大小只是小事,密碼外洩才是大事。

.dockerignore 範例:.env、data/、.git/、__pycache__/、*.pyc、Dockerfile*,各自為什麼不該進映像檔

動手做:同一個程式,三種寫法比大小

在 test27 的 Cloud Shell(不用建專案、不用綁信用卡)實作,大約 15 分鐘,不花錢。第一次要下載約 400MB 的 Python 完整版映像檔。截圖裡的提示字元有縮短,你的畫面會是「你的帳號@cloudshell:~/slimdemo$」。

步驟 1:準備程式

跟第 4 篇一樣的 Flask 網頁,建在新的 ~/slimdemo 資料夾:

mkdir -p ~/slimdemo && cd ~/slimdemo
cat > app.py <<'EOF'
import os
import socket
from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    hostname = socket.gethostname()
    app_env = os.environ.get("APP_ENV", "not set")
    return f"""
<h1>Hello from my first Docker image!</h1>
<p>Container ID (hostname): {hostname}</p>
<p>APP_ENV: {app_env}</p>
"""

if __name__ == "__main__":
    port = int(os.environ.get("PORT", 8080))
    app.run(host="0.0.0.0", port=port)
EOF
echo "flask==3.1.3" > requirements.txt

步驟 2:完整版 python:3.14,單階段

cat > Dockerfile.full <<'EOF'
FROM python:3.14
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.full -t pyweb:full .

-f 是指定要用哪個 Dockerfile(預設找名字剛好叫 Dockerfile 的檔案),這篇會有好幾個版本,所以用 -f 切換。

[+] Building 35.1s (10/10) FINISHED                                        docker:default
 => [internal] load build definition from Dockerfile.full                            0.0s
 => [internal] load metadata for docker.io/library/python:3.14                       1.2s
 => [1/5] FROM docker.io/library/python:3.14@sha256:e5de6bc932256f8138c2353023dc4fd24d010d72f6b5cb06be126f0a4cd537  14.4s
 => => sha256:30a939f32c3666529658895da478296143998cbf9bbb6ede9e0ea68655ef8804 29.89MB / 29.89MB     0.8s
 => => sha256:696c1fe91c64662be9b13aa92628d62d6685ab94c0b55d185258a8f762133deb 237.23MB / 237.23MB   3.1s
 => => sha256:411d2dc8717dbb4bb0d3cfa27e6e0275fca455c5220029d7a14dc7a75fbe8665 67.82MB / 67.82MB     1.5s
 => => sha256:e8a88afca2bd37d4058d4b33d9d4d29b0557f8b811bb8c106942b5b51e1e4aad 25.63MB / 25.63MB     1.2s
 => => sha256:a6dd1c05fbba4f9028078a11f143cbb625d2408921eb8207bfa1dd1ad301276f 49.41MB / 49.41MB     1.0s
(中間省略)
 => [4/5] RUN pip install --no-cache-dir -r requirements.txt                         4.5s
 => [5/5] COPY app.py .                                                              0.0s
 => exporting to image                                                              13.4s
(中間省略)
 => => naming to docker.io/library/pyweb:full                                        0.0s
 => => unpacking to docker.io/library/pyweb:full                                    12.6s
docker build -f Dockerfile.full 用 python:3.14 完整版建置,光下載基底映像檔就有一層 237.23MB,總共 35.1 秒

光是基底映像檔就下載了好幾層,最大一層 237.23MB,整個建置花 35.1 秒,其中解開檔案(unpacking)就花了 12.6 秒。

步驟 3:換成 slim,單階段

只改 FROM 那一行:

cat > Dockerfile.slim <<'EOF'
FROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.slim -t pyweb:slim .
[+] Building 9.0s (10/10) FINISHED                                         docker:default
 => [internal] load build definition from Dockerfile.slim                            0.0s
 => [internal] load metadata for docker.io/library/python:3.14-slim                  0.8s
 => [1/5] FROM docker.io/library/python:3.14-slim@sha256:9aaa474097d094040649f2162a627c0049b408f52138d980916788d80f  1.6s
 => => sha256:0e665593ff40197b851364fab0389fc6f5fa35bc74814ddfad07f96f417fc574 12.41MB / 12.41MB     0.4s
 => => sha256:d6d089a6c0a2543e3dd748a4ffcbfe409ab93f2049d42640588be3a3f67acffe 1.29MB / 1.29MB       0.3s
(中間省略)
 => [4/5] RUN pip install --no-cache-dir -r requirements.txt                         4.1s
 => [5/5] COPY app.py .                                                              0.1s
 => exporting to image                                                               1.6s
(中間省略)
 => => naming to docker.io/library/pyweb:slim                                        0.0s
docker build -f Dockerfile.slim 用 python:3.14-slim 建置,下載的層只有 12.41MB 和 1.29MB,9.0 秒完成

9.0 秒就好了,下載的層只有 12.41MB 這種等級。

步驟 4:多階段建置

cat > Dockerfile.multi <<'EOF'
# 第一階段:builder,用完整版映像檔,把套件裝進 /opt/venv
FROM python:3.14 AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 第二階段:正式映像檔,只從 builder 拿裝好的套件
FROM python:3.14-slim
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.multi -t pyweb:multi .

一行一行看重點:

寫法意思
FROM python:3.14 AS builder開始第一階段,取名叫 builder(名字自己取)
RUN python -m venv /opt/venv建一個 Python 虛擬環境(venv):一個獨立的資料夾,套件全裝在裡面,方便整包搬走
ENV PATH="/opt/venv/bin:$PATH"讓後面的 pip、python 都用這個虛擬環境裡的
FROM python:3.14-slim開始第二階段,基底換成 slim,前面階段的東西全部不會帶過來
COPY --from=builder /opt/venv /opt/venv只從 builder 把裝好套件的 /opt/venv 搬過來
[+] Building 13.6s (15/15) FINISHED                                        docker:default
 => [internal] load build definition from Dockerfile.multi                           0.9s
 => [internal] load metadata for docker.io/library/python:3.14                       0.9s
 => [internal] load metadata for docker.io/library/python:3.14-slim                  1.5s
 => [builder 1/5] FROM docker.io/library/python:3.14@sha256:e5de6bc932256f8138c2353023dc4fd24d010d72f6b5cb06be126f0  0.0s
 => [stage-1 1/4] FROM docker.io/library/python:3.14-slim@sha256:9aaa474097d094040649f2162a627c0049b408f52138d98091  3.3s
(中間省略)
 => CACHED [builder 2/5] WORKDIR /app                                                0.0s
 => [builder 3/5] RUN python -m venv /opt/venv                                       5.9s
 => [builder 4/5] COPY requirements.txt .                                            0.0s
 => [builder 5/5] RUN pip install --no-cache-dir -r requirements.txt                 2.9s
 => [stage-1 2/4] COPY --from=builder /opt/venv /opt/venv                            0.2s
 => [stage-1 3/4] WORKDIR /app                                                       0.0s
 => [stage-1 4/4] COPY app.py .                                                      0.0s
 => exporting to image                                                               1.8s
(中間省略)
 => => naming to docker.io/library/pyweb:multi                                       0.0s
docker build -f Dockerfile.multi 多階段建置,輸出分成 builder 和 stage-1 兩組步驟,COPY --from=builder 把 /opt/venv 搬到第二階段

輸出裡的步驟分成兩組:builder 1/5~5/5 是第一階段,stage-1 1/4~4/4 是第二階段(沒取名字的階段,Docker 自動叫它 stage-1)。builder 1/5 的完整版映像檔是 0.0s,因為步驟 2 已經下載過了。

步驟 5:三種寫法比大小

docker images --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}" | grep -E "REPOSITORY|pyweb"
REPOSITORY:TAG   SIZE
pyweb:multi      204MB
pyweb:full       1.64GB
pyweb:slim       201MB
docker images 比較三種寫法:pyweb:full 1.64GB、pyweb:slim 201MB、pyweb:multi 204MB

--format 讓 docker images 只印名稱和大小(第 3 篇講過 Docker 29 預設格式的欄位不一樣);grep -E "A|B" 是「符合 A 或 B 的行都留下」。SIZE 是映像檔在硬碟上實際佔的空間。

算一次差多少:

寫法大小跟完整版比
完整版單階段 pyweb:full1.64GB(約 1,640MB)基準
slim 單階段 pyweb:slim201MB1,640 ÷ 201 ≈ 8.2 倍小,少了約 88%
多階段 pyweb:multi204MB1,640 ÷ 204 ≈ 8.0 倍小

這裡有個誠實的結論:Flask 這種純 Python 套件不用編譯,直接用 slim 就有幾乎一樣的效果,多階段反而大了 3MB(虛擬環境本身的檔案)。多階段建置真正派上用場,是下面步驟 9「套件需要編譯」的時候。

步驟 6:確認多階段的映像檔能跑

docker run -d --name slimtest -p 8080:8080 pyweb:multi && sleep 3 && curl -s localhost:8080; docker rm -f slimtest
58286db6316d6a4221d57eece7f8fcc3d5a07d4404d47cb2f4c1f26bff70701a
<h1>Hello from my first Docker image!</h1>
<p>Container ID (hostname): 58286db6316d</p>
<p>APP_ENV: not set</p>
slimtest
用 pyweb:multi 開容器,curl 回傳 Hello from my first Docker image!,多階段建置的映像檔正常運作

小了 8 倍,照樣正常運作。sleep 3 是等 3 秒讓 Flask 啟動(第 2 篇講過太快 curl 會沒回應)。

步驟 7:用 docker history 看每一層多大

docker history pyweb:multi --format "table {{.CreatedBy}}\t{{.Size}}" | head -14
CREATED BY                                      SIZE
CMD ["python" "app.py"]                         0B
EXPOSE [8080/tcp]                               0B
COPY app.py . # buildkit                        12.3kB
WORKDIR /app                                    8.19kB
ENV PATH=/opt/venv/bin:/usr/local/bin:/usr/l…   0B
COPY /opt/venv /opt/venv # buildkit             20.2MB
CMD ["python3"]                                 0B
RUN /bin/sh -c set -eux;  for src in idle3 p…   16.4kB
RUN /bin/sh -c set -eux;   savedAptMark="$(a…   42.1MB
ENV PYTHON_SHA256=de414a57119abef52784d8993e…   0B
ENV PYTHON_VERSION=3.14.10                      0B
RUN /bin/sh -c set -eux;  apt-get update;  a…   4.93MB
ENV LANG=C.UTF-8                                0B
docker history pyweb:multi 顯示每一層的大小,COPY /opt/venv 這層 20.2MB,Python 本體 42.1MB,完整版映像檔的層一層都沒有

docker history 從最上面(最新)往下列出每一層。我們自己加的只有上面 6 行,最大的是 COPY /opt/venv 這層 20.2MB(Flask 和它的相依套件);再往下都是 slim 基底映像檔的層(Python 3.14.10 本體 42.1MB)。完整版 python:3.14 的層一層都沒有出現,第一階段整個被丟掉了。head -14 是只看前 14 行。

步驟 8:用 –target 只建到某個階段

想檢查第一階段長怎樣(例如除錯),可以用 --target 叫 Docker 只建到那個階段就停:

docker build -f Dockerfile.multi --target builder -t pyweb:builder . && docker images --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}" | grep -E "REPOSITORY|python|pyweb"
[+] Building 1.7s (10/10) FINISHED                                         docker:default
(中間省略)
 => CACHED [builder 2/5] WORKDIR /app                                                0.0s
 => CACHED [builder 3/5] RUN python -m venv /opt/venv                                0.0s
 => CACHED [builder 4/5] COPY requirements.txt .                                     0.0s
 => CACHED [builder 5/5] RUN pip install --no-cache-dir -r requirements.txt          0.0s
(中間省略)
 => => naming to docker.io/library/pyweb:builder                                     0.0s
REPOSITORY:TAG   SIZE
pyweb:multi      204MB
pyweb:builder    1.65GB
pyweb:full       1.64GB
docker build --target builder 只建第一階段,pyweb:builder 是 1.65GB,跟完整版差不多大

步驟全部 CACHED(第 4 篇講過的快取),1.7 秒就好。第一階段的映像檔是 1.65GB,跟完整版一樣肥,這就是我們丟掉的「廚房」。


動手做:遇到需要編譯的套件

步驟 9:slim 裝 psycopg2,失敗

psycopg2 是 Python 連 PostgreSQL 資料庫最常用的套件。它的正式版本要在安裝時編譯,需要 C 語言編譯器和 PostgreSQL 的開發檔案。拿 slim 試試:

printf 'flask==3.1.3\npsycopg2\n' > requirements-pg.txt
cat > Dockerfile.pg-slim <<'EOF'
FROM python:3.14-slim
WORKDIR /app
COPY requirements-pg.txt .
RUN pip install --no-cache-dir -r requirements-pg.txt
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.pg-slim -t pyweb:pg-slim .
(前面省略)
4.568       Error: pg_config executable not found.
4.568
4.568       pg_config is required to build psycopg2 from source.  Please add the directory
4.568       containing pg_config to the $PATH or specify the full executable path with the
4.568       option:
(中間省略)
4.568       If you prefer to avoid building psycopg2 from source, please install the PyPI
4.568       'psycopg2-binary' package instead.
(中間省略)
4.570 ERROR: Failed to build 'psycopg2' when getting requirements to build wheel
------
Dockerfile.pg-slim:4
--------------------
   2 |     WORKDIR /app
   3 |     COPY requirements-pg.txt .
   4 | >>> RUN pip install --no-cache-dir -r requirements-pg.txt
   5 |     COPY app.py .
   6 |     EXPOSE 8080
--------------------
ERROR: failed to build: failed to solve: process "/bin/sh -c pip install --no-cache-dir -r requirements-pg.txt" did not complete successfully: exit code: 1
slim 版安裝 psycopg2 失敗,錯誤訊息 pg_config executable not found,建議改用 psycopg2-binary

pg_config executable not found:slim 裡沒有 PostgreSQL 的開發工具,編譯不了。這正是 Python 官方映像檔說明警告的情況。錯誤訊息最後的方框標出是 Dockerfile 第 4 行出事(>>> 那行)。

這時有三條路:

做法結果
改用完整版 python:3.14裝得起來,但映像檔 1.64GB
在 slim 裡 apt-get install gcc 和開發檔案裝得起來,但編譯工具會留在映像檔裡
多階段建置在完整版裡編譯,只把成品搬到 slim

錯誤訊息也提到可以改用 psycopg2-binary(預先編譯好的版本,不用編譯)。這對 psycopg2 是一個解法,但不是每個需要編譯的套件都有現成的版本,多階段建置是通用的做法。

步驟 10:多階段建置,在廚房編譯、便當只帶成品

cat > Dockerfile.pg-multi <<'EOF'
# 第一階段:完整版映像檔有 gcc 和 libpq-dev,可以編譯 psycopg2
FROM python:3.14 AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements-pg.txt .
RUN pip install --no-cache-dir -r requirements-pg.txt

# 第二階段:slim 只補執行時需要的 libpq5,不裝編譯工具
FROM python:3.14-slim
RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.pg-multi -t pyweb:pg-multi .
[+] Building 15.9s (16/16) FINISHED                                        docker:default
(中間省略)
 => [builder 4/5] COPY requirements-pg.txt .                                         0.1s
 => [stage-1 2/5] RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/li  6.6s
 => [builder 5/5] RUN pip install --no-cache-dir -r requirements-pg.txt             13.6s
 => [stage-1 3/5] COPY --from=builder /opt/venv /opt/venv                            0.3s
 => [stage-1 4/5] WORKDIR /app                                                       0.0s
 => [stage-1 5/5] COPY app.py .                                                      0.0s
(中間省略)
 => => naming to docker.io/library/pyweb:pg-multi                                    0.0s
多階段建置 psycopg2 成功,builder 階段編譯 13.6 秒,第二階段只安裝 libpq5,兩個階段同時進行

成功了。幾個重點:

  • builder 5/5 花了 13.6 秒:這就是在完整版裡編譯 psycopg2 的時間,完整版有 gcc 和 PostgreSQL 開發檔案(libpq-dev)
  • 第二階段只裝 libpq5:這是 psycopg2 執行時需要的連線函式庫,跟編譯用的開發檔案不一樣,小很多。apt-get 是 Debian 系統的套件安裝工具,最後的 rm -rf /var/lib/apt/lists/* 把下載清單刪掉,省一點空間
  • stage-1 2/5 和 builder 5/5 同時在跑:兩個階段互不相干的步驟,BuildKit(Docker 現在的建置引擎)會平行處理,所以總時間 15.9 秒比各步驟加起來短

做一個完整版單階段來對照,再確認 psycopg2 真的能用:

cat > Dockerfile.pg-full <<'EOF'
FROM python:3.14
WORKDIR /app
COPY requirements-pg.txt .
RUN pip install --no-cache-dir -r requirements-pg.txt
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.pg-full -t pyweb:pg-full . 2>&1 | tail -4
docker run --rm pyweb:pg-multi python -c "import psycopg2; print('psycopg2', psycopg2.__version__)"
docker images --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}" | grep -E "REPOSITORY|python|pyweb"
#10 naming to docker.io/library/pyweb:pg-full done
#10 unpacking to docker.io/library/pyweb:pg-full
#10 unpacking to docker.io/library/pyweb:pg-full 0.3s done
#10 DONE 1.2s
psycopg2 2.9.13 (dt dec pq3 ext lo64)
REPOSITORY:TAG   SIZE
pyweb:pg-full    1.64GB
pyweb:pg-multi   211MB
pyweb:builder    1.65GB
pyweb:multi      204MB
pyweb:full       1.64GB
pyweb:pg-multi 裡 import psycopg2 成功,版本 2.9.13;pg-full 1.64GB、pg-multi 211MB

(2>&1 | tail -4 是把建置輸出只留最後 4 行,避免洗版。)

需要編譯的版本大小能不能用
slim 單階段 pg-slim建不起來✗ pg_config not found
完整版單階段 pg-full1.64GB✓
多階段 pg-multi211MB✓ psycopg2 2.9.13

1,640 ÷ 211 ≈ 7.8 倍小。這才是多階段建置的主場:需要編譯工具才裝得起來,但執行時不需要它們。

實測大小比較:純 Python 套件時 python:3.14 單階段 1.64GB、slim 201MB、多階段 204MB;需要編譯的 psycopg2,slim 建不起來、完整版 1.64GB、多階段 211MB

動手做:.dockerignore 擋住密碼和垃圾

步驟 11:放一個密碼檔和 200MB 的資料

模擬真實專案的資料夾:有一個放密碼的 .env,還有一個大資料夾。dd 是產生檔案的工具,這裡做出一個 200MB 的空白檔案;du -sh 是看資料夾多大。

printf 'SECRET_KEY=abc123-do-not-leak\n' > .env && mkdir -p data && dd if=/dev/zero of=data/big.bin bs=1M count=200 status=none && ls -A && du -sh data
app.py  Dockerfile.full   Dockerfile.pg-full   Dockerfile.pg-slim  requirements-pg.txt
data    Dockerfile.multi  Dockerfile.pg-multi  .env                requirements.txt
201M    data
資料夾裡有 .env 密碼檔和 201M 的 data 資料夾

步驟 12:沒有 .dockerignore,用 COPY . . 打包

很多教學會這樣寫:COPY . .,把整個資料夾複製進去。

cat > Dockerfile.copyall <<'EOF'
FROM python:3.14-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8080
CMD ["python", "app.py"]
EOF
docker build -f Dockerfile.copyall -t pyweb:copyall .
[+] Building 10.3s (9/9) FINISHED                                          docker:default
 => [internal] load build definition from Dockerfile.copyall                         0.0s
 => [internal] load metadata for docker.io/library/python:3.14-slim                  0.2s
 => [internal] load .dockerignore                                                    0.0s
 => => transferring context: 2B                                                      0.0s
(中間省略)
 => [internal] load build context                                                    1.0s
 => => transferring context: 209.77MB                                                1.0s
 => CACHED [2/4] WORKDIR /app                                                        0.0s
 => [3/4] COPY . .                                                                   2.4s
 => [4/4] RUN pip install --no-cache-dir -r requirements.txt                         4.2s
(中間省略)
 => => naming to docker.io/library/pyweb:copyall                                     0.0s
沒有 .dockerignore 時建置,transferring context 是 209.77MB,整個資料夾都送進建置

看 transferring context: 209.77MB:建置前要先把 209.77MB 的資料夾整包送過去,光這步就花 1 秒。進到映像檔裡看看:

docker run --rm pyweb:copyall ls -A
docker run --rm pyweb:copyall cat .env
.env
Dockerfile.copyall
Dockerfile.full
Dockerfile.multi
Dockerfile.pg-full
Dockerfile.pg-multi
Dockerfile.pg-slim
app.py
data
requirements-pg.txt
requirements.txt
SECRET_KEY=abc123-do-not-leak
映像檔裡有 .env、data 和所有 Dockerfile,cat .env 直接讀到 SECRET_KEY=abc123-do-not-leak

密碼直接被讀出來了。任何拿到這個映像檔的人(同事、推上 Docker Hub 後的任何人)只要一行指令就看得到。而且就算之後把 .env 從資料夾刪掉,已經推出去的映像檔裡還是有。

步驟 13:加上 .dockerignore 再建一次

cat > .dockerignore <<'EOF'
.env
data/
.git/
__pycache__/
*.pyc
Dockerfile*
EOF
docker build -f Dockerfile.copyall -t pyweb:copyall2 .
[+] Building 5.4s (9/9) FINISHED                                           docker:default
 => [internal] load build definition from Dockerfile.copyall                         0.0s
 => [internal] load metadata for docker.io/library/python:3.14-slim                  0.2s
 => [internal] load .dockerignore                                                    0.0s
 => => transferring context: 88B                                                     0.0s
(中間省略)
 => [internal] load build context                                                    0.0s
 => => transferring context: 187B                                                    0.0s
 => CACHED [2/4] WORKDIR /app                                                        0.0s
 => [3/4] COPY . .                                                                   0.0s
 => [4/4] RUN pip install --no-cache-dir -r requirements.txt                         4.0s
(中間省略)
 => => naming to docker.io/library/pyweb:copyall2                                    0.0s
加上 .dockerignore 後建置,transferring context 從 209.77MB 變成 187B

transferring context 從 209.77MB 變成 187B(B 是位元組,187 個字元而已),建置從 10.3 秒變 5.4 秒。* 是「任何字」,Dockerfile* 就是所有 Dockerfile 開頭的檔案。

docker run --rm pyweb:copyall2 ls -A
docker run --rm pyweb:copyall2 cat .env
docker images --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}" | grep -E "REPOSITORY|copyall"
.dockerignore
app.py
requirements-pg.txt
requirements.txt
cat: .env: No such file or directory
REPOSITORY:TAG   SIZE
pyweb:copyall2   201MB
pyweb:copyall    411MB
加了 .dockerignore 的映像檔裡沒有 .env 和 data,cat .env 找不到檔案,大小從 411MB 變 201MB

.env 和 data 都不見了,cat .env 回 No such file or directory。大小從 411MB 變回 201MB,差的 210MB 剛好就是那個 200MB 的資料夾。

沒有 .dockerignore有 .dockerignore
送進建置的資料209.77MB187B
建置時間10.3 秒5.4 秒
映像檔大小411MB201MB
.env 密碼讀得到不存在

最好的做法其實是不要用 COPY . .,像步驟 2 那樣只 COPY 需要的檔案(requirements.txt、app.py)。.dockerignore 是第二道保險,兩個一起用最安全。另外,.dockerignore 本身沒有排除自己,所以它出現在映像檔裡;它不含密碼,沒有關係。


實測時的意外

1. 純 Python 套件,多階段反而比 slim 大 3MB

原本預期多階段會最小,實測 pyweb:multi 204MB、pyweb:slim 201MB。差的 3MB 是虛擬環境本身的檔案(python -m venv 會在 /opt/venv 放一份 pip 等工具)。套件不需要編譯時,直接用 slim 就夠了,不用為了多階段而多階段。

2. 第一次就踩到「slim 裝不起來」

psycopg2 在 slim 直接失敗,錯誤是 pg_config executable not found。這不是 Docker 的問題,是 slim 刻意沒放編譯工具。遇到 pip install 在 slim 失敗、訊息提到 gcc、pg_config、Python.h 這類字,就是「需要編譯」的訊號,多階段建置是標準解法。

3. 第二階段還是要補「執行用」的函式庫

一開始很容易以為「編譯好搬過去就沒事」,但 psycopg2 執行時要呼叫 PostgreSQL 的連線函式庫,所以第二階段要 apt-get install libpq5。分辨方式:名字有 -dev 的是編譯用(留在 builder),沒有 -dev 的是執行用(第二階段要裝)。

4. 映像檔裡的檔案,刪了資料夾也拿不回來

步驟 12 的 .env 一旦被打包,之後改 .dockerignore 只對新建的映像檔有效。已經推上倉庫的舊映像檔要整個刪掉,而且密碼要當作已外洩,馬上換一組新的。


用完記得刪

這篇建了 8 個映像檔,Python 完整版又特別大,記得清乾淨:

docker rmi pyweb:full pyweb:slim pyweb:multi pyweb:builder pyweb:pg-multi pyweb:pg-full pyweb:copyall pyweb:copyall2
cd ~ && rm -rf ~/slimdemo
docker builder prune -f | tail -2
Untagged: pyweb:full
Deleted: sha256:fd6a389370cd98bc9b7fa8aea34f606a49cb86d7bb1c8ad58c8a9e0e67a06225
Untagged: pyweb:slim
Deleted: sha256:4d1fb71b21dc94d423aa02b8455a085679b1fe616cfa3927dc749929a0cbbde9
(中間省略)
Untagged: pyweb:copyall2
Deleted: sha256:a5933030f3d486f9d46f8945ff8d91d4f650602344dd531a5792e576a5aa4a28
b9ld1h3pmvy5mosy8c3kpfffx                       true    183.7MB         2 minutes ago
Total:  2.226GB
docker rmi 刪掉 8 個 pyweb 映像檔,docker builder prune 清掉 2.226GB 的建置快取

docker rmi 刪映像檔,rm -rf 刪練習資料夾(-r 連資料夾一起、-f 不詢問,打錯路徑會刪錯東西,一定要看清楚)。

docker builder prune -f 是清建置快取(第 4 篇講過,Docker 會把每一層記起來讓下次建置變快)。這次清出 2.226GB,比所有映像檔加起來還多,因為 Python 完整版的層和編譯過程都被快取了。Cloud Shell 的磁碟空間有限,建了大映像檔之後記得清。


到了 GCP 上叫什麼

這篇的觀念在 Google Cloud
多階段建置Cloud Build 照樣支援,Dockerfile 不用改,第 21 篇會用 Cloud Build 自動建置
映像檔大小推到 Artifact Registry 依儲存量計費,映像檔小、存得久的版本也不會累積太多費用,第 19 篇會講
.dockerignoreCloud Build 也會讀;另外 gcloud 上傳原始碼時看的是 .gcloudignore,規則寫法類似
gcloud run deploy --source .Cloud Run 從原始碼部署時,背後一樣是先建映像檔,Dockerfile 寫得好,部署就快,第 20 篇會實作
不要把密碼打包進映像檔改用 Secret Manager,執行時再讀進來

映像檔小的好處在雲端會被放大:每次部署、每台新機器、每個新的執行個體,都要下載一次映像檔。


面試/證照會怎麼問

面試常見題

題目回答重點
怎麼讓 Docker 映像檔變小?用小的基底映像檔(slim、distroless)、多階段建置、.dockerignore、合併 RUN 減少層數、清掉套件管理器的快取
多階段建置是什麼?解決什麼問題?一個 Dockerfile 多個 FROM,前面階段負責編譯,最後階段用 COPY --from 只拿成品,編譯工具不會進正式映像檔
--target 有什麼用?只建到指定階段,用來除錯或產生測試用的映像檔
.dockerignore 有什麼用?排除不該送進建置內容的檔案:讓建置更快、映像檔更小、避免密碼外洩
Python 專案用 alpine 好嗎?不一定。alpine 用 musl,很多套件沒有現成的編譯版本,可能要自己編譯、反而更大更慢;官方說明也提醒常有問題
密碼不小心打包進映像檔了怎麼辦?重建映像檔、刪掉外流的版本,並把密碼當作已外洩立刻換掉

Kubernetes 證照(CKAD、CKA)

CKAD、CKA 是在 Kubernetes 叢集裡上機實作的考試(依 Linux Foundation 官方頁,2026 年 11 月查:2 小時、445 美元、含 1 次補考、效期 2 年),不會考你寫 Dockerfile。但 CKAD 的考綱有「定義、建置和修改容器映像檔」相關的範圍,多階段建置是理解映像檔的基本功;工作上,映像檔越小,Pod 在新節點上啟動就越快。

看到這些字,就想到這個

題目出現的字想到
「映像檔太大」「減少攻擊面」slim/多階段建置
「建置時需要 gcc,執行時不需要」多階段建置
「COPY --from=」從前面的階段(或別的映像檔)複製檔案
「transferring context 很大」「build 很慢」加 .dockerignore
「.env 被打包」「密碼外洩」.dockerignore+只 COPY 需要的檔案+換密碼
「pg_config not found」「Python.h not found」套件需要編譯,slim 沒有工具

常見問答

Docker 映像檔太大要怎麼縮小?

先換小的基底映像檔,例如 Python 用 -slim 版;套件需要編譯時,用多階段建置在第一階段編譯、最後階段只放成品;再加上 .dockerignore 擋掉資料、.git、.env 這類不該打包的檔案。這篇實測同一個 Flask 程式,從完整版 1.64GB 縮到 204MB。

多階段建置(multi-stage build)是什麼?

在同一個 Dockerfile 裡寫好幾個 FROM,每個 FROM 是一個階段。前面的階段用完整工具下載、編譯、安裝,最後一個階段用 COPY –from=階段名稱 只把需要的成品搬過來。只有最後一個階段會成為映像檔,編譯工具和暫存檔都不會留下。

Python 用 slim 就好,還需要多階段建置嗎?

套件不需要編譯時,slim 就夠了:這篇實測 slim 單階段 201MB,多階段 204MB,差不多。但遇到需要編譯的套件(例如 psycopg2),slim 會出現 pg_config executable not found 而裝不起來,這時多階段建置可以在完整版裡編譯,最後的映像檔仍然只有 211MB。

.dockerignore 和 .gitignore 有什麼不同?

寫法很像,用途不同。.gitignore 決定哪些檔案不要放進 Git 版本控制;.dockerignore 決定哪些檔案不要送進 Docker 建置,所以 COPY 也拿不到它們。兩個檔案各管各的,.env 這類密碼檔兩邊都要寫。

COPY . . 有什麼問題?

它會把整個資料夾都複製進映像檔,包括 .env 密碼、測試資料、.git 版本紀錄。這篇實測沒有 .dockerignore 時,映像檔從 201MB 變成 411MB,而且 cat .env 直接讀得到密碼。建議只 COPY 需要的檔案,再用 .dockerignore 當第二道保險。

python:3.14、3.14-slim、3.14-alpine 要選哪個?

大部分情況選 slim:小、相容性好。完整版適合放在多階段建置的第一階段,負責編譯。alpine 最小,但它用 musl 而不是 glibc,Python 官方映像檔說明也提醒常會遇到問題,很多套件要自己編譯,新手不建議。

–target 是做什麼用的?

docker build –target 階段名稱,會只建到那個階段就停,產生的映像檔就是那個階段的樣子。常用在除錯(看看第一階段裝了什麼),或在同一個 Dockerfile 裡同時定義測試用和正式用的映像檔。


重點整理

  • 映像檔會肥的三個原因:基底映像檔太大、建置工具留在最後、打包了不該打包的檔案
  • slim 是 Python 的好起點:實測完整版 1.64GB、slim 201MB,差 8 倍
  • 多階段建置:多個 FROM、COPY --from=builder 只拿成品;需要編譯的 psycopg2 在 slim 裝不起來,多階段做出 211MB 的可用映像檔
  • .dockerignore:送進建置的資料從 209.77MB 變 187B、映像檔從 411MB 變 201MB,而且 .env 不會被打包;最好再配合「只 COPY 需要的檔案」
  • 清理:docker rmi 刪映像檔,docker builder prune 清建置快取(這次清出 2.226GB)

延伸閱讀

本系列

站上相關文章


Docker 的基本功到這篇告一段落,下一段要進入 Kubernetes。如果你想有系統地從容器一路學到在 Google Cloud 上部署服務,可以看看東東的 GCP 課程,或加 LINE 聊聊你現在的狀況,一起找出最適合你的學習順序。

Table of Contents
返回頂端