By name: container-image-hygiene
description: 在使用 Podman/Docker 建構容器映像檔後自動清理 dangling images，避免產生大量 映像檔佔用磁碟空間。適用於本專案使用 podman compose build/docker compose build 建構 image、需要保持系統乾淨、排查為何 image prune 後仍殘留 的情境。
license: Complete terms in LICENSE.txt
容器映像檔清潔（Build 後自動清理）
等級：基礎 預估時間：2-10 分鐘 最後更新：2026-01-26
目標
- 建構映像檔後自動清理 dangling images（常見為
<none>） - 降低磁碟被大量舊 image 佔滿的風險
- 提供安全（保守）與進階（較激進）兩種清理模式
快速開始（建議）
在專案根目錄執行以下建構腳本：
- Windows：
.github/skills/container-image-hygiene/scripts/build.ps1 - Linux/Mac：
.github/skills/container-image-hygiene/scripts/build.sh
Windows（Podman）
# 建構 + 自動清理 dangling images
.\.github\skills\container-image-hygiene\scripts\build.ps1
# 強制重新建構（不使用快取）+ 自動清理
.\.github\skills\container-image-hygiene\scripts\build.ps1 -Force
# 只建構不清理
.\.github\skills\container-image-hygiene\scripts\build.ps1 -NoPrune
# 若你希望同時清理停止中的容器（可協助移除仍被引用的舊 image）
.\.github\skills\container-image-hygiene\scripts\build.ps1 -PruneContainers
Linux/Mac（Docker 或 Podman）
# 建構 + 自動清理 dangling images
./.github/skills/container-image-hygiene/scripts/build.sh
# 強制重新建構（不使用快取）+ 自動清理
./.github/skills/container-image-hygiene/scripts/build.sh --force
# 只建構不清理
./.github/skills/container-image-hygiene/scripts/build.sh --no-prune
# 若你希望同時清理停止中的容器（可協助移除仍被引用的舊 image）
./.github/skills/container-image-hygiene/scripts/build.sh --prune-containers
保守清理（只清 dangling images）
此模式最安全：只刪除「沒有 tag 且不再被引用」的 dangling images。
podman image prune -f
驗證：
# 應該回傳空或很少
podman images -f "dangling=true"
進階清理（處理 prune 後仍殘留的大型 ）
如果你看到仍有大型 <none>（例如 8GB）存在，常見原因是：
- 有容器（包含停止狀態）仍引用該 image
- 該 image 不是 dangling（例如仍被 build cache/容器引用），因此
image prune不會移除
Step 1：找出哪些容器還在用該 image
podman ps -a --format "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}"
也可以用 image ID 檢查「是否仍被任何容器當作 ancestor（祖先層）引用」：
podman ps -a --filter ancestor=<IMAGE_ID>
若發現停止容器引用舊 image，可選擇刪除停止容器（注意：會刪掉容器本體，但不會刪除你的專案檔案與 bind mount 來源資料夾）。
podman container prune -f
Step 2：再做一次 image prune
podman image prune -f
仍刪不掉怎麼辦？（常見：layer 仍被新 image 共用）
如果 podman images -f "dangling=true" 仍看到大型 <none>，而 podman ps -a --filter ancestor=<IMAGE_ID> 也有回傳容器，代表該 image 的 layers 仍被目前的 image/容器共用；此時 image prune 不會移除它。
處理方式（依你可接受的中斷程度選擇）：
- 最保守：先不動它；等你下一次以
--no-cache重建並汰換容器後，再清理。 - 可接受重建/停機：停止並移除相關容器 → 移除依賴的較新 image → 再移除該
<none>image，最後用--no-cache重建。
較激進模式（不建議預設開啟）
如果你確定要把「所有未被使用的 images」一起清掉（可能包含 base image，之後需要重新下載），可使用：
# 刪除所有未被使用的 images（比 dangling 更廣）
podman image prune -a -f
或整體清理（可能影響更多資源：停止容器、未使用網路、未使用 image）：
podman system prune -f
常見注意事項
- 不要在重要容器仍在跑時做激進清理：保守的
podman image prune -f通常沒問題，但-a/system prune可能影響你預期外的資源。 - 大量
<none>的根因：通常是反覆用同一個 tag（例如latest）重建，舊版本就會變成 untagged；因此「建構後自動清理」是最省心做法。
檢查清單
- 建構流程使用
.github/skills/container-image-hygiene/scripts/build.ps1/.github/skills/container-image-hygiene/scripts/build.sh - 建構後執行過
podman image prune -f - 若仍殘留大型
<none>，已檢查並清掉停止容器後再 prune