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

1.15.1

2025-03-30

此版本的完整發布說明可在 GitHub 上查閱。

# syntax=docker/dockerfile:1.15.1
  • 修復了使用 `--attest type=sbom` 時出現 `no scan targets for 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

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

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

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

1.11.0 (實驗室)

重要提示

實驗室通道讓您可以使用尚未在穩定通道中提供的實驗性 Dockerfile 功能。

1.10.0

2024-09-10

此版本的完整發布說明可在 GitHub 上查閱。

# syntax=docker/dockerfile:1.10.0

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 時可能發生的 panic。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

錯誤修復和增強

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

實驗室

# syntax=docker/dockerfile:1.7-labs

1.6.0

2023-06-13

新增

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

錯誤修復和增強

1.5.2

2023-02-14

錯誤修復和增強

  • 修復了從缺少分支名稱但包含子目錄的 Git 引用構建的問題
  • 386 平臺映象現在包含在釋出版中

1.5.1

2023-01-18

錯誤修復和增強

  • 修復了在多平臺構建中出現警告條件時可能發生的 panic

1.5.0 (實驗室)

2023-01-10
重要提示

實驗室通道讓您可以使用尚未在穩定通道中提供的實驗性 Dockerfile 功能。

新增

1.5.0

2023-01-10

新增

錯誤修復和增強

  • 命名上下文現在支援 `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` 步驟設定預設主機名

錯誤修復和增強

  • 使用交叉編譯階段時，現在在進度輸出中顯示步驟的目標平臺
  • 修復了 Heredocs 錯誤地從內容中刪除引號的某些情況

1.3.1

2021-10-04

錯誤修復和增強

  • 修復瞭解析不帶值的“required”掛載鍵的問題

1.3.0 (實驗室)

2021-07-16
重要提示

實驗室通道讓您可以使用尚未在穩定通道中提供的實驗性 Dockerfile 功能。

新增

1.3.0

2021-07-16

新增

  • RUN 命令允許 --network 標誌用於請求特定型別的網路條件。--network=host 需要允許 `network.host` 授權。此功能之前僅在實驗室通道中可用。

錯誤修復和增強

1.2.1 (實驗室)

2020-12-12
重要提示

實驗室通道讓您可以使用尚未在穩定通道中提供的實驗性 Dockerfile 功能。

錯誤修復和增強

  • RUN 命令允許 --network 標誌用於請求特定型別的網路條件。--network=host 需要允許 `network.host` 授權

1.2.1

2020-12-12

錯誤修復和增強

  • 恢復“確保 ENTRYPOINT 命令至少有一個引數”
  • 最佳化多平臺交叉編譯構建上的 `COPY` 呼叫處理

1.2.0 (實驗室)

2020-12-03
重要提示

實驗室通道讓您可以使用尚未在穩定通道中提供的實驗性 Dockerfile 功能。

錯誤修復和增強

  • 實驗性通道已重新命名為 _labs_

1.2.0

2020-12-03

新增

  • RUN --mount 語法，用於建立 secret、ssh、bind 和 cache 掛載，已移至主通道
  • ARG 命令現在支援在同一行定義多個構建引數，類似於 ENV

錯誤修復和增強

  • 元資料載入錯誤現在作為致命錯誤處理，以避免不正確的構建結果
  • 允許小寫 Dockerfile 名稱
  • ADD 中的 --chown 標誌現在允許引數擴充套件
  • ENTRYPOINT 至少需要一個引數，以避免建立損壞的映象

1.1.7

2020-04-18

錯誤修復和增強

  • 將 `FrontendInputs` 轉發到閘道器

1.1.2 (實驗室)

2019-07-31
重要提示

實驗室通道讓您可以使用尚未在穩定通道中提供的實驗性 Dockerfile 功能。

錯誤修復和增強

  • 允許使用 RUN --security=sandbox|insecure 為程序設定安全模式
  • 允許為快取掛載設定 uid/gid
  • 避免請求內部連結路徑被拉取到構建上下文
  • 確保缺失的快取 ID 預設為目標路徑
  • 允許使用 BUILDKIT_CACHE_MOUNT_NS 構建引數設定快取掛載的名稱空間

1.1.2

2019-07-31

錯誤修復和增強

  • 修復了使用正確使用者建立工作目錄的問題，並且不重置自定義所有權
  • 修復了同時用作 `ENV` 的空構建引數的處理
  • 檢測迴圈依賴

1.1.0

2019-04-27

新增

  • ADD/COPY 命令現在支援基於 llb.FileOp 的實現，如果內建檔案操作支援可用，則無需輔助映象
  • COPY 命令的 --chown 標誌現在支援變數擴充套件

錯誤修復和增強

  • 為了查詢從構建上下文忽略的檔案，Dockerfile 前端將首先查詢檔案 `<path/to/Dockerfile>.dockerignore`，如果未找到，則會從構建上下文的根目錄查詢 `.dockerignore` 檔案。這允許包含多個 Dockerfile 的專案使用不同的 `.dockerignore` 定義