Dockerfile 發行說明

本頁包含有關 Dockerfile 參考資料中的新功能、改進、已知問題和錯誤修正的資訊。

如需使用方式，請參閱Dockerfile 前端語法頁面。

1.18.0

2025-09-03

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.18.0

新增對遠端建置上下文的 Git URL 支援，並且 `ADD` 命令現在允許使用 `?key=value` 格式新增查詢參數的新語法，以更好地控制 Git 複製程序。本次發行版中支援的選項有 `ref`、`tag`、`branch`、`checksum` (別名 `commit`)、`subdir`、`keep-git-dir` 和 `submodules`。 moby/buildkit#6172 moby/buildkit#6173
新增檢查規則 `ExposeProtoCasing` 和 `ExposeInvalidFormat` 以改進 `EXPOSE` 命令的使用方式。 moby/buildkit#6135
修正如果使用具名上下文，則建立時間未從基礎映像檔正確設定的問題。 moby/buildkit#6096

1.17.0

2025-06-17

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.17.0

新增 `ADD --unpack=bool` 以控制是否解壓縮來自 URL 路徑的壓縮檔。預設情況下，會像以前的版本一樣，根據來源路徑偵測解壓縮行為。 moby/buildkit#5991
在解壓縮壓縮檔時，新增對 `ADD --chown` 的支援，類似於複製一般檔案時。 moby/buildkit#5987

1.16.0

2025-05-22

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.16.0

Git URL 的 `ADD --checksum` 支援。 moby/buildkit#5975
允許 heredocs 中存在空白字元。 moby/buildkit#5817
`WORKDIR` 現在支援 `SOURCE_DATE_EPOCH`。 moby/buildkit#5960
保留基礎映像檔為 WCOW 設定的預設 PATH 環境變數。 moby/buildkit#5895

1.15.1

2025-03-30

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.15.1

修正當使用 `--attest type=sbom` 時，針對 `linux/arm64/v8` 找不到掃描目標的問題。 moby/buildkit#5941

1.15.0

2025-04-15

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.15.0

無效目標的建置錯誤現在會顯示正確可能名稱的建議。 moby/buildkit#5851
修正 SBOM 證明針對 Windows 目標產生錯誤的問題。 moby/buildkit#5837
修正遞迴 `ARG` 在處理大綱請求時產生無限迴圈的問題。 moby/buildkit#5823
修正從 JSON 解析語法指令的問題，如果 JSON 包含字串以外的資料類型，則會失敗。 moby/buildkit#5815
修正映像檔設定中的平台處於非正規化形式的問題 (1.12 版的迴歸)。 moby/buildkit#5776
修正當 WCOW 中不存在目標目錄時，複製到目標目錄的問題。 moby/buildkit#5249

1.14.1

2025-03-05

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.14.1

正規化映像檔設定中的平台。 moby/buildkit#5776

1.14.0

2025-02-19

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.14.0

`COPY --chmod` 現在允許非八進位值。此功能以前在實驗版通道中，現在已在主要發行版中提供。 moby/buildkit#5734
修正如果基礎映像檔設定了 OSVersion 平台屬性時的處理。 moby/buildkit#5714
修正具名上下文中繼資料可能被解析的錯誤，即使當前的建置配置無法存取它，導致建置錯誤。 moby/buildkit#5688

1.14.0 (實驗版)

2025-02-19

重要
實驗版通道讓您可以存取尚未在穩定通道中提供的實驗性 Dockerfile 功能。

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker.io/docker/dockerfile-upstream:1.14.0-labs

新的 `RUN --device=name,[required]` 標誌允許建置請求 CDI 裝置可在建置步驟中使用。需要 BuildKit v0.20.0+ moby/buildkit#4056、moby/buildkit#5738

1.13.0

2025-01-20

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.13.0

新的內建建置參數 `TARGETOSVERSION`、`BUILDOSVERSION` 適用於 Windows 建置，且 `TARGETPLATFORM` 值現在也包含 `OSVersion` 值。 moby/buildkit#5614
允許外部前端針對以位元組順序標記 (BOM) 開頭的檔案進行語法轉發。 moby/buildkit#5645
Windows 容器中的預設 `PATH` 已更新，包含 `powershell.exe` 目錄。 moby/buildkit#5446
修正 Dockerfile 指令解析以不允許無效語法。 moby/buildkit#5646
修正 `ONBUILD` 命令可能在繼承階段執行兩次的案例。 moby/buildkit#5593
修正 Dockerfile 子階段中可能遺失具名上下文替換的問題。 moby/buildkit#5596

1.13.0 (實驗版)

2025-01-20

重要
實驗版通道讓您可以存取尚未在穩定通道中提供的實驗性 Dockerfile 功能。

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker.io/docker/dockerfile-upstream:1.13.0-labs

