映像檔太肥怎麼辦:換小的基底映像檔,用多階段建置把編譯工具留在前一階段,再用 .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 範例。

為什麼你需要知道
- 映像檔越大,每一步都越慢:推上倉庫、部署到雲端、新機器第一次下載,都要搬這麼多資料;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 密碼。檔案大小只是小事,密碼外洩才是大事。

動手做:同一個程式,三種寫法比大小
在 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

光是基底映像檔就下載了好幾層,最大一層 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

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

輸出裡的步驟分成兩組: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

--format 讓 docker images 只印名稱和大小(第 3 篇講過 Docker 29 預設格式的欄位不一樣);grep -E "A|B" 是「符合 A 或 B 的行都留下」。SIZE 是映像檔在硬碟上實際佔的空間。
算一次差多少:
| 寫法 | 大小 | 跟完整版比 |
|---|---|---|
完整版單階段 pyweb:full | 1.64GB(約 1,640MB) | 基準 |
slim 單階段 pyweb:slim | 201MB | 1,640 ÷ 201 ≈ 8.2 倍小,少了約 88% |
多階段 pyweb:multi | 204MB | 1,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

小了 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 從最上面(最新)往下列出每一層。我們自己加的只有上面 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

步驟全部 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

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

成功了。幾個重點:
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

(2>&1 | tail -4 是把建置輸出只留最後 4 行,避免洗版。)
| 需要編譯的版本 | 大小 | 能不能用 |
|---|---|---|
slim 單階段 pg-slim | 建不起來 | ✗ pg_config not found |
完整版單階段 pg-full | 1.64GB | ✓ |
多階段 pg-multi | 211MB | ✓ psycopg2 2.9.13 |
1,640 ÷ 211 ≈ 7.8 倍小。這才是多階段建置的主場:需要編譯工具才裝得起來,但執行時不需要它們。

動手做:.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

步驟 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

看 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

密碼直接被讀出來了。任何拿到這個映像檔的人(同事、推上 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

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

.env 和 data 都不見了,cat .env 回 No such file or directory。大小從 411MB 變回 201MB,差的 210MB 剛好就是那個 200MB 的資料夾。
| 沒有 .dockerignore | 有 .dockerignore | |
|---|---|---|
| 送進建置的資料 | 209.77MB | 187B |
| 建置時間 | 10.3 秒 | 5.4 秒 |
| 映像檔大小 | 411MB | 201MB |
.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 刪映像檔,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 篇會講 |
| .dockerignore | Cloud 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)
延伸閱讀
本系列
- 第 1 篇:Docker 入門教學:不用安裝,用 Cloud Shell 跑出第一個容器
- 第 3 篇:Docker 映像檔和容器差在哪?Image、Layer、Tag 白話解釋
- 第 4 篇:Dockerfile 怎麼寫?從零打包你的第一個網頁映像檔
- 第 6 篇:容器之間怎麼連線?Docker Network 與 Port 對應實作
- 上一篇:第 7 篇:Docker Compose 教學:一個 YAML 開起網站+資料庫
- 下一篇:第 9 篇:K8s 架構白話:Kubernetes 控制平面、節點、Pod 怎麼分工(撰寫中)
站上相關文章
- 容器 (Container) 技術是什麼?從零開始看懂 Docker 與容器化應用
- 儲存容器映像檔的 Artifact Registry 簡介與上傳 Docker 映像檔教學
- Cloud Run 讀取 Secret Manager
- SAST 工具是什麼?GCP 上有類似工具嗎?
Docker 的基本功到這篇告一段落,下一段要進入 Kubernetes。如果你想有系統地從容器一路學到在 Google Cloud 上部署服務,可以看看東東的 GCP 課程,或加 LINE 聊聊你現在的狀況,一起找出最適合你的學習順序。