適合:自己架服務的人、用 Docker Compose 開發的工程師
Docker Compose 排錯
容器起來了,服務卻抓不到檔案、讀不到設定,或總是比資料庫早一步啟動?這裡沿著「image 裡有什麼、設定從哪來、誰先啟動」三個問題,帶你找出 Compose 卡住的原因。
image 裡到底放了什麼?
檔案沒放進去、密碼被打包進去,或掛載後原本的檔案不見了,先從這裡查。
- 1. 檢查 build context 與忽略規則
Docker COPY 找不到檔案怎麼修?先確認 build context 與 .dockerignore
Docker 出現 COPY failed 或 file not found in build context 時,先確認建置指令的 context、Dockerfile 相對路徑與 .dockerignore,再決定要改 COPY 還是調整目錄。
- 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. 排查掛載遮住 image 檔案
Docker 掛載後 node_modules 不見?bind mount 會遮住 image 裡的檔案
Docker image 建置時已安裝依賴,Compose 啟動後卻找不到 node_modules,先確認 bind mount 是否蓋住工作目錄。本文用 image 與容器 Mounts 的對照流程區分 COPY、掛載與舊 volume,說明縮小掛載範圍和更新依賴的選擇,避免為排錯刪掉資料庫 volume。
- 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 修正,附上版本檢查、最小重現與升級後回歸清單。
設定改了卻沒生效?
分清環境變數什麼時候被讀取,哪些改動要重建容器才會套用。
- 5. 區分 env_file 與變數插值
Docker Compose 的 env_file 與 ${VAR} 怎麼分?解決變數插值為空
Docker Compose 的 service env_file 不會自動填入 image、port 或 build 的 ${VAR}。本文分開解析階段與容器環境,說明多份 --env-file 被 shell 覆蓋的原因、必填值檢查與只讀取 image 的診斷流程,避免將含密碼的解析設定直接寫進 CI log。
- 6. 選擇 secrets 與 configs
Docker Compose secrets 與 configs 怎麼選?從環境變數改成檔案掛載
Docker Compose 的 secrets 適合密碼、API key 等敏感資料,configs 適合可公開的執行期設定。本文用最小 compose.yaml 比較兩者與 ENV、file、external 的差異,補上驗證和風險邊界,避免把秘密留在 image 或 log。
- 7. 讓環境變數修改進入新容器
Docker Compose 改了環境變數沒生效?restart 不會重建容器
Docker Compose 改了 .env、env_file 或 compose.yaml 後,docker compose restart 仍可能讀到舊環境變數。本文說明 restart 與 up --force-recreate 的差別,並用 config 驗證重建前的實際值。
服務啟動順序亂掉?
讓服務等到依賴真的準備好,再開始工作。
- 8. 等待相依服務就緒
Docker Compose 啟動順序怎麼等服務就緒:healthcheck 與 service_healthy
Docker Compose 的 depends_on 不代表資料庫已可連線。本文示範以 healthcheck 與 service_healthy 等待服務就緒,消除啟動競態並說明重啟與應用程式重試的分工。
- 9. 安排啟動前的初始化工作
Docker Compose pre_start 怎麼用?用 init container 做啟動前準備
Docker Compose 5.3.0 起可用 pre_start,在主服務啟動前依序執行獨立的 init container。本文示範 migration 與資料夾權限準備,並比較 entrypoint、post_start、depends_on 與 per_replica 的執行邊界。
設定檔越來越亂?
專案變大後把設定拆開,開發工具只在需要時才啟動。
- 10. 拆分 Compose 設定檔
Docker Compose include 怎麼拆檔:先釐清路徑、變數與名稱衝突
Docker Compose 的 include 可拆分服務設定檔,但相對路徑、.env 優先順序與資源名稱衝突都會影響結果。本文整理拆檔前後的檢查重點、驗證指令,以及多人協作時的服務所有權安排。
- 11. 依情境啟動除錯工具
Docker Compose profiles 怎麼用:把本機除錯工具與正式服務分開啟動
Docker Compose profiles 可讓同一份 compose.yaml 依需求啟動除錯、監控或測試服務。本文整理 profiles 的啟用方式、依賴陷阱、驗證指令與 include 的分工。
- 12. 區分檔案同步與 image 重建
Docker Compose Watch 怎麼用?用 sync、rebuild 分開本機開發流程
Docker Compose Watch 會根據檔案變更同步、重啟或重建服務。本文用 develop.watch 拆分原始碼、設定檔與依賴檔,並說明 Docker Compose 版本、權限、ignore 與 node_modules 的排錯重點。