修正 `COPY --chmod` 對非八進位值的支援。 moby/buildkit#5626

1.12.0

2024-11-27

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.12.0

修正針對具有多個 `ARG` 指令的映像檔配置，歷史記錄行中不正確的描述。 moby/buildkit#5508

1.11.1

2024-11-08

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.11.1

修正當在相同 Dockerfile 中繼承的階段中使用 `ONBUILD` 指令時發生的迴歸。 moby/buildkit#5490

1.11.0

2024-10-30

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.11.0

`ONBUILD` 指令現在支援參考其他階段或映像檔並使用 `from` 的命令，例如 `COPY --from` 或 `RUN mount=from=....`。 moby/buildkit#5357
`SecretsUsedInArgOrEnv` 建置檢查已改進以減少誤報。 moby/buildkit#5208
新的 `InvalidDefinitionDescription` 建置檢查建議建置參數和階段描述的註解格式。這是一個實驗性檢查。 moby/buildkit#5208、 moby/buildkit#5414
針對 `ONBUILD` 指令的進度與錯誤處理進行多項修正。 moby/buildkit#5397
改進了缺少標誌錯誤的錯誤報告。 moby/buildkit#5369
增強了針對以環境變數形式掛載的密碼值的進度輸出。 moby/buildkit#5336
新增內建建置參數 `TARGETSTAGE` 以公開當前建置的 (最終) 目標階段名稱。 moby/buildkit#5431

1.11.0 (實驗版)

重要
實驗版通道讓您可以存取尚未在穩定通道中提供的實驗性 Dockerfile 功能。

`COPY --chmod` 現在支援非八進位值。 moby/buildkit#5380

1.10.0

2024-09-10

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.10.0

建置密碼現在可以使用 `env=VARIABLE` 選項作為環境變數掛載。 moby/buildkit#5215
`#check` 指令現在允許新的實驗性屬性，以啟用實驗性驗證規則，例如 `CopyIgnoredFile`。 moby/buildkit#5213
改進對變數替換中不支援修飾符的驗證。 moby/buildkit#5146
`ADD` 和 `COPY` 指令現在支援針對 `--chmod` 選項值的建置參數進行變數內插。 moby/buildkit#5151
改進對 `COPY` 和 `ADD` 指令的 `--chmod` 選項的驗證。 moby/buildkit#5148
修正掛載點上 `size` 和 `destination` 屬性遺失自動完成的問題。 moby/buildkit#5245
OCI 註釋現在已設定到 Dockerfile 前端發行映像檔。 moby/buildkit#5197

1.9.0

2024-07-11

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.9.0

新增驗證規則
- SecretsUsedInArgOrEnv
- InvalidDefaultArgInFrom
- RedundantTargetPlatform
- `CopyIgnoredFile` (實驗性)
- FromPlatformFlagConstDisallowed
針對處理大型 Dockerfile 進行了多項效能改進。 moby/buildkit#5067、 moby/buildkit#5029
修正當建置未定義階段的 Dockerfile 時可能發生的程式崩潰問題。 moby/buildkit#5150
修正不正確的 JSON 解析，這可能導致一些不正確的 JSON 值通過而不產生錯誤。 moby/buildkit#5107
修正 `COPY --link` 在目標路徑為 `.` 時可能失敗的迴歸錯誤。 moby/buildkit#5080
修正當 `ADD --checksum` 與 Git URL 一起使用時的驗證。 moby/buildkit#5085

1.8.1

2024-06-18

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.8.1

錯誤修正與增強功能

修正變數擴展中空字串的處理。 moby/buildkit#5052
改進建置警告的格式。 moby/buildkit#5037、 moby/buildkit#5045、 moby/buildkit#5046
修正多階段建置中 `UndeclaredVariable` 警告可能產生無效輸出。 moby/buildkit#5048

1.8.0

2024-06-11

本次發行的完整發行說明可在GitHub上取得。

# syntax=docker/dockerfile:1.8.0

新增了許多驗證規則以驗證您的 Dockerfile 是否遵循最佳實踐。這些規則在建置期間進行驗證，新的 `check` 前端方法可以用來只觸發驗證而不完成整個建置。
新的 `#check` 指令與建置參數 `BUILDKIT_DOCKERFILE_CHECK` 讓您控制建置檢查的行為。 moby/buildkit#4962
現在會驗證使用不符合您預期平台的單一平台基礎映像檔。 moby/buildkit#4924
全域範圍中 `ARG` 定義擴展的錯誤現在已正確處理。 moby/buildkit#4856
`ARG` 預設值的擴展現在只會在使用者未覆寫的情況下發生。以前，擴展會完成，然後該值會被忽略，這可能導致意外的擴展錯誤。 moby/buildkit#4856
解析具有多個階段的巨大 Dockerfile 的效能已改進。 moby/buildkit#4970
修正一些 Windows 路徑處理的一致性錯誤。 moby/buildkit#4825

