1432 字

7 分鐘

Docker Compose type: image 出現 No such image？先升級 Compose 5.5.0

Q: 可以把 source 改成 sha256: 當 workaround 嗎？

不建議把造成問題的 digest 直接當成 image volume source。Compose 文件把 source 定義為 image reference，而官方修正也特別把 mount source 和追蹤 digest 分開。優先升級包含 #14041 的 Compose；若不能升級，改用其他 mount 方式前先確認它符合原本部署語意。

2026-08-27

伺服器

Docker

/

/

/

/

如果 docker compose up 在使用 type: image volume 時出現下面這類錯誤：

1
Error response from daemon: No such image: sha256:<digest>

先不要急著把 image 重建很多次，也不要直接執行會刪除資料的 docker compose down -v。Docker Compose 官方 issue 已記錄一個和 containerd image store 有關的 bug，Compose pull request #14041 修正後，並在 Compose v5.5.0 release 列出。第一個處理方向是確認 Compose 版本並升級到至少 5.5.0，再用原本的 image mount 重跑回歸。

先確認是不是同一個問題#

先記錄 Compose、Docker daemon 和 image 的狀態：

1
docker compose version
2
docker version
3
docker info
4
docker image inspect imgvol-source

如果環境同時符合以下條件，和官方 issue 的症狀相當接近：

Compose service 使用 long syntax 的 type: image volume。
source 指向本機已有的 image tag。
Docker 使用 containerd image store。
docker compose up 回報找不到 sha256:<digest>，但 image tag 看起來存在。

這個錯誤訊息容易把排錯帶到「image 根本沒 pull 到」，但官方 issue 的重現案例正是 image 存在時仍以 digest 失敗。先保留 docker compose version、docker version、docker info 和完整錯誤，之後才有辦法判斷是版本 bug、image reference 問題，還是其他 daemon 狀態。

最小重現：`type: image` 會把 image 掛進 consumer#

Compose services 文件把 image 列為 volume long syntax 的 type 之一，source 是 Docker image reference。官方 issue 使用的最小結構如下：

1
services:
2
  source:
3
    build: .
4
    image: imgvol-source
5

6
  consumer:
7
    image: alpine
8
    depends_on:
9
      - source
10
    command: ["cat", "/data/content.txt"]
11
    volumes:
12
      - type: image
13
        source: imgvol-source
14
        target: /data

搭配一個會產生 /content.txt 的簡單 build context，預期 consumer 能讀出檔案。官方 issue 在 Compose 5.4.0、Docker 29.4.0 和 containerd image store 組合下，記錄到 consumer 啟動時解析 sha256 失敗。

錯誤的根因：manifest digest 被當成 mount source#

這不是單純「tag 消失」的故事。官方修正說明指出，containerd image store 回傳的 ImageSummary.ID 可能是 platform-specific manifest digest。舊版 Compose 把這個 digest 重用為 image volume 的 mount source，但 daemon 解析這個欄位時期待的是 image name／tag 或可接受的 top-level image ID，於是出現 No such image: sha256:...。

#14041 的修正方向是保留解析出來的 image name 作為 mount source，另外用 com.docker.compose.image-volume-digest label 追蹤 digest。換句話說，問題出在 Compose 將「用來追蹤 image 變更的識別值」和「daemon 要掛載的 image reference」混用了。

建議修復流程#

1. 升級 Compose，再保留原始設定#

先確認版本：

1
docker compose version

把 Compose 升級到包含 #14041 的 v5.5.0 或更新版本。不要先改成一個新的 digest、刪除所有 volume，或把問題藏在另一份 compose 檔；先讓修正版本使用原本的 image reference 驗證。

2. 重新拉取或建置，然後重跑最小路徑#

依你的 service 是 pull 還是 build，執行對應的更新：

1
docker compose pull
2
docker compose build
3
docker compose up -d
4
docker compose ps
5
docker compose logs --tail=200 consumer

若 service 使用本機 build，pull 不一定會處理它；若不需要清除 cache，不要為了排錯直接加上 --no-cache。重點是確認升級後 Compose 仍能用 source: imgvol-source 建立 image mount，且 consumer 真的讀到預期內容。

Compose v5.5.0 release notes 也提醒，升級後第一次執行可能因 image digest reconciliation 而重新建立既有 container。安排維護窗口，先確認 container 裡沒有只存在於 writable layer 的未備份資料，再觀察 docker compose ps 和應用程式 logs。

3. 回歸 image mount 的實際語意#

不要只看到 up 成功就結束。至少驗證：

source image 的內容和預期版本一致。
consumer 讀到的檔案、權限和路徑正確。
image 更新後，Compose 能依預期判斷是否需要重建 consumer。
有多平台 image 時，實際執行平台仍取得正確 manifest。
CI、開發機和 production 使用的 Compose plugin 版本一致。

如果原本只是想共享 build output，也可以評估 named volume、bind mount 或直接把檔案打包進 consumer image；但這些方式的權限、可重現性和部署語意不同，不能把它們當成無痛 workaround。

若 image mount 修好後仍然是「服務啟動太早」而不是 image 解析錯誤，再延伸檢查 Docker Compose healthcheck 與 service_healthy 的啟動順序，這是另一個獨立的 Compose 問題。

升級前不要用破壞性清理掩蓋問題#

以下指令可能會影響資料，不能當成第一反應：

1
docker compose down -v
2
docker system prune

down -v 會移除 Compose 管理的 named volume；system prune 的影響範圍也可能超出目前專案。若你要測試乾淨環境，先列出 volumes、image、container 和 backup，再在明確的測試 project name 或隔離環境操作。這個 issue 的核心修正是 Compose 解析 image reference 的方式，不是要求使用者先刪光本機狀態。

常見問題#

Q: `No such image: sha256` 是否代表 image 一定不存在？#

A: 不一定。官方 Compose issue 的重現情境是 image tag 已存在，但 containerd image store 回傳的 digest 被舊版 Compose 當成 mount source，daemon 因而無法以該值解析。先比對 image tag、Compose 版本和 image store，再判斷是否真的缺 image。

Q: 升級到 Compose 5.5.0 後會不會刪掉 container 資料？#

A: release notes 說第一次執行可能因 digest reconciliation 重新建立既有 container；這和 down -v 主動刪除 volume 不同，但仍應在維護窗口測試。先備份需要保留的資料，並確認資料在 volume、bind mount 或外部服務，而不是只在 container writable layer。

Q: 可以把 `source` 改成 `sha256:<digest>` 當 workaround 嗎？#

A: 不建議把造成問題的 digest 直接當成 image volume source。Compose 文件把 source 定義為 image reference，而官方修正也特別把 mount source 和追蹤 digest 分開。優先升級包含 #14041 的 Compose；若不能升級，改用其他 mount 方式前先確認它符合原本部署語意。

參考資料：

Docker Compose issue #14005：type image volume 的 No such image

Docker Compose pull request #14041：修正 image volume digest

Docker Compose v5.5.0 release notes

Docker Compose services 文件：volume type image