docker-compose.yml文件必须包含version、services及每个service的image字段；version指定语法版本（如"3.8"），services定义服务列表，image指定容器镜像，缺一不可。
docker-compose up -d 是唯一需要记住的启动命令，但直接敲它之前，必须确保 docker-compose.yml 文件写对了——否则不是“一键启动”，而是“一键报错”。
docker-compose.yml 文件必须包含哪些字段？
一个能跑起来的最小配置，至少要定义 version、services 和每个 service 的 image。漏掉任意一个，docker-compose up 会直接报错退出。
常见错误现象：
-
ERROR: Version in "./docker-compose.yml" is unsupported→version写成了"3"或"2.4"，Docker 24+ 默认只认"3.8"或"3.9"（推荐用"3.8"） -
ERROR: Service 'web' has no image set→ 某个 service 下没写image:，或者缩进错了（YAML 对空格敏感，必须用两个空格缩进） - 容器启动后立刻退出 → 大概率是镜像没指定前台进程，比如
nginx忘了加command: nginx -g "daemon off;"
depends_on 只控制启动顺序，不等服务就绪
depends_on 常被误认为“等数据库 ready 再启应用”，其实它只保证容器进程启动，不检查端口是否监听、服务是否可连。PostgreSQL 容器可能已运行，但初始化还没完成，这时 Web 服务去连就会失败。
正确做法：
- 删掉
depends_on（它只是个弱依赖，实际意义有限） - 在应用代码里加重试逻辑，或用
healthcheck+condition: service_healthy替代 - 示例：给 db 加健康检查
db:
image: postgres:14
environment:
POSTGRES_DB: myapp
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 30s
timeout: 10s
retries: 5
web:
image: my-web-app
depends_on:
db:
condition: service_healthy
docker-compose up -d 启动后，怎么确认服务真在跑？
别只看 docker-compose ps 显示 Up 就以为万事大吉。很多容器状态是 Up 2 seconds 然后迅速变成 Exit 1，但终端不会自动滚动回显。
实操建议：
- 首次启动先去掉
-d，用docker-compose up看实时日志流，出错立刻可见 - 启动后立即执行
docker-compose logs -f web（把web换成你的服务名），观察是否有连接拒绝、配置加载失败等关键错误 - 检查端口是否真正监听：
docker port web 8000看是否返回主机映射地址；再用curl http://localhost:8000/health验证业务层响应
卷挂载和网络配置容易被忽略的细节
手动 docker run 时挂载路径写错顶多连不上文件，Compose 里写错可能导致整个服务起不来，而且错误提示非常隐晦。
关键点：
- 本地路径必须是绝对路径，或相对于
docker-compose.yml所在目录的相对路径；./data是合法的，~/data会被当成字面量，找不到目录 - 自定义网络不用显式创建，
docker-compose.yml里不写networks字段，Compose 也会自动建一个默认桥接网，服务间直接用 service 名通信（如http://db:5432） - 如果要用已有网络（比如和其他 Compose 项目互通），必须显式声明：
networks: default: external: name: my-shared-net
真正卡住人的从来不是“怎么启动”，而是启动后发现服务看似在跑、实际不工作，又不知道从哪查起。日志、健康检查、端口验证这三步，比写对 YAML 更重要。
