linux下配置docker-compose.yml需严格遵循yaml语法（空格缩进、冒号后空格、双引号包裹特殊字符）和compose结构（必含version与services），常用字段如image、ports、volumes等须按规范书写，并通过docker-compose config验证。
在 Linux 上配置 Docker Compose 模板文件（docker-compose.yml），核心是遵循 YAML 语法规范并符合 Docker Compose 的服务定义结构。写错缩进、字段名拼写错误或版本不匹配，都会导致 docker-compose up 失败。
YAML 基础规范必须遵守
YAML 对空白敏感，不支持 Tab 缩进，只允许空格；常见错误包括：
- 用 Tab 替代 2 或 4 个空格 → 报错
found character '\t' - 键名后缺少冒号或冒号后没加空格 → 如
image:nginx应为image: nginx - 字符串含特殊字符（如
:、{、[）未加引号 → 推荐统一用双引号包裹值，例如command: "sh -c 'echo hello'" - 布尔值写成
true/false即可，不要加引号；但"true"会被当字符串处理
docker-compose.yml 必须包含的顶层字段
一个最小可用模板需包含 version 和 services，其他如 volumes、networks 按需添加：
-
version：指定 Compose 文件格式版本，推荐
"3.8"（兼容 Docker 20.10+，功能稳定）；避免用2.x（已逐步弃用） -
services：定义容器服务列表，每个服务名是自定义标识（如
web、db），下级字段描述该容器行为 -
services.
至少含 image或build字段；否则启动报错Service 'xxx' has neither an image nor a build context
常用服务字段与正确写法示例
以下字段在实际配置中高频出现，注意格式和语义：
-
image：指定镜像名，支持带标签，如
image: nginx:1.25-alpine -
ports：宿主机:容器端口映射，写成字符串数组，如
ports: ["8080:80", "443:443"]；单个映射不能写成ports: 8080:80 -
volumes：绑定挂载优先用绝对路径，如
volumes: ["./data:/app/data:rw"]；命名卷需提前docker volume create myvol或在文件中声明volumes:区块 -
environment：环境变量可写数组或字典，推荐字典更清晰：
environment:DB_HOST: "mysql"DEBUG: "1" - depends_on：仅控制启动顺序，不等待依赖服务“就绪”；需配合健康检查或应用层重试逻辑
验证与调试技巧
写完文件别急着 up，先做两步检查：
- 运行
docker-compose config：校验 YAML 语法 + 解析最终配置（含继承、变量替换），输出即生效配置；报错会明确提示行号和原因 - 使用
docker-compose config --quiet可静默验证（适合 CI 脚本） - 变量替换用
${VAR_NAME}，从 shell 环境或.env文件读取；.env文件每行KEY=VALUE，无需引号，且不支持注释 - 多环境配置可拆分
docker-compose.prod.yml，用docker-compose -f docker-compose.yml -f docker-compose.prod.yml up合并加载
