docker build 指令：參數說明與範例

docker build 依照 Dockerfile 建置映像檔。Dockerfile 的寫法見 Dockerfile 入門 與 Dockerfile 指令大全，這一頁整理指令本身的參數。

語法

docker build [參數] 建置內容路徑

最常見的形式：

docker build -t myapp:1.0 .

-t 命名映像檔，最後的 . 是建置內容（build context）：目前資料夾的檔案會交給建置程式，Dockerfile 預設也從這裡讀取。docker build 與 docker buildx build、docker image build 是同一個指令。

常用參數

完整列表可以執行 docker build --help 查看。

範例專案

以下範例都使用這個多階段 Dockerfile：

FROM alpine:3.23 AS base
ARG GREETING=hello
RUN echo "$GREETING from build" > /greeting.txt

FROM base AS test
RUN cat /greeting.txt && echo "tests passed"

FROM base
CMD ["cat", "/greeting.txt"]

另外有一個 Dockerfile.dev，內容只有 FROM alpine:3.23 和 CMD ["echo", "dev image"]。

-t：建置並命名

$ docker build -t greet .

[+] Building 0.6s (6/6) FINISHED                                                                                                       docker:default
 => [internal] load build definition from Dockerfile                                                                                             0.0s
 => => transferring dockerfile: 235B                                                                                                             0.0s
 => [internal] load metadata for docker.io/library/alpine:3.23                                                                                   0.1s
 => [internal] load .dockerignore                                                                                                                0.0s
 => => transferring context: 2B                                                                                                                  0.0s
 => CACHED [base 1/2] FROM docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                 0.0s
 => => resolve docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                             0.0s
 => [base 2/2] RUN echo "hello from build" > /greeting.txt                                                                                       0.3s
 => exporting to image                                                                                                                           0.1s
 => => exporting layers                                                                                                                          0.0s
 => => exporting manifest sha256:0d0e8696cb61970ffeebe21706f795d44bb7fdb22662a328bd83a22c9cb91d60                                                0.0s
 => => exporting config sha256:04f0467aef1baf360852e9f8633e676c7cbbcbe454d0827bbdd474dcda4a7d1f                                                  0.0s
 => => exporting attestation manifest sha256:186d1197793b26cefb32e3555067d8caaa7d626310efb2c1eeb6c42bfefb01a1                                    0.0s
 => => exporting manifest list sha256:2632bf33adbcb3cffc3697245d5e0ad0d239b58b46413d39f87e29cbbebfb3ef                                           0.0s
 => => naming to docker.io/library/greet:latest                                                                                                  0.0s
 => => unpacking to docker.io/library/greet:latest                                                                                               0.0s

$ docker run --rm greet
hello from build

[base 2/2] 表示這是 base 階段的第 2 步。test 階段沒有被建置：沒有指定 --target 時只建置最後一個階段，以及它依賴的階段。

--build-arg：傳入建置參數

$ docker build -q --build-arg GREETING=hi -t greet:hi .
sha256:c6f108c2247535f2ee548ef5868bdf83911f06e7ecfeab0fb58eb47b19c79154

$ docker run --rm greet:hi
hi from build

GREETING 的預設值是 hello，用 --build-arg GREETING=hi 覆蓋後，建置出的檔案內容變成 hi from build。ARG 只在建置時存在，不要用來傳遞密碼（原因見 安全最佳實務）。

-f：指定 Dockerfile

$ docker build -q -f Dockerfile.dev -t greet:dev .
sha256:59849c87b388414a149e72c98ff88d30d9b575f5240625c0b8f58332ce5103fb

$ docker run --rm greet:dev
dev image

同一個專案可以有多個 Dockerfile，例如 Dockerfile.dev、Dockerfile.prod。注意 -f 只決定讀哪個 Dockerfile，建置內容仍然是最後的 .。

--target 與 --progress plain：只建置測試階段並看完整輸出

$ docker build --target test --progress plain --no-cache . 2>&1 | grep -E "^#[0-9]+ [0-9.]+ |DONE|ERROR" | grep -v DONE
#6 0.210 hello from build
#6 0.210 tests passed

• --target test 只建置到 test 階段，常用來在 CI 中執行測試。
• --progress plain 顯示 RUN 指令的完整輸出（hello from build、tests passed）。預設的輸出模式在步驟成功後會把輸出摺疊起來。
• --no-cache 確保 RUN 真的重新執行，而不是使用快取。
• 這裡用 grep 只留下 RUN 的輸出行；#6 0.210 表示第 6 個步驟、開始後 0.210 秒。

結果

$ docker build -q --target base -t greet:base .
sha256:b92f520e3598da9bcb7ceb2cf82977090316062325363faae1d65c3630423b8e

$ docker images greet
IMAGE          ID             DISK USAGE   CONTENT SIZE   EXTRA
greet:base     b92f520e3598       12.9MB         3.85MB        
greet:dev      59849c87b388       12.9MB         3.85MB        
greet:hi       c6f108c22475       12.9MB         3.85MB        
greet:latest   2632bf33adbc       12.9MB         3.85MB

四個映像檔大小相同，因為它們都只是在 Alpine 上加了一個小檔案。

其他常用寫法

# 同時加上兩個名稱
docker build -t myapp:1.2.0 -t myapp:latest .

# 建置內容是子資料夾，Dockerfile 在別處
docker build -f docker/Dockerfile.prod -t myapp ./src

# 重新下載基礎映像檔並且不用快取（完全重建）
docker build --pull --no-cache -t myapp .

# 建置給 amd64 伺服器（在 Apple Silicon Mac 上）
docker build --platform linux/amd64 -t myapp .

# 建置時使用機密
docker build --secret id=npm_token,env=NPM_TOKEN -t myapp .

相關章節

• Dockerfile 入門、Dockerfile 指令大全
• 建置快取與最佳化：快取的運作方式
• 多階段建置：--target 的更多用法
• 多平台映像檔：--platform
• 常見錯誤訊息：建置失敗的排查

動手練習

練習：用本頁的 Dockerfile，建置一個 GREETING 為 hey 的映像檔，並同時命名為 greet:hey 和 greet:latest。

docker build --build-arg GREETING=hey -t greet:hey -t greet:latest .
docker run --rm greet:latest

更新於 2026年10月14日