Compose 陷阱

depends_on

• depends_on: [db] 仅等待容器启动 — 不等服务就绪
• condition: service_healthy 需要定义 healthcheck — 否则静默失败
• 循环依赖不是错误 — compose 尝试解决但可能随机失败
• depends_on 不影响 docker compose run — 依赖服务不会启动

环境变量

• .env 必须在 docker-compose.yml 同目录 — 子目录中不会被读取
• ${VAR} 未定义 = 空字符串，不报错 — 静默 bug
• ${VAR:-default} 仅在 VAR 未定义时生效 — VAR="" 使用空值，不用默认值
• env_file 不接受 export 语法 — export VAR=x 会失败

存储卷

• 卷挂载覆盖容器目录中的文件 = 容器原有文件消失
• 宿主机空目录 bind mount = 容器目录变空
• ./path 相对于 compose 文件，不是当前工作目录
• 命名卷首次挂载时复制容器内容 — 之后不再同步

网络

• 默认 bridge 网络无容器间 DNS — 名称无法解析
• 容器名 ≠ 服务名 — 用服务名做 DNS
• network_mode: host 禁用 compose 全部网络 — 不仅影响该容器
• 外部网络不会自动创建 — 必须预先存在

构建

• build: . 使用 Dockerfile，build: { dockerfile: X } 指定其他文件
• 构建上下文完整发送给 daemon — 大目录 = 构建慢
• image: + build: 同时存在 = 构建并打上该标签名
• 不同 compose 项目的构建缓存默认不共享

健康检查

• compose 中的 healthcheck 会覆盖 Dockerfile 中的
• start_period 不计入重试次数 — 前几秒的失败被忽略
• test: ["CMD", "curl", ...] — CMD 用 exec，CMD-SHELL 用 shell
• Exit code 0 = healthy，1 = unhealthy，2 = reserved（不要用）