Dockerfile 指令逐一

Dockerfile 指令 每個指令的用意與 copy-exact 範例。以 Docker 官方 Dockerfile 參考為準（截至 2026-06）。

指令一覽

指令	用意
`FROM`	指定基底映像，必須是第一條有效指令；`AS <name>` 替 stage 命名
`RUN`	build 期間執行指令（裝套件、編譯）。每條 `RUN` 是一層
`CMD`	容器啟動時的預設指令，可被 `docker run` 後接的指令覆蓋
`ENTRYPOINT`	容器啟動時固定執行的進入點，`docker run` 的參數不覆蓋它
`COPY`	把 context 的檔案複製進映像（最常用）
`ADD`	同 COPY，但多了自動解壓 tar 與下載 URL（一般優先 COPY）
`ENV`	設環境變數，留在映像、容器執行時可見
`ARG`	build 期變數，`--build-arg` 傳入，不留在映像
`WORKDIR`	設工作目錄（不存在會自動建），取代 `RUN cd`
`EXPOSE`	文件性質宣告監聽埠，不會真的開埠
`VOLUME`	標記某路徑為外部 volume 掛載點
`USER`	設後續指令與容器的執行身分（建議切非 root）
`LABEL`	加中繼資料（取代已棄用的 `MAINTAINER`）
`HEALTHCHECK`	定義健康檢查指令
`ONBUILD`	延遲觸發：本映像被當基底時才執行
`SHELL`	覆蓋 shell form 用的 shell
`STOPSIGNAL`	`docker stop` 時送的信號（預設 SIGTERM）

RUN 的 shell form 與 exec form

# Shell form（包在 /bin/sh -c，會做變數展開與管線）
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl git \
    && rm -rf /var/lib/apt/lists/*

# Exec form（JSON 陣列，不過 shell）
RUN ["/bin/bash", "-c", "echo $HOME"]

合併多條 RUN 成一條（用 && 與 \）可減少層數，並把 apt 快取在同一層清掉。

三組常混的差異

CMD vs ENTRYPOINT
COPY vs ADD
ARG vs ENV

CMD 是「預設指令」，docker run myimg 其他指令 會整個覆蓋 CMD。
ENTRYPOINT 是「固定進入點」，docker run 後接的參數會附加在 ENTRYPOINT 之後，不覆蓋它。
常見組合：ENTRYPOINT 放固定執行檔、CMD 放可被覆蓋的預設參數。
兩者都用 exec form（JSON 陣列），PID 1 才是應用程式本身，才能正確收到 SIGTERM 做優雅關閉；shell form 會包一層 /bin/sh -c，signal 傳不進去。

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8000"]
# docker run img             → python app.py --port 8000
# docker run img --port 9000 → python app.py --port 9000

完整互動：

	ENTRYPOINT 無	`ENTRYPOINT ["ep"]`（exec）	`ENTRYPOINT ep`（shell）
CMD 無	錯誤	`ep`	`/bin/sh -c ep`
`CMD ["cmd"]`	`cmd`	`ep cmd`	`/bin/sh -c ep`（CMD 被忽略）
`CMD cmd`	`/bin/sh -c cmd`	`ep /bin/sh -c cmd`	`/bin/sh -c ep`（CMD 被忽略）

	COPY	ADD
本地檔案複製	是	是
自動解壓本地 tar	否	是
下載遠端 URL	否	是
`--from` 跨 stage	是	否

官方建議優先用 COPY：語義單純、可預期。只有真的需要「解壓 tar」或「下載 URL」時才用 ADD，而且 ADD 下載 URL 的快取與認證行為複雜，多數情況用 RUN curl 反而更清楚可控。

COPY requirements.txt .
COPY --from=builder /app/dist /usr/share/nginx/html   # 跨 stage
COPY --chown=appuser:appgroup . /app                  # 設擁有者

	ARG	ENV
可在 FROM 前宣告	是	否
留在最終映像	否	是
容器執行時可見	否	是
CLI 傳入	`--build-arg`	`docker run --env`
進 `docker history`	否（預設）	是

ARG 是 build 期的暫時變數，ENV 會固化進映像。ARG 有個作用域雷：在 FROM 前宣告的全域 ARG，進到 stage 裡會失效，要在 stage 內重新 ARG 宣告一次才用得到。同名時 ENV 蓋過 ARG。

ARG PYTHON_VERSION=3.12-slim
FROM python:${PYTHON_VERSION}
ARG PYTHON_VERSION          # 進 stage 後要重新宣告才有值
RUN echo "built on ${PYTHON_VERSION}"

僅 build 期需要的變數（如 DEBIAN_FRONTEND）別用 ENV（會污染執行期），改 inline 或 ARG：

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get install -y tzdata

其他常用指令範例

WORKDIR /app                    # 設工作目錄，相對路徑相對於前一個 WORKDIR
EXPOSE 8000                     # 文件性質，實際開埠靠 docker run -p
ENV APP_ENV=production PORT=8080
USER 1001:1001                  # 切非 root（用 UID:GID 不依賴 user database）
LABEL org.opencontainers.image.authors="dev@example.com"
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost/ || exit 1
STOPSIGNAL SIGTERM

EXPOSE 只是宣告，不會真的開埠；USER 不存在的使用者要先 RUN useradd 建立。

接下來

配合 Python 程式：把這些指令兜成可用的 Dockerfile。
Layer cache 與最佳實踐：指令順序與快取。

官方參考：docs.docker.com/reference/dockerfile

​指令一覽

​RUN 的 shell form 與 exec form

​三組常混的差異

​其他常用指令範例

​接下來

指令一覽

RUN 的 shell form 與 exec form

三組常混的差異

其他常用指令範例

接下來