Stage 01

image 裡到底放了什麼?

檔案沒放進去、密碼被打包進去,或掛載後原本的檔案不見了,先從這裡查。

  1. 1. 檢查 build context 與忽略規則

    Docker COPY 找不到檔案怎麼修?先確認 build context 與 .dockerignore

    Docker 出現 COPY failed 或 file not found in build context 時,先確認建置指令的 context、Dockerfile 相對路徑與 .dockerignore,再決定要改 COPY 還是調整目錄。

  2. 2. 在建置時傳入 secrets

    Docker Build secrets 怎麼用?用 --secret 取代 ARG 與 ENV

    Docker 建置需要 npm token、私有套件憑證或 SSH 金鑰時,本文比較 ARG、ENV、secret mount 與 SSH mount,示範 required、BuildKit cache 與 GitHub Actions 驗證,避免金鑰進 image。

  3. 3. 排查掛載遮住 image 檔案

    Docker 掛載後 node_modules 不見?bind mount 會遮住 image 裡的檔案

    Docker image 建置時已安裝依賴,Compose 啟動後卻找不到 node_modules,先確認 bind mount 是否蓋住工作目錄。本文用 image 與容器 Mounts 的對照流程區分 COPY、掛載與舊 volume,說明縮小掛載範圍和更新依賴的選擇,避免為排錯刪掉資料庫 volume。

  4. 4. 排查 image volume 的 No such image

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

    Docker Compose 的 type: image volume 在 containerd image store 可能出現 No such image: sha256。本文拆解 image mount、digest 與 Compose 5.5.0 修正,附上版本檢查、最小重現與升級後回歸清單。

Stage 02

設定改了卻沒生效?

分清環境變數什麼時候被讀取,哪些改動要重建容器才會套用。

  1. 5. 區分 env_file 與變數插值

    Docker Compose 的 env_file 與 ${VAR} 怎麼分?解決變數插值為空

    Docker Compose 的 service env_file 不會自動填入 image、port 或 build 的 ${VAR}。本文分開解析階段與容器環境,說明多份 --env-file 被 shell 覆蓋的原因、必填值檢查與只讀取 image 的診斷流程,避免將含密碼的解析設定直接寫進 CI log。

  2. 6. 選擇 secrets 與 configs

    Docker Compose secrets 與 configs 怎麼選?從環境變數改成檔案掛載

    Docker Compose 的 secrets 適合密碼、API key 等敏感資料,configs 適合可公開的執行期設定。本文用最小 compose.yaml 比較兩者與 ENV、file、external 的差異,補上驗證和風險邊界,避免把秘密留在 image 或 log。

  3. 7. 讓環境變數修改進入新容器

    Docker Compose 改了環境變數沒生效?restart 不會重建容器

    Docker Compose 改了 .env、env_file 或 compose.yaml 後,docker compose restart 仍可能讀到舊環境變數。本文說明 restart 與 up --force-recreate 的差別,並用 config 驗證重建前的實際值。

Stage 03

服務啟動順序亂掉?

讓服務等到依賴真的準備好,再開始工作。

  1. 8. 等待相依服務就緒

    Docker Compose 啟動順序怎麼等服務就緒:healthcheck 與 service_healthy

    Docker Compose 的 depends_on 不代表資料庫已可連線。本文示範以 healthcheck 與 service_healthy 等待服務就緒,消除啟動競態並說明重啟與應用程式重試的分工。

  2. 9. 安排啟動前的初始化工作

    Docker Compose pre_start 怎麼用?用 init container 做啟動前準備

    Docker Compose 5.3.0 起可用 pre_start,在主服務啟動前依序執行獨立的 init container。本文示範 migration 與資料夾權限準備,並比較 entrypoint、post_start、depends_on 與 per_replica 的執行邊界。

Stage 04

設定檔越來越亂?

專案變大後把設定拆開,開發工具只在需要時才啟動。

  1. 10. 拆分 Compose 設定檔

    Docker Compose include 怎麼拆檔:先釐清路徑、變數與名稱衝突

    Docker Compose 的 include 可拆分服務設定檔,但相對路徑、.env 優先順序與資源名稱衝突都會影響結果。本文整理拆檔前後的檢查重點、驗證指令,以及多人協作時的服務所有權安排。

  2. 11. 依情境啟動除錯工具

    Docker Compose profiles 怎麼用:把本機除錯工具與正式服務分開啟動

    Docker Compose profiles 可讓同一份 compose.yaml 依需求啟動除錯、監控或測試服務。本文整理 profiles 的啟用方式、依賴陷阱、驗證指令與 include 的分工。

  3. 12. 區分檔案同步與 image 重建

    Docker Compose Watch 怎麼用?用 sync、rebuild 分開本機開發流程

    Docker Compose Watch 會根據檔案變更同步、重啟或重建服務。本文用 develop.watch 拆分原始碼、設定檔與依賴檔,並說明 Docker Compose 版本、權限、ignore 與 node_modules 的排錯重點。