1.7.0

2024-03-06

穩定版

# syntax=docker/dockerfile:1.7

變數擴展現在允許字串替換和修剪。 moby/buildkit#4427、 moby/buildkit#4287
具有本地來源的具名上下文現在只會正確傳輸 Dockerfile 中使用的檔案，而不是完整的來源目錄。 moby/buildkit#4161
Dockerfile 現在更好地驗證階段的順序，如果階段順序不正確，則會返回包含堆疊追蹤的友善錯誤。 moby/buildkit#4568、 moby/buildkit#4567
歷史提交訊息現在包含與 `COPY` 和 `ADD` 一起使用的標誌。 moby/buildkit#4597
從 Git 和 HTTP 來源的 `ADD` 命令進度訊息已改進。 moby/buildkit#4408

實驗版

# syntax=docker/dockerfile:1.7-labs

`COPY` 新增了 `--parents` 標誌，用於在複製檔案時保留父目錄結構。 moby/buildkit#4598、 moby/buildkit#3001、 moby/buildkit#4720、 moby/buildkit#4728、文件
`COPY` 和 `ADD` 命令可以使用新的 `--exclude` 標誌，以對複製的檔案應用過濾器。 moby/buildkit#4561、文件

1.6.0

2023-06-13

新增功能

為 `HEALTHCHECK` 指令新增 `--start-interval` 標誌。

以下功能已從實驗版通道升級到穩定版

`ADD` 指令現在可以直接從 Git URL 匯入檔案
`ADD` 指令現在支援`--checksum` 標誌以驗證遠端 URL 內容

錯誤修正與增強功能

變數替換現在支援額外的 POSIX 相容變體，不帶 `:`。 moby/buildkit#3611
匯出的 Windows 映像檔現在包含來自基礎映像檔的 `OSVersion` 和 `OSFeatures` 值。 moby/buildkit#3619
將 Heredocs 的權限更改為 0644。 moby/buildkit#3992

1.5.2

2023-02-14

錯誤修正與增強功能

修正從缺少分支名稱但包含子目錄的 Git 參考建置的問題
386 平台映像檔現在已包含在發行版中

1.5.1

2023-01-18

錯誤修正與增強功能

修正多平台建置中出現警告條件時可能發生的程式崩潰問題

1.5.0 (實驗版)

2023-01-10

重要
實驗版通道讓您可以存取尚未在穩定通道中提供的實驗性 Dockerfile 功能。

新增功能

`ADD` 命令現在支援`--checksum` 標誌以驗證遠端 URL 內容

1.5.0

2023-01-10

新增功能

`ADD` 命令現在可以直接從 Git URL 匯入檔案

錯誤修正與增強功能

具名上下文現在支援 `oci-layout://` 協定，用於從本地 OCI 布局結構中包含映像檔
Dockerfile 現在支援次要請求，用於列出所有建置目標或列印特定建置目標的接受參數大綱
重新導向到外部前端映像檔的 Dockerfile `#syntax` 指令現在也允許使用 `//` 註解或 JSON 設定該指令。該檔案也可能包含 shebang 標頭
具名上下文現在可以使用空的 scratch 映像檔進行初始化
具名上下文現在可以使用 SSH Git URL 進行初始化
修正導入 Schema1 映像檔時 `ONBUILD` 的處理

1.4.3

2022-08-23

錯誤修正與增強功能

修正從 `docker-image://` 具名上下文建置映像檔時，建立時間戳記未重設的問題
修正載入 `docker-image://` 具名上下文時，`FROM` 命令的 `--platform` 標誌傳遞問題

1.4.2

2022-05-06

錯誤修正與增強功能

修正從建置上下文傳遞的映像檔載入特定環境變數的問題

1.4.1

2022-04-08

錯誤修正與增強功能

修正當輸入是針對不同平台建置時，針對輸入進行交叉編譯情況的具名上下文解析

1.4.0

2022-03-09

新增功能

`COPY --link` 和 `ADD --link` 允許以提高快取效率的方式複製檔案，並在不需重新建置的情況下重設映像檔基礎。 `--link` 將檔案複製到獨立的層，然後使用新的 LLB MergeOp 實作將獨立的層鏈接在一起
Heredocs 支援已從實驗版通道升級到穩定版。此功能允許編寫多行內聯指令碼和檔案
額外的具名建置上下文可以傳遞給建置，以在建置中新增或覆寫階段或映像檔。上下文的來源可以是本地來源、映像檔、Git 或 HTTP URL
`BUILDKIT_SANDBOX_HOSTNAME` 建置參數可用於設定 `RUN` 步驟的預設主機名稱